Laravel 中文文档

主题

全部文档

发行说明 ​

版本策略 ​

Laravel 及其其他官方包遵循 语义化版本。框架大版本大约每年发布一次（约第一季度），小版本与补丁版本可能每周都会发布。小版本与补丁版本绝不应包含破坏性变更。

在应用或包中引用 Laravel 框架或其组件时，应始终使用类似 ^12.0 的版本约束，因为 Laravel 大版本确实会包含破坏性变更。不过我们会尽力确保你能在一天甚至更短时间内完成升级。

命名参数 ​

命名参数 不在 Laravel 向后兼容指南的覆盖范围内。我们可能在必要时重命名函数参数以改进代码库。因此，调用 Laravel 方法时使用命名参数应格外谨慎，并明白参数名未来可能变更。

支持策略 ​

所有 Laravel 版本均提供 18 个月的缺陷修复与 2 年的安全修复。对于包括 Lumen 在内的其他附加库，仅最新主版本会收到缺陷修复。此外，请查阅 Laravel 支持的数据库版本。

VersionPHP (*)ReleaseBug Fixes UntilSecurity Fixes Until
98.0 - 8.2February 8th, 2022August 8th, 2023February 6th, 2024
108.1 - 8.3February 14th, 2023August 6th, 2024February 4th, 2025
118.2 - 8.4March 12th, 2024September 3rd, 2025March 12th, 2026
128.2 - 8.4February 24th, 2025August 13th, 2026February 24th, 2027
已终止支持
仅安全修复

(*) 支持的 PHP 版本

Laravel 11 ​

Laravel 11 在 Laravel 10.x 的改进之上，引入了精简的应用结构、按秒限流、健康检查路由、平滑的加密密钥轮换、队列测试改进、Resend 邮件传输、Prompt 校验器集成、新的 Artisan 命令等。此外还发布了官方可扩展 WebSocket 服务器 Laravel Reverb，为应用提供强大的实时能力。

PHP 8.2 ​

Laravel 11.x 要求最低 PHP 版本为 8.2。

精简的应用结构 ​

Laravel 精简应用结构由 Taylor Otwell 与 Nuno Maduro 开发。

Laravel 11 为新 Laravel 应用引入了精简的应用结构，现有应用无需任何改动。新结构旨在提供更精简、更现代的体验，同时保留 Laravel 开发者已熟悉的许多概念。下面我们讨论新应用结构的亮点。

应用引导文件 ​

bootstrap/app.php 已焕新为以代码优先的应用配置文件。你可在此自定义应用的路由、中间件、服务提供者、异常处理等。该文件统一了此前分散在应用目录结构中的多种高层行为设置：

php
return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        //
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

服务提供者 ​

默认 Laravel 应用结构此前包含五个服务提供者，而 Laravel 11 仅保留单一的 AppServiceProvider。此前各服务提供者的功能已并入 bootstrap/app.php、由框架自动处理，或可放在应用的 AppServiceProvider 中。

例如，事件发现现已默认启用，基本无需再手动注册事件与监听器。若仍需手动注册事件，可直接在 AppServiceProvider 中完成。同理，此前在 AuthServiceProvider 中注册的路由模型绑定或授权 gate，也可改在 AppServiceProvider 中注册。

按需启用的 API 与广播路由 ​

api.php 与 channels.php 路由文件默认不再存在，因为许多应用并不需要它们。需要时可使用简单的 Artisan 命令创建：

shell
php artisan install:api

php artisan install:broadcasting

中间件 ​

此前，新建 Laravel 应用包含九个中间件，分别负责认证请求、裁剪输入字符串、校验 CSRF 令牌等任务。

在 Laravel 11 中，这些中间件已移入框架内部，不再增加应用结构的体积。框架新增了用于自定义这些中间件行为的方法，可在应用的 bootstrap/app.php 中调用：

php
->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(
        except: ['stripe/*']
    );

    $middleware->web(append: [
        EnsureUserIsSubscribed::class,
    ])
})

由于所有中间件都可通过应用的 bootstrap/app.php 轻松自定义，因此不再需要单独的 HTTP「内核」类。

任务调度 ​

