PHP

Laravel 10 Migration Guide: Checklist & Step‑by‑Step Process

ⓘ本ページはプロモーションが含まれています

もっとスキルを活かしたいエンジニアへ

スポンサードリンク
働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。


スポンサードリンク

移行前の準備と環境チェック

この章では、PHP のバージョン・必須拡張・サーバ構成 が Laravel 10 の動作要件を満たしているかを確認する手順を紹介します。要件が未整合だとインストール時にエラーになるだけでなく、ランタイムで予期せぬ例外が発生するリスクがあります。

PHP バージョンと拡張モジュールの検証

Laravel 10 は PHP >= 8.1 を必須とし、以下の拡張が有効であることを前提に動作します。

必須拡張 用途例
pdo_mysql データベース接続
openssl 暗号化・HTTPS 通信
mbstring マルチバイト文字列処理
tokenizer Blade コンパイル
xml XML パーサ
ctype 文字種判定関数
json JSON エンコード/デコード
bcmath 高精度演算

確認コマンド例

Composer での要件チェック

php artisan env は Laravel に存在しないコマンドです。代わりに Composer のプラットフォーム要件検証 を利用します。

上記を実行すると、現在の PHP バージョンや拡張モジュールが composer.json に記載された要件と照合され、足りないものが一覧で表示されます。これによりローカル・CI 環境双方で同一条件を保証できます。

バックアップとバージョン管理の基本方針

コードだけでなくデータベースや環境設定も含めた 「復元可能な状態」 を作ることが、失敗時の最重要対策です。以下はチームで標準化すべき手順例です。

Git ブランチ戦略

  1. git checkout -b upgrade-to-laravel10
  2. 変更を小粒にコミットし、プルリクエストでレビューを実施
  3. マージ前に CI が全テストをパス していることを必須条件とする

データベース・環境のスナップショット

対象 コマンド例
MySQL ダンプ mysqldump -u $USER -p $DB > backup_$(date +%Y%m%d).sql
Docker イメージ保存 docker save $(docker images -q) -o images_$(date +%Y%m%d).tar

重要ポイント.env ファイルは必ずバックアップし、機密情報は暗号化して保管してください。


依存関係とコードベースのアップデート

Laravel 本体だけでなく、サードパーティーパッケージや自作ヘルパーも Laravel 10 に合わせて調整する必要があります。この章では Composer の操作方法非推奨 API の置き換え を具体的に示します。

Composer での依存関係更新手順

composer.json に Laravel 10 用のバージョン指定を追加し、全パッケージの互換性を同時に解決します。

更新コマンド

  • --with-all-dependencies(短縮形 -W)は、Laravel が依存しているパッケージまで含めてバージョン解決を行うため、「依存関係の衝突」 を防ぎます。
  • 実行前に composer.lock をリポジトリへコミットし、CI でロックファイルが正しく使用されることを確認してください。

トラブルシューティング

このコマンドは、インストールできないパッケージとそのバージョン制約を一覧表示します。問題が判明したら composer.json のバージョン範囲を調整するか、代替パッケージへ切り替えます。

非推奨 API と置き換え例

Laravel 9 → 10 の公式 Upgrade Guide に基づき、代表的な変更点とその対処法をまとめました。抜けや古い情報が残っている可能性があるため、常に最新ドキュメントを参照してください

旧 API 新しい記述例 補足
Str::contains($haystack, $needle) str_contains($haystack, $needle)(PHP ネイティブ) 文字列検索は PHP 標準関数で高速化
Route::cache() (コード上の呼び出し) 不要php artisan route:cache を実行すれば自動的にキャッシュが利用されます コード変更は不要、Artisan コマンドだけで完了
Response::download($path)(第2引数省略時の挙動) $name = basename($path); return response()->download($path, $name); 第2引数が省略されてもファイル名が期待通りになるよう明示的に指定
Response::file($path) の MIME 推測 同様に response()->file($path, ['Content-Type' => mime_content_type($path)]) と明示化 将来的なデフォルト変更に備える

置き換えサンプルコード

ベストプラクティス:非推奨 API の置き換えは、まずテストコードでカバー範囲を確認し、リファクタリング後に CI が全テストを通過することを必須条件とします。


設定・環境変数とマイグレーションの変更点

Laravel 10 では設定ファイルや .env の項目が一部整理されています。ここで 「必ず確認すべき差分」 と、データベーススキーマ変更時の安全な手順を解説します。

.env と config ディレクトリの差分

変更前 (Laravel 9) 変更後 (Laravel 10) 実務上の注意点
APP_DEBUG=true(文字列) 同値だが ブール型にキャスト が内部で行われる 動作に影響は少ないが、手動編集時は true/false をそのまま記述
CACHE_DRIVER=file など デフォルトは redis 推奨 だが CACHE_STORE=redis は任意設定 Redis が利用できる環境では .env に追加するとパフォーマンス向上
MAIL_MAILER=smtp(旧名) キーはそのまま残存、ただし 必須項目 (MAIL_HOST, MAIL_PORT) の抜けが無いか確認 メール送信エラーを防ぐために .env.example と照合
新規追加: QUEUE_CONNECTION=redis(推奨) キューも同様に Redis がデフォルト候補になる キュー駆動のジョブがある場合は接続先を明示

差分自動適用スクリプト(bash)

運用上のコツ:スクリプト実行前に必ず .env をバージョン管理外へコピーし、変更履歴を残すことでロールバックが容易になります。

データベースマイグレーションの安全な実施

Laravel 10 で Schema::renameColumn() が内部的に DB::statement を使用するようになり、一部 MySQL バージョンで テーブルロック が発生しやすくなります。そこで 「コピー → 移行 → 削除」 の三段階手順を推奨します。

