Laravelのインストールと設定の詳細ガイド
設定はLaravelの「ダッシュボード」です。.envとconfig/の関係を理解することは, 車のダッシュボードにアクセスして, いつでもエンジンパラメータを調整できるようなものです。
1. 学ぶ内容
.env環境ファイルとconfig/*.php設定読み込みメカニズム- 環境切り替え:local/staging/production設定ポリシー
- データベース接続設定 (MySQL & PostgreSQL)
- キャッシュとセッションドライバの設定
php artisan config:cache本番環境での設定キャッシュ
2. 運用現場のリアルストーリー
(1) ペインポイント:乱雑な開発環境設定
AliceはローカルでShopMetricsを開発する際にMySQLを使っていましたが, ステージングサーバーにデプロイした後, データベースに接続できませんでした。DB_PASSWORDをコードにハードコードしており, Gitにプッシュすると同僚Bobのローカルパスワードで上書きされてしまったのです。さらに悪いことに, Charlieが誤って本番環境のAPP_DEBUG=trueをリポジトリにコミットし, エラースタックトレース全体がユーザーに露出してしまいました。3人で設定問題のトラブルシューティングに2日かかりました。
(2) .env設定のソリューション
Laravelは.envファイルを使って環境変数を分離します。ローカル, ステージング, 本番それぞれに1つずつ用意し, 機密値をコードにハードコードすることはありません。
BASH
# .env (ローカル — このファイルはコミットしない)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics_local
DB_USERNAME=root
DB_PASSWORD=secret
APP_DEBUG=true
(3) 成果
Aliceが.envを使って設定を管理した後, ローカルと本番環境が干渉しなくなり, APP_DEBUGは本番環境で自動的にオフになるため, Bobは二度とパスワード上書きの問題に直面することはありません。
3. 環境設定メカニズム
Laravelの設定システムは2つの層で構成されています。.envファイルが環境変数を格納し, config/*.phpファイルがこれらの変数を読み取り, 整理します。
graph TD
A[.envファイル] -->|dotenvが読み込み| B[$_ENV / $_SERVER]
B -->|configが読み取り| C[config/database.php]
C -->|envヘルパー| D["env('DB_HOST', 'localhost')"]
D -->|フォールバック| E[未設定時のデフォルト値]
(1) .envファイルの詳細解説
.envファイルはプロジェクトルートにあり、KEY=VALUE形式を使用します。Gitには絶対にコミットしないでください。
| ルール | 説明 |
|---|---|
| 形式 | KEY=VALUE, 等号の両側にスペースなし |
| 引用符 | スペースを含む値には引用符を使用:APP_NAME="My App" |
| コメント | #で始まる行はコメント |
| 型 | すべての値は文字列。コード内で手動で型変換が必要 |
| 優先順位 | 実際の環境変数 > .envファイルの値 |
(2) configディレクトリ構造
config/は各PHPファイルの設定配列を返し、env()関数を使って環境変数を読み取ります。
| ファイル | 目的 |
|---|---|
app.php |
アプリ名, タイムゾーン, 暗号化キー, デバッグモード |
database.php |
データベース接続, テーブル名マイグレーション |
cache.php |
キャッシュドライバ (file/redis/database) |
session.php |
セッションドライバとライフサイクル |
mail.php |
メールサービス設定 |
filesystems.php |
ファイルストレージドライバ |
(1) ▶ サンプル:現在の設定値の確認
BASH
# 特定の設定値を確認
php artisan tinker
# tinker REPL内で:
config('app.name')
# => "Laravel"
config('database.default')
# => "mysql"
config('cache.default')
# => "file"
出力:
TEXT
# コマンドは正常に実行されました
4. データベース設定
(1) MySQL設定
PHP
// config/database.php — 'mysql'接続
'mysql' => [
'driver' => 'mysql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => env('DB_DATABASE', 'shopmetrics'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
],
(2) PostgreSQL設定
PHP
// config/database.php — 'pgsql'接続
'pgsql' => [
'driver' => 'pgsql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '5432'),
'database' => env('DB_DATABASE', 'shopmetrics'),
'username' => env('DB_USERNAME', 'postgres'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
],
| 項目 | MySQL | PostgreSQL |
|---|---|---|
| デフォルトポート | 3306 | 5432 |
| JSONサポート | 5.7+でネイティブ | ネイティブでより強力 |
| フルテキスト検索 | 基本 | 高度 (tsvector) |
| 拡張性 | 中 | 高 (PostGISなど) |
| 用途 | ECサイト/コンテンツ | 地理/分析 |
(1) ▶ サンプル:ShopMetricsのMySQL接続設定
BASH
# .env — ShopMetricsのMySQL設定
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!
# データベースを作成
mysql -u root -p -e "CREATE DATABASE shopmetrics;"
mysql -u root -p -e "CREATE USER 'shopmetrics_user'@'localhost' IDENTIFIED BY 'Str0ngP@ssw0rd!';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON shopmetrics.* TO 'shopmetrics_user'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"
# 接続テスト
php artisan db:show
# Database: shopmetrics | MySQL 8.x | Tables: 0
出力:
TEXT
# コマンドは正常に実行されました
5. キャッシュとセッションドライバ
(1) キャッシュドライバの比較
| ドライバ | 用途 | パフォーマンス | 永続性 |
|---|---|---|---|
file |
開発/小規模プロジェクト | 遅い | ✅ |
database |
Redisなし | 中 | ✅ |
redis |
本番環境 | 高速 | ✅ |
memcached |
高同時読み取り | 高速 | ❌ |
array |
テスト | 超高速 | ❌ |
(2) セッションドライバの比較
| ドライバ | 適用シナリオ | 説明 |
|---|---|---|
file |
開発 | storage/framework/sessions/に保存 |
database |
中規模 | "sessions"テーブルの作成が必要 |
redis |
本番 | 高性能, TTLサポート |
cookie |
軽量 | 暗号化後にクライアントに保存, 4KB制限 |
array |
テスト | リクエスト終了時に消滅 |
(1) ▶ サンプル:Redisキャッシュとセッションの設定
BASH
# .env — キャッシュとセッションにRedisを設定
CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
# Redis PHP拡張機能をインストール
pecl install redis
# Redis接続テスト
php artisan tinker
# Cache::put('test_key', 'hello', 60)
# => true
# Cache::get('test_key')
# => "hello"
出力:
TEXT
# コマンドは正常に実行されました
6. 環境切り替え戦略
(1) マルチ環境設定ソリューション
| ソリューション | アプローチ | メリット・デメリット |
|---|---|---|
| 複数.envファイル | .env.local / .env.staging / .env.production |
シンプルだが手動切り替えが必要 |
| CI/CD連携 | デプロイスクリプトで環境変数を設定 | 安全だがCIプラットフォームが必要 |
| Laravel Envoyer | サーバー側.env管理 | 公式ツールだが有料 |
(2) 主要な環境変数の違い
| 変数 | ローカル | ステージング | 本番 |
|---|---|---|---|
APP_ENV |
local | staging | production |
APP_DEBUG |
true | true | false |
CACHE_DRIVER |
file | redis | redis |
SESSION_DRIVER |
file | redis | redis |
LOG_LEVEL |
debug | info | warning |
(1) ▶ サンプル:異なる環境用の.envファイルの準備
BASH
# .env.local (開発)
APP_ENV=local
APP_DEBUG=true
DB_DATABASE=shopmetrics_dev
CACHE_DRIVER=file
LOG_LEVEL=debug
# .env.staging (ステージングサーバー)
APP_ENV=staging
APP_DEBUG=true
DB_DATABASE=shopmetrics_staging
CACHE_DRIVER=redis
LOG_LEVEL=info
# .env.production (本番サーバー)
APP_ENV=production
APP_DEBUG=false
DB_DATABASE=shopmetrics
CACHE_DRIVER=redis
LOG_LEVEL=warning
出力:
TEXT
# コマンドは正常に実行されました
7. 設定キャッシュ
本番環境では, Laravelはすべての設定ファイルを1つのPHPファイルにマージしてキャッシュできるため, リクエストごとに.envを読み取り, config/*.phpを解析する必要がなくなります。
(1) ▶ サンプル:設定キャッシュコマンドの使用
BASH
# 全設定をキャッシュ (本番環境)
php artisan config:cache
# Configuration cached successfully!
# キャッシュ後, env()はnullを返す — 必ずconfig()を使用
# これはよくある落とし穴です!
# 設定キャッシュをクリア
php artisan config:clear
# Configuration cache cleared!
# 設定がキャッシュされているか確認
php artisan config:status
# Config is cached.
出力:
TEXT
# コマンドは正常に実行されました
⚠️ 注意:
config:cacheを実行した後, env()関数は設定ファイル以外ではnullを返します。env()はconfig/*.php内でのみ使用し, その他の場所ではconfig()を使用してください。
| コマンド | 機能 | 使用ケース |
|---|---|---|
config:cache |
設定をキャッシュ | 本番デプロイ |
config:clear |
キャッシュをクリア | 設定変更後 |
config:show |
設定値を表示 | デバッグ |
env |
.env値を表示 | 開発中 |
8. 総合例:ShopMetricsの完全な環境設定
PHP
// ============================================
// 総合: ShopMetrics完全.env設定
// 内容: アプリ, データベース, キャッシュ, セッション, メール, ログ
// ============================================
// ShopMetricsの.envファイル (ローカル開発)
/*
APP_NAME=ShopMetrics
APP_ENV=local
APP_KEY=base64:generated-key-here
APP_DEBUG=true
APP_URL=http://localhost:8000
LOG_CHANNEL=stack
LOG_LEVEL=debug
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shopmetrics
DB_USERNAME=shopmetrics_user
DB_PASSWORD=Str0ngP@ssw0rd!
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database
MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=shopmetrics-uploads
*/
BASH
# .env設定後, 以下のコマンドを実行:
php artisan key:generate
php artisan config:clear
php artisan migrate
php artisan db:seed
php artisan serve
出力:
TEXT
Application key set successfully.
Configuration cache cleared!
Info: Using MySQL database: shopmetrics
Migration table created successfully.
Starting Laravel development server: http://127.0.0.1:8000
❓ よくある質問
Q env()とconfig()の違いは何ですか?
A env()は.envファイルから環境変数を直接読み取ります。config()はconfig/*.phpファイルで整理された設定値を読み取ります。本番環境で
config:cacheを実行した後, 設定ファイル以外でenv()にアクセスするとnullが返されるため, 常にconfig()を使用すべきです。Q .envファイルはGitにコミットすべきですか?
A 絶対にいけません。.envファイルにはデータベースパスワードやAPIキーなどの機密情報が含まれています。テンプレートとして.env.exampleのみコミットし, 実際の.envファイルはサーバーで運用担当者が作成すべきです。
Q .envを変更した後, サーバーを再起動する必要がありますか?
A はい。
php artisan serveは変更を自動的に再読み込みしますが, php-fpmではphp artisan config:clearまたはサービスの再起動が必要です。本番環境でconfig:cacheが実行されている場合, キャッシュを再構築する必要があります。Q SQLiteとMySQLはいつ使い分けるべきですか?
A 学習やプロトタイピングにはSQLite (設定不要)を使用し, 本番環境にはMySQL (同時接続, レプリケーション, バックアップなどのエンタープライズ機能)を使用してください。高度なクエリ (フルテキスト検索, GIS)が必要な場合はPostgreSQLを選択してください。
Q APP_KEYの目的は何ですか?
A APP_KEYはすべての暗号化操作 (セッション暗号化, パスワードリセットトークン, CSRFトークンなど)に使用されます。APP_KEYを変更すると, 暗号化されたデータはすべて復号できなくなります。本番環境にデプロイした後は変更しないでください。
Q
config:cache実行後, .envの変更を反映するにはどうすればよいですか?A
php artisan config:cacheを再実行してキャッシュを再生成するだけです。これにより, .envとすべてのconfigファイルが再読み込みされ, 新しいキャッシュファイルが生成されます。📖 まとめ
- Laravelの設定は2層で構成:.envが環境変数を格納し, config/*.phpが設定値を整理する
env()は設定ファイル内でのみ使用し, その他の場所ではconfig()を使用する- MySQLはECサイトシナリオに, PostgreSQLは分析シナリオに, SQLiteは開発に適している
- 本番環境ではRedisをキャッシュとセッション管理のソリューションとして推奨
- APP_DEBUGは本番環境で必ずfalseに設定する
- config:cacheはパフォーマンスを向上させるが, キャッシュ後env()は設定ファイル外で機能しなくなる
📝 練習問題
-
基本演習 (⭐):ShopMetricsプロジェクトでMySQLデータベースを使用するように設定してください。
.envファイルのデータベース接続情報を変更し,php artisan migrateを実行して接続が成功することを確認してください。 -
応用演習 (⭐⭐):
.env.localと.env.stagingの2つの環境設定ファイルを作成し, 異なるデータベース名とキャッシュドライバを使用して, 環境間を素早く切り替えるスクリプトを書いてください。 -
チャレンジ (⭐⭐⭐):
config:cacheの実装原理を調査し (Illuminate/Foundation/Console/ConfigCacheCommand.phpを読む), キャッシュ後にenv()が無効になる理由を説明し, 本番環境で安全に設定キャッシュを使用する方法を述べてください。