借助新的 Schedule 门面，可直接在应用的 routes/console.php 中定义计划任务，无需单独的控制台「内核」类：

php
use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')->daily();

异常处理 ​

与路由和中间件一样，异常处理现在也可在应用的 bootstrap/app.php 中自定义，而不再依赖单独的异常处理器类，从而减少新建 Laravel 应用包含的文件数量：

php
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->dontReport(MissedFlightException::class);

    $exceptions->report(function (InvalidOrderException $e) {
        // ...
    });
})

基础 Controller 类 ​

新建 Laravel 应用中的基础控制器已简化：不再继承 Laravel 内部的 Controller 类，并移除了 AuthorizesRequests 与 ValidatesRequests trait；如有需要，可在各个控制器中自行引入：

php
<?php

namespace App\Http\Controllers;

abstract class Controller
{
    //
}

应用默认值 ​

默认情况下，新建 Laravel 应用使用 SQLite 作为数据库，并为会话、缓存与队列使用 database 驱动。这样创建应用后即可立刻开始开发，无需安装额外软件或创建额外数据库迁移。

此外，这些 Laravel 服务的 database 驱动已足够稳健，可在许多生产场景中使用；因此它们为本地与生产环境提供了合理、统一的选择。

Laravel Reverb ​

Laravel Reverb 由 Joe Dixon 开发。

Laravel Reverb 为 Laravel 应用带来极速、可扩展的实时 WebSocket 通信，并与 Laravel Echo 等现有事件广播工具无缝集成。

shell
php artisan reverb:start

此外，Reverb 可通过 Redis 的发布 / 订阅能力进行水平扩展，让你将 WebSocket 流量分散到多台后端 Reverb 服务器，共同支撑单一高并发应用。

关于 Laravel Reverb 的更多信息，请参阅完整的 Reverb 文档。

按秒限流 ​

按秒限流由 Tim MacDonald 贡献。

Laravel 现在为所有限流器（包括 HTTP 请求与队列任务）支持「按秒」限流。此前，Laravel 限流器仅支持「按分钟」粒度：

php
RateLimiter::for('invoices', function (Request $request) {
    return Limit::perSecond(1);
});

关于 Laravel 限流的更多信息，请参阅限流文档。

健康检查路由 ​

健康检查路由由 Taylor Otwell 贡献。

新建 Laravel 11 应用包含 health 路由指令，用于定义简单的健康检查端点，可供第三方应用健康监控服务或 Kubernetes 等编排系统调用。默认该路由为 /up：

php
->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
)

向该路由发起 HTTP 请求时，Laravel 还会派发 DiagnosingHealth 事件，便于你执行与应用相关的额外健康检查。

平滑的加密密钥轮换 ​

平滑的加密密钥轮换由 Taylor Otwell 贡献。

由于 Laravel 会加密所有 Cookie（包括会话 Cookie），几乎每次请求都依赖加密。因此，轮换应用加密密钥会导致所有用户退出登录，且此前密钥加密的数据也无法再解密。

Laravel 11 允许通过 APP_PREVIOUS_KEYS 环境变量，以逗号分隔列表的形式定义应用的先前加密密钥。

加密时，Laravel 始终使用 APP_KEY 环境变量中的「当前」加密密钥。解密时会先尝试当前密钥；若失败，再依次尝试所有先前密钥，直到成功解密为止。

这种平滑解密方式可让用户在加密密钥轮换后仍能不中断地使用应用。

关于 Laravel 加密的更多信息，请参阅加密文档。

自动重新哈希密码 ​

自动密码重哈希由 Stephen Rees-Carter 贡献。

Laravel 默认密码哈希算法为 bcrypt。bcrypt 哈希的「工作因子」可通过 config/hashing.php 配置文件或 BCRYPT_ROUNDS 环境变量调整。

通常，随着 CPU / GPU 算力提升，应逐步提高 bcrypt 工作因子。若提高了应用的 bcrypt 工作因子，Laravel 现在会在用户认证时平滑、自动地重哈希用户密码。

Prompt 校验 ​

Prompt 校验器集成由 Andrea Marco Sartori 贡献。