カラムリネームの実装例

型変更・カラム属性の更新

change() メソッドは MySQL 8.0 以降で安全に使用できますが、トランザクション内で実行 するとロールバックが容易です。

ベストプラクティス:大規模テーブルはメンテナンスウィンドウを設け、事前にステージング環境でロック時間を測定してから本番へ適用してください。


テストと CI パイプラインでの検証

Laravel 10 に合わせて PHPUnit と Pest のバージョン を更新し、CI 上で自動的にマイグレーションとテストが走る環境を整えます。ここではローカル・CI 両方で必要な設定ポイントと、GitHub Actions の具体例を示します。

PHPUnit と Pest のバージョン合わせ

Laravel 10 は PHPUnit 10 系 が標準で同梱されており、phpunit.xmlAPP_ENV=testing が設定されていることが前提です。Pest を併用する場合は対応バージョンを合わせます。

主な変更点とコード修正例

変更項目 Laravel 9 → 10 の差分 修正例
アサーションシグネチャ assertEquals($expected, $actual, $message = '')厳密比較 に統一 assertSame() を意識してテストを書き直す
Pest のマッチャー expect()->toBeTrue() などはそのまま利用可だが、内部で PHPunit10 の API に依存 バージョンアップ後に警告が出たら公式ドキュメント参照

テストコード例(PHPUnit)

同等の Pest バージョン

GitHub Actions に組み込む移行テストフロー

以下は Pull Request が作成された時点 で Laravel 10 へのアップデートと全テストを実行するワークフローです。

ポイントcomposer require laravel/framework:^10.0 -W を CI でも実行することで、ローカルと同一条件で依存関係の解決が確認できます。マイグレーションはテスト用データベースに対してのみ走らせるので、本番への影響はありません。


本番環境へのデプロイとパフォーマンス最適化

本番リリースでは 「段階的切り替え」「障害時の即時ロールバック」 が不可欠です。ここでは Blue‑Green デプロイの具体手順、そして Laravel 10 で改善されたキャッシュ機構を活かすベンチマーク方法を紹介します。

Blue‑Green デプロイの実装フロー

  1. 環境準備
  2. blue(現行) と green(新バージョン) の 2 套 EC2 / コンテナを同一 VPC に構築。
  3. 両方が同じデータベース/ストレージに接続できることを事前確認。

  4. Green 環境へのデプロイ

  1. ヘルスチェック
  2. /healthz エンドポイントで 200 が返るか、キューが正常に動くかを自動テスト。

  3. トラフィックの段階的切替(例:AWS ALB のターゲットグループ)

  4. 25% → 50% → 100% と徐々にシフトし、エラー率が閾値以下なら次へ進む。

  5. ロールバック手順

  6. 問題検出時は ALB の設定だけで Blue 環境へ戻す。
  7. 必要ならばデータベースのポイントインタイムリカバリ(PITR)を実施。

運用上の注意:マイグレーションが 不可逆 な場合は、Blue‑Green の前に「バックアップ+リバーシブルスクリプト」を必ず用意してください。

キャッシュとパフォーマンスベンチマーク

Laravel 10 では Cache::store('redis') が内部最適化され、php artisan cache:clear の処理も高速化されています。以下の手順で 実測値を取得し改善点を洗い出す ことができます。

ベンチマークツールと計測項目

ツール 測定対象
wrk(HTTP 負荷テスト) 平均応答時間、95 パーセンタイル latency
Laravel Telescope リクエストごとの DB クエリ数・キャッシュヒット率
redis-cli INFO stats キャッシュミス率、メモリ使用率

サンプルコマンド

設定の最適化例

項目 Laravel 9 設定例 Laravel 10 推奨
デフォルトキャッシュドライバ file(デフォルト) redis が推奨、.env で明示的に指定可
キー長制限 255 バイト未満 Redis 使用時は 512 バイトまで拡張可能
タグ付けサポート 限定的(file ドライバ不可) Cache::tags([...]) が全ドライバで利用可

実務的なヒント:キャッシュキーに動的パラメータを入れる場合は、Str::slug() などで長さを抑えつつ一意性を保ちましょう。


全体のまとめとチェックリスト

項目 完了条件
PHP & 拡張 composer check-platform-reqs がエラーなし
バックアップ .env, DB, Docker イメージがそれぞれ保存済み
依存関係更新 composer update -W 後に composer.lock がコミットされ、CI が緑
非推奨 API 置換 全テストがパスし、phpstan / larastan の警告が消滅
設定差分適用 .env.diff.sh 実行後、php artisan config:cache が成功
マイグレーション安全実施 「コピー → 移行 → 削除」手順でロック時間 < 5 秒(ステージング測定)
CI パイプライン GitHub Actions が composer require laravel/framework:^10.0 とテストを通過
Blue‑Green デプロイ Green 環境がヘルスチェックをクリアし、段階的トラフィック切替完了
パフォーマンス測定 wrk の平均応答時間が前バージョン比で 15% 改善、Redis ヒット率 > 90%

上記リストを順に実行・検証すれば、「Laravel 10 への移行は安全かつ確実」 に完了します。

最終アドバイス:本番環境での障害は設定ミスやキャッシュ不整合が原因になることが多いです。移行作業は必ず ステージング環境でフルリハーサル を行い、手順書をチーム全員で共有したうえで本番に適用してください。これが長期的な安定運用への最短ルートです。

スポンサードリンク

もっとスキルを活かしたいエンジニアへ

スポンサードリンク
働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。


-PHP