laravel-upgrade

Laravel 升级

每次将 Laravel 应用升级一个主版本。支持：9→10、10→11、11→12。

工作流

1. 检测当前版本

读取 composer.json，查找 laravel/framework 版本约束：

// Example: "laravel/framework": "^10.0" means Laravel 10.x

确定目标版本（当前版本 + 1）。如果已经使用 Laravel 12，请告知用户当前使用的是受支持的最新版本。

2. 加载升级指南

根据检测到的版本，读取相应的参考文件：

当前版本	目标版本	参考文件
9.x	10.x	references/from-9-to-10.md
10.x	11.x	references/from-10-to-11.md
11.x	12.x	references/from-11-to-12.md

3. 扫描并修复

针对指南中的每项破坏性变更，扫描代码库并应用修复：

高影响（始终检查）：

• composer.json 依赖版本
• PHP 版本要求
• 使用已弃用方法的数据库迁移

中等影响（检查相关文件）：

• 模型 $dates 属性 → $casts（9→10）
• 使用 (string) 强制转换的数据库表达式（9→10）
• 缺少属性的列修改迁移（10→11）
• HasUuids trait 行为变更（11→12）

低影响（发现相关模式时检查）：

• 已弃用的方法调用（Bus::dispatchNow、Redirect::home 等）
• 契约接口变更
• 配置文件更新

4. 更新依赖项

修复代码后，更新 composer.json：

# Update laravel/framework constraint to target version
# Update related packages per upgrade guide
composer update

5. 升级后验证

• 运行 php artisan，确认框架正常启动
• 如果有测试套件，则运行测试
• 检查日志中的弃用警告

常见模式

依赖项更新（所有升级）

搜索 composer.json 中过时的约束，并根据指南更新。

将模型 $dates 改为 $casts（9→10）

// Before
protected $dates = ['deployed_at'];

// After
protected $casts = ['deployed_at' => 'datetime'];

搜索模式：protected \$dates\s*=

数据库表达式强制转换（9→10）

// Before
$string = (string) DB::raw('select 1');

// After
$string = DB::raw('select 1')->getValue(DB::connection()->getQueryGrammar());

列修改（10→11）

现在，使用 ->change() 的迁移必须包含所有修饰符：

// Before (implicit retention)
$table->integer('votes')->nullable()->change();

// After (explicit)
$table->integer('votes')->unsigned()->default(1)->nullable()->change();

HasUuids Trait（11→12）

// Before (ordered UUIDv4)
use Illuminate\Database\Eloquent\Concerns\HasUuids;

// After (if you need UUIDv4 behavior)
use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids;