升级指南

• 从 9.x 升级到 10.0

#高影响变化

#中等影响变化

#低影响变化

#从 9.x 升级到 10.0

预计升级时间：10 分钟

Note
我们试图记录每一个可能的破坏性变化。由于其中一些重大更改位于框架的模糊部分，因此这些更改中只有一部分可能会实际影响您的应用程序。想节省时间？您可以使用Laravel 转变 帮助自动化您的应用程序升级。

#更新依赖

影响的可能性：高

需要 PHP 8.1.0

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

需要 Composer 2.2.0

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

作曲家依赖

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

如果您要从 2.x 版本系列升级到 Sanctum 3.x，请参阅圣殿升级指南.

此外，如果您想使用PHP单元10, 你应该删除processUncoveredFiles 属性来自<coverage> 您的应用程序的一部分phpunit.xml 配置文件。然后，更新应用程序中的以下依赖项composer.json 文件：

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

最低稳定性

你应该更新minimum-stability 在您的应用程序中设置composer.json 归档到stable:

"minimum-stability": "stable",

#Application

公共路径绑定

影响的可能性：低

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

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

#Authorization

#这registerPolicies 方法

影响的可能性：低

这registerPolicies 的方法AuthServiceProvider 现在由框架自动调用。因此，您可以从boot 你的应用程序的方法AuthServiceProvider.

#Cache

Redis 缓存标签

影响的可能性：中等

雷迪斯缓存标签 支持已被重写以获得更好的性能和存储效率。在以前的 Laravel 版本中，当使用 Redis 作为应用程序的缓存驱动程序时，陈旧的缓存标签会在缓存中累积。

然而，为了正确地修剪陈旧的缓存标签条目，Laravel 的新cache:prune-stale-tags 工匠命令应该是scheduled 在你的应用程序中App\Console\Kernel 班级：

$schedule->command('cache:prune-stale-tags')->hourly();

#Database

数据库表达式

影响的可能性：中等

数据库“表达式”（通常通过DB::raw) 在 Laravel 10.x 中被重写以在未来提供额外的功能。值得注意的是，语法的原始字符串值现在必须通过表达式的getValue(Grammar $grammar) 方法。将表达式转换为字符串使用(string) 不再受支持。

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

use Illuminate\Support\Facades\DB;

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

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

查询异常构造函数

影响的可能性：非常低

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

ULID 列

影响的可能性：低

当迁移调用ulid 没有任何参数的方法，列现在将被命名ulid.在以前的 Laravel 版本中，不带任何参数调用此方法会创建一个错误命名的列uuid:

$table->ulid();

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

$table->ulid('ulid');

#Eloquent

模型“日期”属性

影响的可能性：中等

Eloquent 模型已弃用$dates 财产已被删除。您的应用程序现在应该使用$casts财产：

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

关系getBaseQuery 方法

影响的可能性：非常低

这getBaseQuery 上的方法Illuminate\Database\Eloquent\Relations\Relation 类已重命名为toBase.

#Localization

语言目录

影响的可能性：无

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

php artisan lang:publish

#Logging

独白 3

影响的可能性：中等

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

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

#Queues

这Bus::dispatchNow 方法

影响的可能性：低

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

#Routing

中间件别名

影响的可能性：可选

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

速率限制器返回值

影响的可能性：低

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

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

$value; // ['example']

这Redirect::home 方法

影响的可能性：非常低

弃用的Redirect::home 方法已被删除。相反，您的应用程序应该重定向到一个明确命名的路由：

return Redirect::route('home');

#Testing

服务模拟

影响的可能性：中等

弃用的MocksApplicationServices 特征已从框架中删除。这种特性提供了测试方法，例如expectsEvents,expectsJobs， 和expectsNotifications.

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

#Validation

闭包验证规则消息

影响的可能性：非常低

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

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

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

#Miscellaneous

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

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