ミライトアドベントカレンダー 23日目の記事です。

22日目はぶっちの文章を書くのが苦手だった私が、伝わる文章を書くために意識するようになったこと
という記事でした。

社内案件で PHP 8.1 → 8.4 / Laravel 9 → 12 を段階的にアップデートしました。
この記事は「やったこと」の記録ではなく、アップデート作業を他の人に振れるように再現手順と検証を最低限の内容ですがまとめたものです。

主にアップデートするもの

PHP: 8.1 → 8.4
Composer: 2.2 → 2.9
Laravel: 9 → 12
PHPUnit: 9.6 → 12.5

互換性の前提(今回の採用組み合わせ)

ここは「本記事で実際に通した組み合わせ」の記録です。公式要件は各バージョンの composer.json を必ず確認してください。別の組み合わせは検証していません。

段階	Laravel	PHP	Composer	PHPUnit
1	9.x	8.1	2.9	9.6
2	10.x	8.1	2.9	10.5
3	10.x	8.2	2.9	10.5
4	11.x	8.2	2.9	11.5
5	11.x	8.4	2.9	11.5
6	12.x	8.4	2.9	12.5

PHP/Laravel 移行ガイド

プロジェクトで影響する箇所がないか確認します。

PHP移行ガイド

PHPのバージョンアップの変更点は公式が情報をまとめられています。

Laravel移行ガイド

Laravelのバージョンアップの変更点は公式が情報をまとめられています。

アップデート方針

一気に各ライブラリのバージョンを上げてしまうと不具合が出やすいので、一つずつ上げていくと安心です。
まずはComposerを最新に寄せましょう。(Laravel10以降はComposer 2.2+が要件)

おすすめの進め方としてはLaravelを先に段階アップしていき、PHPはLaravelの要件に合わせて段階アップしていくと良いです。

Composer: 2.2 → 2.9
Laravel: 9 → 10
PHP: 8.1 → 8.2
Laravel: 10 → 11
PHP: 8.2 → 8.4
Laravel: 11 → 12

各LaravelがどのPHPバージョンに依存しているかはLaravelのリポジトリのcomposer.jsonを確認しています。

最小検証セット(各ステップで必ず)

「バージョンだけ上げて終わり」にしないための最低ラインです。これが通ることを確認してから次に進みます。

composer.json / lock の整合性: composer validate --strict
実行環境の要件チェック: composer check-platform-reqs
脆弱性の監査: composer audit
テスト: ./vendor/bin/phpunit か php artisan test を通す
最低限の動作確認: 主要な画面やAPIを1〜2本叩く(更新系を含む)

Rectorの導入

Rector は、PHPコードをAST(構文木)で解析して非推奨構文の置き換えやアップグレードに伴う機械的な修正をまとめて適用できるツールです。--dry-run で差分だけ出してレビューしてから適用できるので、アップデート作業の手戻りを減らせます。

Laravel 向けにはコミュニティ拡張の driftingly/rector-laravel があり、Laravel特有の変更(ヘルパーやコンテナ、Factory周りなど)をルールとして提供します。

$ composer require rector/rector --dev
$ composer require driftingly/rector-laravel --dev

$ ./vendor/bin/rector -V
Rector 2.3.0

Rectorの設定は rector.php に記載します。

rector.php

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;
use RectorLaravel\Set\LaravelLevelSetList;
use Rector\PHPUnit\Set\PHPUnitSetList;

return RectorConfig::configure()
    ->withPaths([
        __DIR__.'/app',
        __DIR__.'/config',
        __DIR__.'/database',
        __DIR__.'/routes',
        __DIR__.'/tests',
    ])
    ->withSets([
        LevelSetList::UP_TO_PHP_81,
        LaravelLevelSetList::UP_TO_LARAVEL_90,
        PHPUnitSetList::PHPUNIT_90,
    ]);

PHP, Laravel, PHPUnitのルールセットが用意されています。
まず、現行バージョンで非推奨な書き方があればRectorで修正します。

# テスト
$ ./vendor/bin/rector --dry-run

# 適用
$ ./vendor/bin/rector

アップデート手順

いよいよアップデート作業を行います。
順序のおさらいですが、上で決めたようにこの順番で行きます。

Composer: 2.2 → 2.9
Laravel: 9 → 10
PHP: 8.1 → 8.2
Laravel: 10 → 11
PHP: 8.2 → 8.4
Laravel: 11 → 12

各ステップの最後に「最小検証セット」を必ず実行します。
判断がブレないように、目的/判断基準/失敗時の次手を先に固定します。

ステップ	目的	判断基準	失敗時の次手
Composer: 2.2 → 2.9	最新に揃える	最小検証セットが通る	`composer diagnose` / `composer prohibits` でブロッカー特定、更新/ピン留め
Laravel: 9 → 10	フレームワーク更新	最小検証セットが通る	公式ガイド確認、互換パッケージ更新/代替
PHP: 8.1 → 8.2	Laravel 10要件に合わせる	最小検証セットが通る	移行ガイド確認、Rectorで非推奨対応
Laravel: 10 → 11	フレームワーク更新	最小検証セットが通る	公式ガイド確認、DB/スキーマ周りを重点確認
PHP: 8.2 → 8.4	Laravel 12要件に合わせる	最小検証セットが通る	移行ガイド確認、互換性の問題を早めに確認する
Laravel: 11 → 12	フレームワーク更新	最小検証セットが通る	公式ガイド確認、互換パッケージ更新/代替

Composer: 2.2 → 2.9

