Laravel 10.x 中文文档

简体中文

English

简体中文

English

主题

升级指南 ​

高影响变更 ​

中等影响变更 ​

低影响变更 ​

从 9.x 升级到 10.0 ​

预计升级时间：10 分钟 ​

lightbulb

我们尝试记录每一个可能的重大变更。由于这些变更中的一些位于框架的偏僻部分，只有一部分变更可能实际影响您的应用程序。想节省时间？您可以使用 Laravel Shift 来帮助自动化您的应用程序升级。

更新依赖项 ​

影响可能性：高

需要 PHP 8.1.0 ​

Laravel 现在需要 PHP 8.1.0 或更高版本。

需要 Composer 2.2.0 ​

Laravel 现在需要 Composer 2.2.0 或更高版本。

Composer 依赖项 ​

您应该在应用程序的 composer.json 文件中更新以下依赖项：

  • laravel/framework 到 ^10.0
  • laravel/sanctum 到 ^3.2
  • doctrine/dbal 到 ^3.0
  • spatie/laravel-ignition 到 ^2.0
  • laravel/passport 到 ^11.0 (升级指南)
  • laravel/ui 到 ^4.0

如果您从 Sanctum 2.x 升级到 3.x，请查阅 Sanctum 升级指南。

此外，如果您希望使用 PHPUnit 10，您应该从应用程序的 phpunit.xml 配置文件的 <coverage> 部分中删除 processUncoveredFiles 属性。然后，在应用程序的 composer.json 文件中更新以下依赖项：

  • nunomaduro/collision 到 ^7.0
  • phpunit/phpunit 到 ^10.0

最后，检查应用程序使用的任何其他第三方包，并验证您使用的是支持 Laravel 10 的正确版本。

最低稳定性 ​

您应该在应用程序的 composer.json 文件中将 minimum-stability 设置更新为 stable。或者，由于 minimum-stability 的默认值是 stable，您可以从应用程序的 composer.json 文件中删除此设置：

json
"minimum-stability": "stable",

应用程序 ​

公共路径绑定 ​

影响可能性：低

如果您的应用程序通过将 path.public 绑定到容器来自定义其“公共路径”，您应该更新代码以调用 Illuminate\Foundation\Application 对象提供的 usePublicPath 方法：

php
app()->usePublicPath(__DIR__.'/public');

授权 ​

registerPolicies 方法 ​

影响可能性：低

AuthServiceProvider 的 registerPolicies 方法现在由框架自动调用。因此，您可以从应用程序的 AuthServiceProvider 的 boot 方法中删除对此方法的调用。

缓存 ​

Redis 缓存标签 ​

影响可能性：中等

仅建议使用 Cache::tags() 的应用程序使用 Memcached。如果您使用 Redis 作为应用程序的缓存驱动程序，您应该考虑迁移到 Memcached 或使用替代解决方案。

数据库 ​

数据库表达式 ​

影响可能性：中等

Laravel 10.x 中的数据库“表达式”（通常通过 DB::raw 生成）已被重写，以便将来提供更多功能。特别是，语法的原始字符串值现在必须通过表达式的 getValue(Grammar $grammar) 方法检索。不再支持使用 (string) 将表达式转换为字符串。

通常，这不会影响最终用户应用程序；但是，如果您的应用程序手动将数据库表达式转换为字符串使用 (string) 或直接调用表达式的 __toString 方法，您应该更新代码以调用 getValue 方法：

php
use Illuminate\Support\Facades\DB;

$expression = DB::raw('select 1');

$string = $expression->getValue(DB::connection()->getQueryGrammar());

查询异常构造函数 ​

影响可能性：非常低

Illuminate\Database\QueryException 构造函数现在接受一个字符串连接名称作为其第一个参数。如果您的应用程序手动抛出此异常，您应该相应地调整代码。

ULID 列 ​

影响可能性：低

当迁移调用 ulid 方法而不带任何参数时，列现在将被命名为 ulid。在 Laravel 的早期版本中，调用此方法而不带任何参数会创建一个错误命名为 uuid 的列：

php
$table->ulid();

要在调用 ulid 方法时显式指定列名，您可以将列名传递给该方法：

php
$table->ulid('ulid');

Eloquent ​

模型 "Dates" 属性 ​

影响可能性：中等

Eloquent 模型的已弃用 $dates 属性已被移除。您的应用程序现在应该使用 $casts 属性：

php
protected $casts = [
    'deployed_at' => 'datetime',
];

本地化 ​

语言目录 ​

影响可能性：无

虽然与现有应用程序无关，但 Laravel 应用程序骨架默认不再包含 lang 目录。相反，在编写新的 Laravel 应用程序时，可以使用 lang:publish Artisan 命令发布：

shell
php artisan lang:publish

日志记录 ​

Monolog 3 ​

影响可能性：中等

Laravel 的 Monolog 依赖项已更新为 Monolog 3.x。如果您在应用程序中直接与 Monolog 交互，您应该查看 Monolog 的 升级指南。

如果您使用第三方日志服务，如 BugSnag 或 Rollbar，您可能需要将这些第三方包升级到支持 Monolog 3.x 和 Laravel 10.x 的版本。

队列 ​

Bus::dispatchNow 方法 ​

影响可能性：低

已弃用的 Bus::dispatchNow 和 dispatch_now 方法已被移除。相应地，您的应用程序应该使用 Bus::dispatchSync 和 dispatch_sync 方法。

dispatch() 助手返回值 ​

调用不实现 Illuminate\Contracts\Queue 的类的 dispatch 以前会返回类的 handle 方法的结果。然而，现在将返回一个 Illuminate\Foundation\Bus\PendingBatch 实例。您可以使用 dispatch_sync() 来复制以前的行为。

路由 ​

中间件别名 ​

影响可能性：可选

在新的 Laravel 应用程序中，App\Http\Kernel 类的 $routeMiddleware 属性已重命名为 $middlewareAliases 以更好地反映其用途。您可以在现有应用程序中重命名此属性，但这不是必需的。

速率限制器返回值 ​

影响可能性：低

调用 RateLimiter::attempt 方法时，提供的闭包返回的值现在将由该方法返回。如果没有返回任何内容或返回 null，attempt 方法将返回 true：

php
$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

Redirect::home 方法 ​

影响可能性：非常低

已弃用的 Redirect::home 方法已被移除。相应地，您的应用程序应该重定向到一个显式命名的路由：

php
return Redirect::route('home');

测试 ​

服务模拟 ​

影响可能性：中等

已弃用的 MocksApplicationServices trait 已从框架中移除。此 trait 提供了测试方法，如 expectsEvents、expectsJobs 和 expectsNotifications。

如果您的应用程序使用这些方法，我们建议您过渡到 Event::fake、Bus::fake 和 Notification::fake。您可以在尝试模拟的组件的相应文档中了解有关通过伪造进行模拟的更多信息。

验证 ​

闭包验证规则消息 ​

影响可能性：非常低

在编写基于闭包的自定义验证规则时，多次调用 $fail 回调现在将消息附加到数组中，而不是覆盖先前的消息。通常，这不会影响您的应用程序。

此外，$fail 回调现在返回一个对象。如果您以前为验证闭包的返回类型进行类型提示，这可能需要您更新类型提示：

php
public function rules()
{
    'name' => [
        function ($attribute, $value, $fail) {
            $fail('validation.translation.key')->translate();
        },
    ],
}

验证消息和闭包规则 ​

影响可能性：非常低

以前，您可以通过向闭包验证规则中注入的 $fail 回调提供一个数组来将失败消息分配给不同的键。然而，您现在应该将键作为第一个参数提供，并将失败消息作为第二个参数：

php
Validator::make([
    'foo' => 'string',
    'bar' => [function ($attribute, $value, $fail) {
        $fail('foo', 'Something went wrong!');
    }],
]);

表单请求 After 方法 ​

影响可能性：非常低

在表单请求中，after 方法现在由 Laravel 保留。如果您的表单请求定义了一个 after 方法，该方法应重命名或修改以利用 Laravel 表单请求的新“验证后”功能。

杂项 ​

我们还鼓励您查看 laravel/laravel GitHub 仓库 中的更改。虽然许多这些更改不是必需的，但您可能希望将这些文件与您的应用程序保持同步。本升级指南将涵盖其中一些更改，但其他更改，如配置文件或注释的更改，将不会。

您可以使用 GitHub 比较工具 轻松查看更改，并选择哪些更新对您重要。然而，GitHub 比较工具显示的许多更改是由于我们组织采用了 PHP 原生类型。这些更改是向后兼容的，并且在迁移到 Laravel 10 时采用它们是可选的。

版权所有 © 2024-2025 laravel.wiki