こんにちは、かつコーチです。
2026年3月にリリースされたLaravel13は、公式が「破壊的変更を最小限に抑えた」とアナウンスしているアップグレードです。
とはいえ、実務で本番環境にデプロイするとなると話は別です。
PHPのバージョン要件、composer.jsonの更新、CSRF関連クラス名の変更、キャッシュキーの区切り文字変更など、事前に把握しておかないとハマるポイントがいくつかあります。
この記事では、Laravel12からLaravel13へアップグレードする際に押さえておくべき手順と、注意すべき破壊的変更を実務目線でまとめます。
筆者が実際に検証環境で12→13へ上げた際に踏んだ手順をベースにしているので、これから移行作業に入る方はチェックリスト代わりに使ってください。
Laravel13へのアップグレード手順
PHP8.3以上への引き上げが必須
Laravel12はPHP8.2以上に対応していましたが、Laravel13ではPHP8.3以上が必須になりました。
まず最初に確認すべきは、本番サーバー・ステージング環境・ローカル開発環境のPHPバージョンです。
# 現在のPHPバージョンを確認
php -v
PHP8.2以下が動いている環境では、Laravel13へのcomposer updateがそもそも失敗します。
サーバー側のPHPバージョンアップは、インフラ担当と連携してLaravel本体のアップグレードより先に済ませておく必要があります。
共用レンタルサーバーを使っている場合は、PHP8.3が選択できるかを事前にコントロールパネルで確認しておきましょう。
composer.jsonの更新
PHPバージョンの引き上げが完了したら、composer.jsonのLaravelフレームワーク本体のバージョン指定を更新します。
{
"require": {
"php": "^8.3",
"laravel/framework": "^13.0"
}
}
# 依存パッケージを更新する
composer update laravel/framework --with-all-dependencies
--with-all-dependenciesを付けることで、Laravel13が要求する依存パッケージ（Illuminateコンポーネント群など）もあわせて解決されます。
このタイミングで、Sanctum・Horizon・Telescopeなど周辺パッケージがLaravel13に対応済みかもcomposer.jsonの警告やエラーメッセージで確認してください。
対応していないバージョンのままだと、composer updateの段階でバージョン制約の衝突が発生します。
アップグレード後の動作確認手順
composerの更新が完了したら、いきなり本番反映せず、以下の順で確認するのがおすすめです。
- ローカル・ステージング環境でcomposer updateを実行
php artisan testで既存テストが通ることを確認- CSRF・キャッシュまわりを中心に手動での動作確認
- ステージング環境で一定期間の並行稼働
- 本番環境へのデプロイ
特に3の手動確認は、後述する破壊的変更が絡む部分なので省略しないことをおすすめします。
破壊的変更の注意点
CSRF関連クラス名の変更
Laravel13では、CSRF対策用のミドルウェアクラス名が変更されました。
CSRF（Cross-Site Request Forgery、クロスサイトリクエストフォージェリ）とは、悪意のあるサイトから正規サイトへ不正なリクエストを送らせる攻撃手法のことです。
// ❌ Before：Laravel12までのクラス名
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken;
class Kernel extends HttpKernel
{
protected $middlewareGroups = [
'web' => [
VerifyCsrfToken::class,
],
];
}
// ✅ After：Laravel13でのクラス名
use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;
class Kernel extends HttpKernel
{
protected $middlewareGroups = [
'web' => [
PreventRequestForgery::class,
],
];
}
VerifyCsrfTokenというクラス名を独自ミドルウェアの継承元にしていたり、configやbootstrapのミドルウェア除外設定（exceptプロパティ）で直接クラス名を参照していたりするコードは、PreventRequestForgeryへの置き換えが必要です。
クラス名で直接参照している箇所は、プロジェクト全体をgrepしてから修正するのが確実です。
# VerifyCsrfTokenを直接参照している箇所を洗い出す
grep -r "VerifyCsrfToken" app/ config/ bootstrap/
キャッシュキーのデフォルト区切り文字変更
もう1つ実務で見落としやすいのが、キャッシュキーのデフォルト区切り文字がアンダースコア（_）からハイフン（-）に変更された点です。
たとえばLaravel12までは、タグ付きキャッシュや自動生成されるキャッシュキーの一部にアンダースコアが使われていました。
// Laravel12までの内部的なキー生成イメージ
// 例：cache_user_123_profile のようなキーが生成される
// Laravel13のデフォルト設定
// 例：cache-user-123-profile のようなキーが生成される
なぜこれが問題になるのかというと、区切り文字が変わることで、Laravel12時代に保存された既存キャッシュのキーと、Laravel13で新たに生成されるキーが一致しなくなるためです。
結果として、アップグレード直後は既存キャッシュに一切アクセスできなくなり、キャッシュミスが多発してDB・APIへの負荷が一時的に跳ね上がるリスクがあります。
セッションキャッシュやレートリミット用のキャッシュがこの影響を受けると、ログイン状態が意図せずリセットされるといった実害にもつながりかねません。
対策：デプロイ前にキャッシュを明示的にクリアする
このリスクを避ける一番シンプルな対策は、デプロイのタイミングで既存キャッシュを明示的にクリアしてしまうことです。
# デプロイ手順にキャッシュクリアを組み込む
php artisan cache:clear
php artisan config:clear
php artisan route:clear
「アクセスできない古いキャッシュが残り続ける」よりも、「デプロイ時に一度クリアして新しい区切り文字でキャッシュを作り直す」方が、影響範囲をコントロールしやすくなります。
対策：区切り文字を明示的に固定する
もう1つの選択肢として、config/cache.phpで区切り文字を明示的に指定し、Laravel12時代の挙動を維持する方法もあります。
// config/cache.php
return [
// 区切り文字を明示的にアンダースコアへ固定する
'key_separator' => '_',
];
ただしこの方法は、あくまで移行期間中の緊急避避的な対応と考えてください。
長期的にはLaravel13のデフォルト設定に合わせておく方が、将来のアップグレード時に同様の問題を繰り返さずに済みます。
筆者が検証環境で試した際は、キャッシュクリアを組み込んだデプロイ手順に切り替える方針を選びました。
セッションやレート制限のキャッシュが多かったため、区切り文字を固定するより、一度きれいにクリアしてしまう方が事故のリスクが低いと判断したためです。
よくあるつまずきポイント・エラー対処
独自ミドルウェアがVerifyCsrfTokenを継承していてエラーになる
// ❌ Before：VerifyCsrfTokenを継承した独自ミドルウェア
class CustomCsrfMiddleware extends VerifyCsrfToken
{
protected $except = ['api/webhook/*'];
}
// ✅ After：PreventRequestForgeryを継承するよう修正
class CustomCsrfMiddleware extends PreventRequestForgery
{
protected $except = ['api/webhook/*'];
}
composer updateは成功したのに、php artisan serveで起動した瞬間に「Class ‘VerifyCsrfToken’ not found」のようなエラーが出るケースがあります。
これは大抵、独自ミドルウェアや設定ファイルの中でクラス名を直接参照している箇所の修正漏れです。
エラーメッセージに出てくるファイルパスを起点に、参照箇所を1つずつPreventRequestForgeryへ置き換えていけば解消します。
応用・一歩先の使い方
CI/CDパイプラインへの組み込み
キャッシュクリアの対策は、手動デプロイ時に忘れると本末転倒です。
GitHub ActionsなどのCI/CDパイプラインに、Laravel13へのデプロイ手順としてcache:clearを含むデプロイスクリプトを組み込んでおくと、手順の抜け漏れを防げます。
# .github/workflows配下のデプロイジョブの一部イメージ
- name: Clear application cache
run: php artisan cache:clear
ステージング環境での並行稼働期間を設ける
キャッシュキーの区切り文字変更のような「気づきにくいが実害のある変更」は、本番反映前にステージング環境である程度の期間稼働させ、ログを監視するのが安全です。
キャッシュミス率やレスポンスタイムに異常な変化がないかを見ておくと、本番デプロイ後のトラブルを未然に防げます。
まとめ
この記事のポイント
- Laravel13はPHP8.3以上が必須。composer updateの前に、まず全環境のPHPバージョンを引き上げる
- composer.jsonの更新は
--with-all-dependenciesを付けて、周辺パッケージの対応状況もあわせて確認する - CSRFミドルウェアは
VerifyCsrfTokenからPreventRequestForgeryへクラス名が変更された。継承・直接参照している箇所はgrepで洗い出して修正する - キャッシュキーのデフォルト区切り文字がアンダースコアからハイフンに変わり、既存キャッシュにアクセスできなくなるリスクがある。デプロイ時のキャッシュクリア、または区切り文字の明示的な固定で対策する
次に読むべき記事
これでLaravel13シリーズ（全5本）は完結です。
Laravel13の全体像や新機能を振り返りたい方は、シリーズ1本目の「Laravel13とは？Laravel12からの変更点まとめ」からどうぞ。
PHP Attributes・Queue Routing・JSON:API Resources・Cache::touch()の実務Tipsは、前回の「Laravel13のPHP Attributes化とQueue Routing・JSON:API・Cache::touch()」で解説しています。