Composerは2.2以上であれば要件は満たします。
特別な理由がなければ最新の2.x(本記事では2.9)に上げ、据え置くなら2.2系の最新パッチに揃える、で十分です。

Laravel: 9 → 10

公式のアップグレードガイドに沿って対応する。
https://readouble.com/laravel/10.x/ja/upgrade.html

composer.json

-        "laravel/framework": "^9.52",
+        "laravel/framework": "^v10.49",
-        "phpunit/phpunit": "^9.6",
+        "phpunit/phpunit": "^10.5",

composer.json に Laravel と PHPUnit のバージョンを上げる。

$ composer update

※ 互換性のないパッケージがある場合は、Composerがエラーを出力します。
その際は、対象パッケージの最新版を探すか、代替のパッケージの利用を検討する。

rector.php

-        LaravelLevelSetList::UP_TO_LARAVEL_90,
+        LaravelLevelSetList::UP_TO_LARAVEL_100,
-        PHPUnitSetList::PHPUNIT_90,
+        PHPUnitSetList::PHPUNIT_100,

# テスト
$ ./vendor/bin/rector --dry-run

# 適用
$ ./vendor/bin/rector

手動修正
- 依存パッケージのアップデート > 最低安定度
  - composer.json minimum-stability の属性を削除

特にハマりどころはなかったです。

PHP: 8.1 → 8.2

公式の移行ガイドに沿って対応する。
https://www.php.net/manual/ja/migration82.php

composer.json

-        "php": "^8.1",
+        "php": "^8.2",

$ composer update

rector.php

-        LevelSetList::UP_TO_PHP_81,
+        LevelSetList::UP_TO_PHP_82,

# テスト
$ ./vendor/bin/rector --dry-run

# 適用
$ ./vendor/bin/rector

Rectorが適用したルール
- FunctionFirstClassCallableRector
- ReadOnlyClassRector

特にハマりどころなく、手で修正した箇所もなし。

Laravel: 10 → 11

公式のアップグレードガイドに沿って対応する。
https://readouble.com/laravel/11.x/ja/upgrade.html

composer.json

-        "laravel/framework": "^v10.49",
+        "laravel/framework": "^v11.46",
-        "phpunit/phpunit": "^10.5",
+        "phpunit/phpunit": "^11.5",

composer.json に Laravel と PHPUnit のバージョンを上げる。

$ composer update

※ 互換性のないパッケージがある場合は、Composerがエラーを出力します。
その際は、対象パッケージの最新版を探すか、代替のパッケージの利用を検討する。

rector.php

-        LaravelLevelSetList::UP_TO_LARAVEL_100,
+        LaravelLevelSetList::UP_TO_LARAVEL_110,
-        PHPUnitSetList::PHPUNIT_100,
+        PHPUnitSetList::PHPUNIT_110,

# テスト
$ ./vendor/bin/rector --dry-run

# 適用
$ ./vendor/bin/rector

Laravel: 10 → 11: 手動修正まとめ

データベース > Doctrine DBALの削除
- Doctrine DBALのlistTableNamesメソッドを使っていたのをSchema::getTables()に移行
データベース > カラムの変更
- Laravel11以降はDoctrine DBALに依存しなくなったため、カラム変更のマイグレーションがある場合、php artisan schema:dumpしてマイグレーションの圧縮が必要

このプロジェクトでは全テーブルの一覧が欲しい機能が一つあったので、そこだけ直しました。リリース済みのプロジェクトでカラム変更マイグレーションがあるなら、圧縮はほぼ必要になります。

PHP: 8.2 → 8.4

公式の移行ガイドに沿って対応する。
https://www.php.net/manual/ja/migration83.php
https://www.php.net/manual/ja/migration84.php

composer.json

-        "php": "^8.2",
+        "php": "^8.4",

$ composer update

rector.php

-        LevelSetList::UP_TO_PHP_82,
+        LevelSetList::UP_TO_PHP_84,

# テスト
$ ./vendor/bin/rector --dry-run

# 適用
$ ./vendor/bin/rector

特にハマりどころなく、手で修正した箇所もなし。

Laravel: 11 → 12

公式のアップグレードガイドに沿って対応する。
https://readouble.com/laravel/12.x/ja/upgrade.html

composer.json

-        "laravel/framework": "^v11.46",
+        "laravel/framework": "^v12.35",
-        "phpunit/phpunit": "^11.5",
+        "phpunit/phpunit": "^12.5",

composer.json に Laravel と PHPUnit のバージョンを上げる。

$ composer update

※ 互換性のないパッケージがある場合は、Composerがエラーを出力します。
その際は、対象パッケージの最新版を探すか、代替のパッケージの利用を検討する。

rector.php

-        LaravelLevelSetList::UP_TO_LARAVEL_110,
+        LaravelLevelSetList::UP_TO_LARAVEL_120,
-        PHPUnitSetList::PHPUNIT_110,
+        PHPUnitSetList::PHPUNIT_120,

# テスト
$ ./vendor/bin/rector --dry-run

# 適用
$ ./vendor/bin/rector

その他

コードスタイルチェックCI

バージョンアップ対応の修正漏れと今後の追加で非推奨コードが入らないようにGitHub Actionsワークフローでチェックするようにしました。

.github/workflows/laravel-style-test.yml

name: Laravel Style Test
on:
  pull_request:
jobs:
  code-style-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          tools: composer:v2.9.2
      - name: Install Dependencies
        run: composer install
      - name: Rector Test
        run: ./vendor/bin/rector --dry-run

ミライトアドベントカレンダー 24日目は FrozenVoiceさんの Rails4保守開発でAIを“読む/直す”に使った所感という記事です。