【Laravel】環境別に設定ファイルを自動切り替え｜local・staging・productionの運用最適化

【Laravel】環境別に設定ファイルを自動切り替え｜local・staging・productionの運用最適化 Laravel

Laravelアプリケーションを本番運用していく上で、環境（local / staging / production）に応じて設定を切り替える設計は避けて通れません。.envファイルで簡易的な制御は可能ですが、複雑な構成になると.envだけでは管理が難しくなり、configファイル単位で環境に応じた出し分けが必要になるケースもあります。

この記事では、Laravelの設定管理を環境ごとに柔軟かつ安全に最適化する方法を解説します。

Laravelにおける環境の定義方法

Laravelでは.envファイルのAPP_ENVキーを用いて環境名を定義します。

APP_ENV=local

この値はapp()->environment()やApp::environment()などで取得でき、環境ごとの条件分岐に利用できます。

if (app()->environment('production')) {
    // 本番用の処理
}

.envだけでは管理しきれない設定の例

例えば以下のようなケースでは、.envファイルでは管理が煩雑になります。

  • 決済サービスのAPIキーが複数あり、config配下にまとめたい
  • 特定の環境のみで使うフラグをconfigで制御したい
  • JSONや多次元配列など、複雑な構造の設定が必要

このような場合は、.envの変数を元にconfig/*.phpの中で環境ごとに条件分岐を入れる方法が有効です。

環境によって設定内容を切り替える具体例

たとえば config/payment.php に決済APIの設定を記述するとします。

<?php

return [

    'gateway' => env('PAYMENT_GATEWAY', 'stripe'),

    'credentials' => match (env('APP_ENV')) {
        'production' => [
            'api_key' => env('PAYMENT_API_KEY_PROD'),
            'secret'  => env('PAYMENT_SECRET_PROD'),
        ],
        'staging' => [
            'api_key' => env('PAYMENT_API_KEY_STG'),
            'secret'  => env('PAYMENT_SECRET_STG'),
        ],
        default => [
            'api_key' => env('PAYMENT_API_KEY_DEV'),
            'secret'  => env('PAYMENT_SECRET_DEV'),
        ],
    },

];

このようにすることで、.envファイルに以下を記述するだけで環境ごとに自動でAPIキーが切り替わります。

APP_ENV=production
PAYMENT_API_KEY_PROD=prod_123
PAYMENT_SECRET_PROD=secret_abc

configのキャッシュに注意

php artisan config:cacheを使っている場合、.envの変更だけでは反映されません。設定ファイルを変更した場合は、キャッシュの再生成が必要です。

php artisan config:clear
php artisan config:cache

CI/CDのデプロイスクリプトにこの2行を組み込んでおくと、意図しない古い設定の読み込みを防げます。

環境ごとのサービスプロバイダの登録方法

Laravelでは、AppServiceProviderなどのサービスプロバイダを環境に応じて切り替えることも可能です。

// app/Providers/AppServiceProvider.php

public function register()
{
    if (app()->environment('local')) {
        $this->app->register(\App\Providers\LocalOnlyServiceProvider::class);
    }
}

開発環境限定のログ出力やテスト用モックなどはこの方法で分離することで、コードの健全性が保てます。

実践的な構成例：複数設定ファイル＋環境ブートロジック

設定ファイルが多くなる場合、環境別に分けた設定ファイルを作るのも有効です。

例：config/payment.local.php, config/payment.staging.php, config/payment.production.php

そして、共通のconfig/payment.phpで以下のように環境ごとのファイルを読み込みます。

<?php

$env = env('APP_ENV', 'local');
$path = __DIR__ . "/payment.{$env}.php";

return file_exists($path) ? require $path : [];

この構成により、設定ファイルごと完全に環境を分離できます。

まとめ

Laravelの環境別設定管理は、アプリの成長とともに洗練させるべき重要な構成要素です。.envのみに頼らず、configファイル単位での条件分岐やファイルの分離運用を取り入れることで、安全かつ柔軟な環境管理が可能になります。

本番・ステージング・開発環境を安定して運用したいプロジェクトにおいて、今回紹介した設計パターンを導入してみてください。