升级指南
从 9.x 升级到 10.0
预计升级时间:10分钟
我们试图记录每一个可能出现的破坏性改变。由于一些这些破坏性改变出现在框架的偏僻部分,因此只有部分改变可能会影响您的应用程序。想节省时间吗?您可以使用 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
spatie/laravel-ignition
至^2.0
如果您希望使用 PHPUnit 10,您应该从应用程序的 phpunit.xml
配置文件的 <coverage>
部分中删除 processUncoveredFiles
属性。然后,您应该在应用程序的 composer.json
文件中更新以下依赖项:
nunomaduro/collision
至^7.0
phpunit/phpunit
至^10.0
最后,请检查应用程序使用的任何其他第三方包,并验证您正在使用适用于 Laravel 10 支持的正确版本。
最小稳定性
您应该将应用程序的 composer.json
文件中的最小稳定性设置更新为 stable
:
"minimum-stability": "stable",
应用程序
公共路径绑定
影响可能性:低
如果您的应用程序通过将 path.public
绑定到容器来自定义其“public path”,则应该更新您的代码以调用 Illuminate\Foundation\Application
对象提供的 usePublicPath
方法:
app()->usePublicPath(__DIR__.'/public');
授权
registerPolicy 方法
影响可能性:低
现在,框架会自动调用 AuthServiceProvider
的 registerPolicies
方法。因此,您可以从应用程序的 AuthServiceProvider
的 boot
方法中删除对此方法的调用。
缓存
Redis 缓存标签
影响可能性:中
为了更好地提高性能和存储效率,Redis 缓存标签支持已被重写。在之前的 Laravel 版本中,使用 Redis 作为应用程序缓存驱动程序时,过期的缓存标签会在缓存中积累。
但是,为了正确地修剪过期的缓存标签条目,您应该在应用程序的 App\Console\Kernel
类中调度 Laravel 的新 cache:prune-stale-tags
Artisan 命令:
$schedule->command('cache:prune-stale-tags')->hourly();
数据库
数据库表达式
影响可能性:中
数据库“表达式”(通常是通过 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());
Query Exception Constructor
影响可能性:非常低
Illuminate\Database\QueryException
构造函数现在将字符串连接名称作为其第一个参数接受。如果您的应用程序手动抛出此异常,则应相应地调整您的代码。
ULID 列
影响可能性:低
当迁移调用 ulid
方法而没有任何参数时,列现在将被命名为 ulid
。在 Laravel 的早期版本中,调用此方法而没有任何参数会误将列命名为 uuid
:
$table->ulid();
要在调用 ulid
方法时显式指定列名,可以将列名传递给方法:
$table->ulid('ulid');
Eloquent
模型的 "Dates" 属性
影响可能性:中
Eloquent 模型的 $dates
属性已弃用并已被删除。您的应用程序现在应该使用 $casts
属性:
protected $casts = [ 'deployed_at' => 'datetime', ];
Relation getBaseQuery 方法
影响可能性:非常低
Illuminate\Database\Eloquent\Relations\Relation
类上的 getBaseQuery
方法已重命名为 toBase
。
本地化
语言目录
影响可能性:无
尽管与现有应用程序无关,但 Laravel 应用程序骨架现在默认不再包含 lang
目录。相反,在编写新的 Laravel 应用程序时,可以使用 lang:publish
Artisan 命令进行发布:
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
方法。
路由
中间件别名
影响可能性:可选
在新的 Laravel 应用程序中,App\Http\Kernel
类的 $routeMiddleware
属性已更名为 $middlewareAliases
,以更好地反映其目的。您可以在现有应用程序中更改此属性的名称,但不是必需的。
速率限制器返回值
影响可能性:低
调用 RateLimiter::attempt
方法时,由提供的闭包返回的值现在将由该方法返回。如果未返回任何内容或 null
,则 attempt
方法将返回 true
:
$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);
$value; // ['example']
Redirect::home 方法
影响可能性:极低
已删除弃用的 Redirect::home
方法。而应该使用显式命名的路由来重定向:
return Redirect::route('home');
测试
服务模拟
影响可能性:中等
框架中已删除 MocksApplicationServices
trait。该 trait 提供了测试方法,如 expectsEvents
、expectsJobs
和 expectsNotifications
。
如果您的应用程序使用这些方法,我们建议您转换为 Event::fake
、Bus::fake
和 Notification::fake
。您可以在尝试伪造的组件的相应文档中了解有关伪造的更多信息。
验证
闭包验证规则消息
影响可能性:非常低
在编写基于闭包的自定义验证规则时,多次调用 $fail
回调现在将将消息追加到数组中,而不是覆盖先前的消息。通常,这不会影响您的应用程序。
此外,$fail
回调现在返回一个对象。如果您以前是对验证闭包的返回类型进行类型提示,则可能需要更新类型提示:
public function rules()
{
'name' => [
function ($attribute, $value, $fail) {
$fail('validation.translation.key')->translate();
},
],
}
杂项
我们也鼓励您查看 laravel/laravel GitHub 存储库中的更改。虽然这些更改中的许多不是必需的,但您可能希望将这些文件与您的应用程序保持同步。本升级指南将涵盖其中的一些更改,但其他更改,例如对配置文件或注释的更改,将不在此列。
您可以使用 GitHub 比较工具轻松查看更改,并选择对您重要的更新。但是,GitHub 比较工具显示的许多更改是由于我们组织采用了 PHP 本地类型。这些更改是向后兼容的,迁移到 Laravel 10 期间采用它们是可选的。
No Comments