【Laravel】Laravelのキャッシュ設定（config/route/viewキャッシュ）

laravelアイキャッチ Laravel
2024.06.27

こんにちは、かつコーチです。

前回は、.env ファイルの環境ごとの管理方法と、シークレット情報の安全な扱い方を解説しました。

その中で少し触れた config:cache について、今回はきちんと掘り下げていきます。

Laravelには、本番環境でアプリの応答速度を上げるための「キャッシュ」の仕組みがいくつか用意されています。

正しく使えば速度改善に直結しますが、仕組みを理解せずに使うと「設定を変えたのに反映されない」というトラブルの原因にもなります。

Laravelのキャッシュの種類

config・route・viewの3種類

本番運用でよく使われるキャッシュには、主に次の3種類があります。

コマンドキャッシュ対象効果
php artisan config:cache設定ファイル（config/配下）設定ファイルの読み込みを高速化
php artisan route:cacheルート定義ルーティングの解決を高速化
php artisan view:cacheBladeテンプレートBladeのコンパイル処理を事前実行

いずれも「毎回リクエストのたびに行っていた処理を、事前に1回まとめてやっておく」という考え方は共通しています。

なぜキャッシュが速度改善につながるのか

Laravelは通常、リクエストが来るたびに config/ 配下の複数のPHPファイルを読み込み、.env の値を反映しながら設定を組み立てます。

route:cache や view:cache も同様に、リクエストごとにルート定義の解析やBladeテンプレートのコンパイルを行っています。

これらの処理を事前に1つのキャッシュファイルにまとめておくことで、リクエストのたびに発生していた処理を省略し、応答速度を上げることができます。

config:cacheの使い方と注意点

基本の使い方

php artisan config:cache

実行すると、bootstrap/cache/config.php に、すべての設定ファイルの内容が1つにまとめられた状態で保存されます。

キャッシュを削除したいときは、次のコマンドを使います。

php artisan config:clear

最大の注意点：env() の直接呼び出しが効かなくなる

前回の記事でも軽く触れましたが、config:cache を実行すると、コントローラやサービスクラスの中で直接呼び出している env() 関数は、.env の値ではなく null を返すようになります。

❌ Before：env() を直接呼び出しているコード

class PaymentService
{
    public function charge(int $amount): void
    {
        $apiKey = env('STRIPE_API_KEY'); // config:cache実行後はnullになる

        Stripe::setApiKey($apiKey);
        // ...
    }
}

これは、config:cache によって生成されたキャッシュファイルには .env の実ファイルへの参照が含まれておらず、キャッシュ後は .env 自体が読み込まれなくなるためです。

✅ After：config/ の設定ファイルを経由して取得する

// config/services.php
return [
    'stripe' => [
        'key' => env('STRIPE_API_KEY'),
    ],
];

class PaymentService
{
    public function charge(int $amount): void
    {
        $apiKey = config('services.stripe.key'); // config:cache実行後も正しく取得できる

        Stripe::setApiKey($apiKey);
        // ...
    }
}

config/ の設定ファイルの中で env() を呼び出しておけば、config:cache の実行時にその値ごとキャッシュに焼き込まれるため、本番でも正しく値が取得できます。

route:cacheの使い方と注意点

基本の使い方

php artisan route:cache

ルート数が多い大規模なアプリケーションほど、この効果は顕著になります。

クロージャを使ったルート定義はキャッシュできない

route:cache には、コントローラを指定したルートしかキャッシュできないという制約があります。

❌ Before：クロージャで定義したルート

// routes/web.php
Route::get('/ping', function () {
    return response()->json(['status' => 'ok']);
});

このルートが定義された状態で route:cache を実行すると、次のようなエラーが発生します。

RuntimeException: Unable to prepare route [/ping] for serialization. Uses Closure.

✅ After：コントローラのメソッドとして定義し直す

// routes/web.php
use App\Http\Controllers\HealthCheckController;

Route::get('/ping', [HealthCheckController::class, 'index']);

// app/Http/Controllers/HealthCheckController.php
class HealthCheckController extends Controller
{
    public function index()
    {
        return response()->json(['status' => 'ok']);
    }
}

私が初めてこのエラーに遭遇したときは、開発中に手軽さから書いていたクロージャのルートを、本番デプロイ直前に全部コントローラへ書き直す羽目になり、結構な手戻りになりました。

この経験から、開発初期の動作確認用ルート以外は、最初からコントローラとして定義しておくようにしています。

view:cacheの使い方

基本の使い方

php artisan view:cache

Bladeテンプレートは通常、初回アクセス時にPHPコードへコンパイルされ、storage/framework/views/ にキャッシュファイルとして保存されます。

view:cache を使うと、このコンパイル処理をデプロイのタイミングで事前にまとめて実行しておけるため、公開後の最初のアクセスから高速に応答できます。

view:cacheを忘れるとどうなるか

view:cache を実行し忘れても致命的なエラーにはなりませんが、デプロイ直後の最初の数リクエストだけ、Bladeのコンパイル処理が走る分だけ応答が遅くなります。

アクセスが集中するタイミングでのデプロイでは、このわずかな遅延が体感速度に影響することもあるため、デプロイ手順に組み込んでおくのがおすすめです。

デプロイ時にキャッシュコマンドをまとめて実行する

3つのコマンドをまとめて実行する

実際の運用では、デプロイの最終ステップとして3つのキャッシュコマンドをまとめて実行します。

php artisan config:cache
php artisan route:cache
php artisan view:cache

Laravel 9以降では、これらをまとめて実行する optimize コマンドも用意されています。

php artisan optimize

キャッシュを解除したいときは、対応する optimize:clear を使います。

php artisan optimize:clear

つまずきやすいポイント：設定を変更したのに本番に反映されない

.env を書き換えたのにキャッシュが古いまま

config:cache を運用している本番環境で、.env の値だけを書き換えても、実際の挙動には反映されません。

❌ Before：.env を書き換えただけで反映されると思い込む

# 本番サーバー上で.envの値を書き換える
vim .env
# APIキーを新しい値に変更して保存

# 何もキャッシュを更新せずにそのまま公開し続けてしまう

私は一度、決済APIのキーをテスト用から本番用に切り替えた際、.env を書き換えただけで満足してしまい、config:cache の再実行を忘れたことがあります。

古いキャッシュには元のテスト用キーがそのまま焼き込まれていたため、決済処理が本番用の値に切り替わっておらず、原因の特定に時間がかかりました。

✅ After：.env を変更したら必ずキャッシュを再生成する

vim .env
# APIキーを新しい値に変更して保存

# 古いキャッシュを削除してから再生成する
php artisan config:cache

.env を変更する運用がある場合は、「.env を書き換えたら config:cache を再実行する」までを1セットの作業として覚えておく必要があります。

まとめ

この記事のポイント

  • Laravelには config:cache route:cache view:cache という3種類の主要なキャッシュがある
  • config:cache 実行後は env() の直接呼び出しが効かなくなるため、config/ 経由で値を取得する設計にしておく
  • route:cache はクロージャで定義したルートに対応しておらず、コントローラベースの定義に統一する必要がある
  • デプロイの最終ステップとして3つのキャッシュコマンド、または optimize コマンドをまとめて実行する
  • .env の値を変更したときは、config:cache の再実行を忘れずセットで行う

次に読むべき記事

キャッシュで応答速度が改善できたところで、次は時間のかかる処理をリクエストの外側で実行する「Queue」の仕組みについて解説していきます。

→ 次の記事：Queueの基本：時間のかかる処理を非同期化する

タイトルとURLをコピーしました