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

2026年7月2日

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

スポンサードリンク

働き方から選べる

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

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

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

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

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

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

Beyond Careerに無料相談する

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

Contents

1 移行前の準備と環境チェック
- 1.1 PHP バージョンと拡張モジュールの検証
  - 1.1.1 確認コマンド例
  - 1.1.2 Composer での要件チェック
- 1.2 バックアップとバージョン管理の基本方針
  - 1.2.1 Git ブランチ戦略
  - 1.2.2 データベース・環境のスナップショット
2 依存関係とコードベースのアップデート
- 2.1 Composer での依存関係更新手順
  - 2.1.1 更新コマンド
  - 2.1.2 トラブルシューティング
- 2.2 非推奨 API と置き換え例
  - 2.2.1 置き換えサンプルコード
3 設定・環境変数とマイグレーションの変更点
- 3.1 .env と config ディレクトリの差分
  - 3.1.1 差分自動適用スクリプト（bash）
- 3.2 データベースマイグレーションの安全な実施
  - 3.2.1 カラムリネームの実装例
  - 3.2.2 型変更・カラム属性の更新
4 テストと CI パイプラインでの検証
- 4.1 PHPUnit と Pest のバージョン合わせ
- 4.2 GitHub Actions に組み込む移行テストフロー
5 本番環境へのデプロイとパフォーマンス最適化
- 5.1 Blue‑Green デプロイの実装フロー
- 5.2 キャッシュとパフォーマンスベンチマーク
6 全体のまとめとチェックリスト

スポンサードリンク

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

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

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

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

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

確認コマンド例

# PHP バージョン確認
php -v

# 必要拡張がインストール済みかチェック
php -m | grep -E 'pdo_mysql|openssl|mbstring|tokenizer|xml|ctype|json|bcmath'

# PHP バージョン確認

php -v

# 必要拡張がインストール済みかチェック

Composer での要件チェック

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

composer check-platform-reqs

1 2	composer check-platform-reqs

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

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

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

Git ブランチ戦略

git checkout -b upgrade-to-laravel10
変更を小粒にコミットし、プルリクエストでレビューを実施
マージ前に 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 用のバージョン指定を追加し、全パッケージの互換性を同時に解決します。

{
    &quot;require&quot;: {
        &quot;php&quot;: &quot;^8.1&quot;,
        &quot;laravel/framework&quot;: &quot;^10.0&quot;
    }
}