Laravel Prompts 是一个 PHP 包，可为命令行应用添加美观、易用的表单，具备占位符与验证等类似浏览器的特性。

Laravel Prompts 支持通过闭包进行输入校验：

php
$name = text(
    label: 'What is your name?',
    validate: fn (string $value) => match (true) {
        strlen($value) < 3 => 'The name must be at least 3 characters.',
        strlen($value) > 255 => 'The name must not exceed 255 characters.',
        default => null
    }
);

但在处理大量输入或复杂校验场景时会变得繁琐。因此在 Laravel 11 中，校验 Prompt 输入时可充分发挥 Laravel 校验器 的能力：

php
$name = text('What is your name?', validate: [
    'name' => 'required|min:3|max:255',
]);

队列交互测试 ​

队列交互测试由 Taylor Otwell 贡献。

此前，测试队列任务是否被释放、删除或手动失败既繁琐，又需要自定义队列 fake 与 stub。而在 Laravel 11 中，可使用 withFakeQueueInteractions 方法轻松测试这些队列交互：

php
use App\Jobs\ProcessPodcast;

$job = (new ProcessPodcast)->withFakeQueueInteractions();

$job->handle();

$job->assertReleased(delay: 30);

关于测试队列任务的更多信息，请参阅队列文档。

新的 Artisan 命令 ​

类创建 Artisan 命令由 Taylor Otwell 贡献。

新增了可快速创建类、枚举、接口与 trait 的 Artisan 命令：

shell
php artisan make:class
php artisan make:enum
php artisan make:interface
php artisan make:trait

模型 Cast 改进 ​

模型 Cast 改进由 Nuno Maduro 贡献。

Laravel 11 支持用方法而非属性定义模型的 cast，便于编写精简、流畅的 cast 定义，尤其是带参数的 cast：

php
/**
 * Get the attributes that should be cast.
 *
 * @return array<string, string>
 */
protected function casts(): array
{
    return [
        'options' => AsCollection::using(OptionCollection::class),
                  // AsEncryptedCollection::using(OptionCollection::class),
                  // AsEnumArrayObject::using(OptionEnum::class),
                  // AsEnumCollection::using(OptionEnum::class),
    ];
}

关于属性转换的更多信息，请参阅 Eloquent 文档。

once 函数 ​

once 辅助函数由 Taylor Otwell 与 Nuno Maduro 贡献。

once 辅助函数会执行给定回调，并在请求期间将结果缓存在内存中。之后以相同回调再次调用 once 时，将返回先前缓存的结果：

function random(): int
{
    return once(function () {
        return random_int(1, 1000);
    });
}

random(); // 123
random(); // 123 (cached result)
random(); // 123 (cached result)

关于 once 辅助函数的更多信息，请参阅辅助函数文档。

使用内存数据库测试时的性能提升 ​

内存数据库测试性能提升由 Anders Jenbo 贡献

Laravel 11 在测试中使用 :memory: SQLite 数据库时性能显著提升。为此，Laravel 现在会保留对 PHP PDO 对象的引用并在连接间复用，往往可将总测试运行时间减半。

改进的 MariaDB 支持 ​

改进的 MariaDB 支持由 Jonas Staudenmeir 与 Julius Kiekbusch 贡献

Laravel 11 改进了对 MariaDB 的支持。此前可通过 Laravel 的 MySQL 驱动使用 MariaDB；而 Laravel 11 现已提供专用 MariaDB 驱动，并为该数据库系统提供更好的默认配置。

关于 Laravel 数据库驱动的更多信息，请参阅数据库文档。

数据库检查与改进的 Schema 操作 ​

改进的 Schema 操作与数据库检查由 Hafez Divandari 贡献

Laravel 11 提供了更多数据库 schema 操作与检查方法，包括原生的列修改、重命名与删除。此外还提供高级空间类型、非默认 schema 名称，以及用于操作表、视图、列、索引与外键的原生 schema 方法：

use Illuminate\Support\Facades\Schema;

$tables = Schema::getTables();
$views = Schema::getViews();
$columns = Schema::getColumns('users');
$indexes = Schema::getIndexes('users');
$foreignKeys = Schema::getForeignKeys('users');