升级指南

高影响变化

中等影响变化

模型与 UUIDv7

低影响变化

从 11.x 升级到 12.0

预计升级时间：5 分钟

我们试图记录所有可能的破坏性更改。由于其中一些破坏性更改位于框架中不为人知的部位，因此只有一部分更改可能真正影响您的应用程序。想节省时间吗？您可以使用 Laravel Shift 来帮助自动化您的应用程序升级。

更新依赖

影响可能性：高

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

laravel/framework 到 ^12.0
phpunit/phpunit 到 ^11.0
pestphp/pest 到 ^3.0

Carbon 3

影响可能性：低

对 Carbon 2.x 的支持已移除。所有 Laravel 12 应用程序现在都需要 Carbon 3.x。

更新 Laravel 安装器

如果您正在使用 Laravel 安装器 CLI 工具来创建新的 Laravel 应用程序，您应该更新您的安装器安装以与 Laravel 12.x 和新的 Laravel 入门套件兼容。如果您最初是通过 composer global require 安装的 Laravel 安装器，您可以使用 composer global update 更新安装器：

composer global update laravel/installer

如果您最初是通过 php.new 安装 PHP 和 Laravel 的，您可以简单地为您的操作系统重新运行 php.new 安装命令，以安装最新版本的 PHP 和 Laravel 安装器：

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

# Run as administrator...
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"

或者，如果您正在使用 Laravel Herd 的捆绑 Laravel 安装器副本，您应该将您的 Herd 安装更新到最新版本。

身份验证

更新的 `DatabaseTokenRepository` 构造函数签名

影响可能性：非常低

Illuminate\Auth\Passwords\DatabaseTokenRepository 类的构造函数现在期望 expires 参数以秒为单位给出，而不是分钟。

并发

并发结果索引映射

影响可能性：低

当使用关联数组调用 Concurrency::run 方法时，并发操作的结果现在会以其关联的键返回：

$result = Concurrency::run([
    'task-1' => fn () => 1 + 1,
    'task-2' => fn () => 2 + 2,
]);
 
// ['task-1' => 2, 'task-2' => 4]

容器

容器类依赖解析

影响可能性：低

依赖注入容器现在在解析类实例时会尊重类属性的默认值。如果您之前依赖容器在没有默认值的情况下解析类实例，您可能需要调整您的应用程序以适应这种新行为：

class Example
{
    public function __construct(public ?Carbon $date = null) {}
}
 
$example = resolve(Example::class);
 
// <= 11.x
$example->date instanceof Carbon;
 
// >= 12.x
$example->date === null;

数据库

多模式数据库检查

影响可能性：低

Schema::getTables()、Schema::getViews() 和 Schema::getTypes() 方法现在默认包含来自所有模式的结果。您可以传递 schema 参数，仅检索给定模式的结果：

// 所有模式上的所有表...
$tables = Schema::getTables();
 
// 'main' 模式上的所有表...
$tables = Schema::getTables(schema: 'main');
 
// 'main' 和 'blog' 模式上的所有表...
$tables = Schema::getTables(schema: ['main', 'blog']);

Schema::getTableListing() 方法现在默认返回包含模式限定的表名。您可以传递 schemaQualified 参数来根据需要更改行为：

$tables = Schema::getTableListing();
// ['main.migrations', 'main.users', 'blog.posts']
 
$tables = Schema::getTableListing(schema: 'main');
// ['main.migrations', 'main.users']
 
$tables = Schema::getTableListing(schema: 'main', schemaQualified: false);
// ['migrations', 'users']

db:table 和 db:show 命令现在输出所有模式的结果，就像 PostgreSQL 和 SQL Server 一样。

更新的 `Blueprint` 构造函数签名

影响可能性：非常低

Illuminate\Database\Schema\Blueprint 类的构造函数现在期望 Illuminate\Database\Connection 的实例作为其第一个参数。

Eloquent

模型与 UUIDv7

影响可能性：中等

HasUuids trait 现在返回与 UUID 规范第 7 版（有序 UUID）兼容的 UUID。如果您想继续为模型的 ID 使用有序的 UUIDv4 字符串，您现在应该使用 HasVersion4Uuids trait：

- use Illuminate\Database\Eloquent\Concerns\HasUuids; 
+ use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids;

HasVersion7Uuids trait 已被移除。如果您之前使用此 trait，您应该改用 HasUuids trait，它现在提供了相同的行为。

请求

嵌套数组请求合并

影响可能性：低

$request->mergeIfMissing() 方法现在允许使用“点”符号合并嵌套数组数据。如果您之前依赖此方法来创建包含键的“点”符号版本 user.last_name 的顶级数组键，您可能需要调整您的应用程序以适应这种新行为：

$request->mergeIfMissing([
    'user.last_name' => 'Otwell',
]);

存储

本地文件系统磁盘默认根路径

影响可能性：低

如果您的应用程序没有在文件系统配置中明确定义 local 磁盘，Laravel 现在将把本地磁盘的根目录默认为 storage/app/private。在以前的版本中，这默认为 storage/app。因此，对 Storage::disk('local') 的调用将读写 storage/app/private，除非另有配置。要恢复以前的行为，您可以手动定义 local 磁盘并设置所需的根路径。

验证

图片验证现在排除 SVG

影响可能性：低

image 验证规则默认不再允许 SVG 图片。如果您在使用 image 规则时想允许 SVG，您必须明确允许它们：

use Illuminate\Validation\Rules\File;
 
'photo' => 'required|image:allow_svg'
 
// 或...
'photo' => ['required', File::image(allowSvg: true)],

其他

我们还鼓励您查看 laravel/laravel GitHub 仓库中的更改。虽然其中许多更改不是必需的，但您可能希望使这些文件与您的应用程序保持同步。其中一些更改将在此升级指南中介绍，但其他更改（例如对配置文件或注释的更改）将不会。您可以使用 GitHub 比较工具轻松查看更改，并选择对您重要的更新。

发布记录

贡献指南