{

"require": {

"php": "^8.1",

"laravel/framework": "^10.0"

}

更新コマンド

composer update --with-all-dependencies -W

1 2	composer update --with-all-dependencies -W

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

トラブルシューティング

# 競合原因の特定例
composer why-not laravel/framework ^10.0

# 競合原因の特定例

composer why-not laravel/framework ^10.0

このコマンドは、インストールできないパッケージとそのバージョン制約を一覧表示します。問題が判明したら 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)])` と明示化	将来的なデフォルト変更に備える

置き換えサンプルコード

// Laravel 9 (旧)
use Illuminate\Support\Str;

if (Str::contains($request-&gt;url(), 'admin')) {
    // 管理画面用ロジック
}

// Laravel 9 (旧)

use Illuminate\Support\Str;

if (Str::contains($request->url(), 'admin')) {

// 管理画面用ロジック

}

// Laravel 10 (新)
if (str_contains($request-&gt;url(), 'admin')) {
    // 同上
}

// Laravel 10 (新)

if (str_contains($request->url(), 'admin')) {

// 同上

}

ベストプラクティス：非推奨 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）

#!/usr/bin/env bash
# laravel10_env_diff.sh - .env の差分を自動的に反映

set -euo pipefail

BACKUP=&quot;.env.backup_$(date +%Y%m%d_%H%M%S)&quot;
cp .env &quot;$BACKUP&quot;
echo &quot;Backup created: $BACKUP&quot;

# 追加項目（例：Redis キャッシュ）
if ! grep -q '^CACHE_STORE=' .env; then
    echo 'CACHE_STORE=redis' &gt;&gt; .env
fi

# 必須メール設定が抜けているかチェック
required_mail=(&quot;MAIL_HOST&quot; &quot;MAIL_PORT&quot;)
for var in &quot;${required_mail[@]}&quot;; do
    if ! grep -q &quot;^${var}=&quot; .env; then
        echo &quot;# TODO: Set ${var}=&lt;value&gt;&quot; &gt;&gt; .env
    fi
done

php artisan config:cache
echo &quot;.env の差分適用が完了しました。&quot;

#!/usr/bin/env bash

# laravel10_env_diff.sh - .env の差分を自動的に反映

set -euo pipefail

BACKUP=".env.backup_$(date +%Y%m%d_%H%M%S)"

cp .env "$BACKUP"

echo "Backup created: $BACKUP"

# 追加項目（例：Redis キャッシュ）

if ! grep -q '^CACHE_STORE=' .env; then

echo 'CACHE_STORE=redis' >> .env

# 必須メール設定が抜けているかチェック

required_mail=("MAIL_HOST" "MAIL_PORT")

for var in "${required_mail[@]}"; do

if ! grep -q "^${var}=" .env; then

echo "# TODO: Set ${var}=<value>" >> .env

done

php artisan config:cache

echo ".env の差分適用が完了しました。"

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

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

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

カラムリネームの実装例

// ① 新カラム追加 &amp; データコピー
Schema::table('users', function (Blueprint $table) {
    $table-&gt;string('email_new')-&gt;nullable();
});

DB::statement('UPDATE users SET email_new = email');

// ② アプリ側で新カラムを使用開始（モデル・バリデーション更新）

// ③ 旧カラム削除 &amp; 名前変更
Schema::table('users', function (Blueprint $table) {
    $table-&gt;dropColumn('email');
});
Schema::rename('users', 'email_new', 'email'); // 実際は再度 addColumn が必要な場合あり

// ① 新カラム追加 & データコピー

Schema::table('users', function (Blueprint $table) {

$table->string('email_new')->nullable();

});

DB::statement('UPDATE users SET email_new = email');

// ② アプリ側で新カラムを使用開始（モデル・バリデーション更新）

// ③ 旧カラム削除 & 名前変更

Schema::table('users', function (Blueprint $table) {

$table->dropColumn('email');

});

Schema::rename('users', 'email_new', 'email'); // 実際は再度 addColumn が必要な場合あり

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

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

DB::transaction(function () {
    Schema::table('orders', function (Blueprint $table) {
        $table-&gt;decimal('total_amount', 12, 2)-&gt;change();
    });
});

DB::transaction(function () {

Schema::table('orders', function (Blueprint $table) {

$table->decimal('total_amount', 12, 2)->change();

});

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

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

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

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

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

composer require --dev phpunit/phpunit ^10.0
composer require --dev pestphp/pest ^2.0   # 必要ならば

composer require --dev phpunit/phpunit ^10.0

composer require --dev pestphp/pest ^2.0 # 必要ならば

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

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

テストコード例（PHPUnit）

public function test_user_list_endpoint_returns_ok()
{
    $response = $this-&gt;getJson('/api/v1/users');
    $response-&gt;assertStatus(200);
    $this-&gt;assertIsArray($response-&gt;json());
}

public function test_user_list_endpoint_returns_ok()

{

$response = $this->getJson('/api/v1/users');

$response->assertStatus(200);

$this->assertIsArray($response->json());

}

同等の Pest バージョン

it('returns ok for user list endpoint', function () {
    getJson('/api/v1/users')-&gt;assertOk()-&gt;assertJsonStructure(['data']);
});

it('returns ok for user list endpoint', function () {

getJson('/api/v1/users')->assertOk()->assertJsonStructure(['data']);

});

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

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

name: Laravel 10 Migration CI

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: secret
          MYSQL_DATABASE: laravel_test
        ports: ['3306:3306']
        options: &gt;-
          --health-cmd=&quot;mysqladmin ping&quot;
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3

    steps:
      - uses: actions/checkout@v3

      # PHP 8.1 環境をセットアップ
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          extensions: mbstring, bcmath, intl, pdo_mysql
          coverage: none

      # Composer の依存関係インストール（ロックファイル使用）
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress --no-suggest

      # Laravel 10 へのアップデートとマイグレーション実行
      - name: Upgrade to Laravel 10
        run: |
          composer require laravel/framework:^10.0 --with-all-dependencies -W
          php artisan migrate --env=testing

      # テスト実行（PHPUnit）
      - name: Run PHPUnit tests
        run: vendor/bin/phpunit --colors=always

      # 必要に応じて Pest のテストも走らせる
      - name: Run Pest tests
        if: always()
        run: vendor/bin/pest --parallel

name: Laravel 10 Migration CI

on:

pull_request:

branches: [ main ]

jobs:

test:

runs-on: ubuntu-latest

services:

mysql:

image: mysql:8.0

env:

MYSQL_ROOT_PASSWORD: secret

MYSQL_DATABASE: laravel_test

ports: ['3306:3306']

options: >-

--health-cmd="mysqladmin ping"

--health-interval=10s

--health-timeout=5s

--health-retries=3

steps:

- uses: actions/checkout@v3

# PHP 8.1 環境をセットアップ

- name: Set up PHP

uses: shivammathur/setup-php@v2

with:

php-version: '8.1'

extensions: mbstring, bcmath, intl, pdo_mysql

coverage: none

# Composer の依存関係インストール（ロックファイル使用）

- name: Install dependencies

run: composer install --prefer-dist --no-progress --no-suggest

# Laravel 10 へのアップデートとマイグレーション実行

- name: Upgrade to Laravel 10

run: |

composer require laravel/framework:^10.0 --with-all-dependencies -W

php artisan migrate --env=testing

# テスト実行（PHPUnit）

- name: Run PHPUnit tests

run: vendor/bin/phpunit --colors=always

# 必要に応じて Pest のテストも走らせる

- name: Run Pest tests

if: always()

run: vendor/bin/pest --parallel

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

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

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

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

環境準備
blue（現行）と green（新バージョン）の 2 套 EC2 / コンテナを同一 VPC に構築。
両方が同じデータベース／ストレージに接続できることを事前確認。
Green 環境へのデプロイ

# Envoy スクリプト例（green サーバーへ展開）
@servers(['green' =&gt; 'deploy@green.example.com'])

@task('prepare')
    cd /var/www/laravel
    git pull origin main
    composer install --no-dev -W
    php artisan migrate --force
@endtask

@task('optimize')
    php artisan config:cache
    php artisan route:cache
    php artisan view:cache
@endtask

@story('deploy_green')
    prepare
    optimize
@endstory

# Envoy スクリプト例（green サーバーへ展開）

@servers(['green' => 'deploy@green.example.com'])

@task('prepare')

cd /var/www/laravel

git pull origin main

composer install --no-dev -W

php artisan migrate --force

@endtask

@task('optimize')

php artisan config:cache

php artisan route:cache

php artisan view:cache

@endtask

@story('deploy_green')

prepare

optimize

@endstory

ヘルスチェック
/healthz エンドポイントで 200 が返るか、キューが正常に動くかを自動テスト。
トラフィックの段階的切替（例：AWS ALB のターゲットグループ）
25% → 50% → 100% と徐々にシフトし、エラー率が閾値以下なら次へ進む。
ロールバック手順
問題検出時は ALB の設定だけで Blue 環境へ戻す。
必要ならばデータベースのポイントインタイムリカバリ（PITR）を実施。

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

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

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

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

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

サンプルコマンド

wrk -t8 -c200 -d45s http://example.com/api/v1/products

1 2	wrk -t8 -c200 -d45s http://example.com/api/v1/products

設定の最適化例

// config/cache.php
return [
    'default' =&gt; env('CACHE_STORE', 'redis'), // 任意で file から redis に切り替え可

    'stores' =&gt; [
        'redis' =&gt; [
            'driver' =&gt; 'redis',
            'connection' =&gt; 'cache',
            // Redis の TTL をデフォルトで 60 分に設定
            'ttl' =&gt; env('CACHE_TTL', 3600),
        ],
    ],
];

// config/cache.php

return [

'default' => env('CACHE_STORE', 'redis'), // 任意で file から redis に切り替え可

'stores' => [

'redis' => [

'driver' => 'redis',

'connection' => 'cache',

// Redis の TTL をデフォルトで 60 分に設定

'ttl' => env('CACHE_TTL', 3600),

];

項目	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%