> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 設定

> Laravelの設定ファイル、環境変数(.env)、設定値へのアクセス方法、キャッシュ、デバッグモード、メンテナンスモードを解説します。

## はじめに

Laravelフレームワークの設定ファイルはすべて `config/` ディレクトリに格納されています。各オプションにはコメントが付いているので、ファイルを開いて利用可能なオプションを確認してみてください。

設定ファイルでは、データベース接続情報・メールサーバー情報・アプリケーションURLや暗号化キーなど、さまざまなコア設定値を管理します。

```mermaid theme={null}
flowchart LR
    A[".env ファイル"] -->|"env()"| B["config/ ファイル"]
    B -->|"config()"| C["アプリケーション"]
```

### `about` コマンド

`about` Artisanコマンドを使うと、アプリケーションの設定・ドライバー・環境の概要を確認できます。

```shell theme={null}
php artisan about
```

特定のセクションだけを確認したい場合は `--only` オプションを使います。

```shell theme={null}
php artisan about --only=environment
```

特定の設定ファイルの値を詳しく確認するには `config:show` コマンドが便利です。

```shell theme={null}
php artisan config:show database
```

## 環境設定(.env)

実行環境によって設定値を切り替えたい場合がよくあります。たとえば、ローカルと本番でキャッシュドライバーを変えたいケースなどです。

Laravelはこれを簡単にするために [DotEnv](https://github.com/vlucas/phpdotenv) PHPライブラリを利用しています。新規インストール時、アプリケーションのルートディレクトリには一般的な環境変数が定義された `.env.example` ファイルが含まれており、インストールプロセス中に自動的に `.env` にコピーされます。

<Info>
  チームで開発する場合は、`.env.example` ファイルを更新しながらリポジトリに含めておくと便利です。プレースホルダー値を設定しておくことで、チームの他の開発者がどの環境変数が必要かを明確に把握できます。
</Info>

### 環境ファイルのセキュリティ

<Warning>
  `.env` ファイルはソースコントロールにコミットしないでください。開発者やサーバーごとに異なる設定が必要であり、リポジトリに含めるとインシデント発生時に機密情報が漏洩するリスクがあります。
</Warning>

ただし、Laravelには環境ファイルを暗号化する機能が組み込まれており、暗号化された状態であればソースコントロールに安全に保存できます。

### 追加の環境ファイル

アプリケーション起動時、Laravelは `APP_ENV` 環境変数またはCLIの `--env` 引数が指定されているかを確認します。指定されている場合、`.env.[APP_ENV]` ファイルが存在すればそれを読み込みます。存在しない場合はデフォルトの `.env` ファイルが使われます。

### 環境変数の型

`.env` ファイルの変数はすべて文字列として解析されますが、`env()` 関数からより幅広い型を返せるよう、以下の特殊な値が用意されています。

| `.env` の値 | `env()` の返り値 |
| - | - |
| `true` | `(bool) true` |
| `(true)` | `(bool) true` |
| `false` | `(bool) false` |
| `(false)` | `(bool) false` |
| `empty` | `(string) ''` |
| `(empty)` | `(string) ''` |
| `null` | `(null) null` |
| `(null)` | `(null) null` |

スペースを含む値を設定するにはダブルクォートで囲みます。

```ini theme={null}
APP_NAME="My Application"
```

### 環境変数の取得

`.env` ファイルに記述したすべての変数は、リクエストを受け取ったとき `$_ENV` PHPスーパーグローバルに読み込まれます。設定ファイル内では `env()` 関数を使って値を取得できます。

```php theme={null}
'debug' => (bool) env('APP_DEBUG', false),
```

第2引数はデフォルト値です。その環境変数が存在しない場合に返されます。

### 現在の環境を確認する

現在の環境は `.env` ファイルの `APP_ENV` 変数で決まります。`App` ファサードの `environment` メソッドで取得できます。

```php theme={null}
use Illuminate\Support\Facades\App;

$environment = App::environment();
```

引数を渡して特定の環境かどうかを確認することもできます。

```php theme={null}
if (App::environment('local')) {
    // ローカル環境
}

if (App::environment(['local', 'staging'])) {
    // ローカルまたはステージング環境
}
```

### 環境ファイルの暗号化

暗号化されていない環境ファイルはソースコントロールに保存すべきではありませんが、Laravelには環境ファイルを暗号化する機能があります。

#### 暗号化

環境ファイルを暗号化するには `env:encrypt` コマンドを使います。

```shell theme={null}
php artisan env:encrypt
```

実行すると `.env` が暗号化され、暗号化された内容が `.env.encrypted` ファイルに保存されます。復号キーはコマンドの出力に表示されるので、安全なパスワードマネージャーに保存してください。

独自の暗号化キーを指定したい場合は `--key` オプションを使います。

```shell theme={null}
php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

<Info>
  指定するキーの長さは、使用する暗号化方式が要求するキー長と一致させる必要があります。デフォルトでは32文字のキーが必要な `AES-256-CBC` が使われます。`--cipher` オプションを使えば、[暗号化](/jp/encryption)がサポートする任意の暗号方式を利用できます。
</Info>

`.env` と `.env.staging` のように複数の環境ファイルがある場合は、`--env` オプションで暗号化対象の環境名を指定できます。

```shell theme={null}
php artisan env:encrypt --env=staging
```

#### 可読な変数名（Readable Variable Names）

環境ファイルを暗号化する際、`--readable` オプションを使うと、値だけを暗号化して変数名は読める状態のまま残せます。

```shell theme={null}
php artisan env:encrypt --readable
```

これにより、以下のような形式の暗号化ファイルが生成されます。

```ini theme={null}
APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...
```

可読形式を使うことで、機密データを露出させずにどの環境変数が存在するかを確認できます。また、プルリクエストのレビュー時にも、ファイルを復号しなくてもどの変数が追加・削除・変更されたか把握しやすくなります。

環境ファイルを復号する際、Laravelは使用されている形式を自動的に判定するため、`env:decrypt` コマンドに追加のオプションは不要です。

<Info>
  `--readable` オプションを使用する場合、元の環境ファイルのコメントや空行は暗号化後の出力に含まれません。
</Info>

#### 可読な暗号化ファイルの更新

可読な暗号化済み環境ファイルを更新する場合、Laravelは変更のない値をそのまま保持し、元の環境ファイルに存在しなくなった変数を削除します。

```shell theme={null}
php artisan env:encrypt --readable --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

暗号化ファイルが存在しない場合は新規作成されます。既存のファイルを更新する場合は、作成時と同じ暗号化キー・暗号方式を指定してください。復号に失敗した場合、コマンドは既存ファイルを上書きせずに失敗します。

すべての値を強制的に再暗号化したい場合は `--force` オプションを使います。暗号化キーの変更や、無効になった暗号化ファイルの置き換えに利用できます。

```shell theme={null}
php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

#### 復号

環境ファイルを復号するには `env:decrypt` コマンドを使います。このコマンドは復号キーを必要とし、Laravelは `LARAVEL_ENV_ENCRYPTION_KEY` 環境変数からキーを取得します。

```shell theme={null}
php artisan env:decrypt
```

キーを直接 `--key` オプションで渡すこともできます。

```shell theme={null}
php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

`env:decrypt` コマンドが実行されると、Laravelは `.env.encrypted` ファイルの内容を復号し、`.env` ファイルに書き出します。

カスタムの暗号方式を使う場合は `--cipher` オプションを指定します。

```shell theme={null}
php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC
```

`.env` と `.env.staging` のように複数の環境ファイルがある場合は、`--env` オプションで復号対象の環境名を指定できます。

```shell theme={null}
php artisan env:decrypt --env=staging
```

既存の環境ファイルを上書きするには `--force` オプションを指定します。

```shell theme={null}
php artisan env:decrypt --force
```

## 設定値へのアクセス

`Config` ファサードまたはグローバルの `config()` 関数を使って、アプリケーションのどこからでも設定値にアクセスできます。「ドット記法」を使い、ファイル名とオプション名を組み合わせて指定します。

```php theme={null}
use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

// グローバル関数でも取得できる
$value = config('app.timezone');

// 存在しない場合のデフォルト値を指定する
$value = config('app.timezone', 'Asia/Tokyo');
```

実行時に設定値を変更するには `Config::set()` または配列を `config()` に渡します。

```php theme={null}
Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);
```

型付きの取得メソッドも用意されており、型が一致しない場合は例外がスローされます。

```php theme={null}
Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');
```

## 設定のキャッシュ

アプリケーションのパフォーマンスを向上させるには、すべての設定ファイルを1つのファイルにキャッシュします。

```shell theme={null}
php artisan config:cache
```

このコマンドはすべての設定オプションを1つのファイルにまとめ、フレームワークが素早く読み込めるようにします。

<Warning>
  `config:cache` コマンドは本番環境のデプロイプロセスの一部として実行してください。ローカル開発中は設定が頻繁に変わるため、実行しないことを推奨します。
</Warning>

キャッシュが作成されると、`.env` ファイルはフレームワークのリクエストやArtisanコマンド実行時に読み込まれなくなります。そのため `env()` 関数はシステムレベルの環境変数のみを返します。

<Tip>
  このため、`env()` 関数は必ず `config/` ディレクトリ内の設定ファイルからのみ呼び出すようにしてください。アプリケーション内の他の場所からは `config()` 関数を使って設定値を取得します。
</Tip>

キャッシュを削除するには `config:clear` コマンドを使います。

```shell theme={null}
php artisan config:clear
```

### 設定ファイルの公開

Laravelの設定ファイルの多くはすでに `config/` ディレクトリに公開されていますが、`cors.php` や `view.php` など一部のファイルはデフォルトでは公開されていません。

未公開の設定ファイルを公開するには `config:publish` コマンドを使います。

```shell theme={null}
php artisan config:publish

php artisan config:publish --all
```

## デバッグモード

`config/app.php` の `debug` オプションは、エラー情報をユーザーにどの程度表示するかを決定します。このオプションはデフォルトで `.env` ファイルの `APP_DEBUG` 環境変数の値に従います。

<Warning>
  **本番環境では `APP_DEBUG` を必ず `false` に設定してください。** `true` のままにすると、アプリケーションの機密設定値がエンドユーザーに公開される危険があります。
</Warning>

```ini theme={null}
# ローカル開発
APP_DEBUG=true

# 本番環境
APP_DEBUG=false
```

## メンテナンスモード

アプリケーションがメンテナンスモードのとき、すべてのリクエストに対してカスタムビューが表示されます。これにより、アップデート中や保守作業中にアプリケーションを一時的に「無効化」できます。

### メンテナンスモードの有効化

```shell theme={null}
php artisan down
```

`--refresh` オプションを指定すると、ブラウザが指定秒数後に自動的にリロードされます。

```shell theme={null}
php artisan down --refresh=15
```

`--retry` オプションは `Retry-After` HTTPヘッダーの値として設定されます。

```shell theme={null}
php artisan down --retry=60
```

### メンテナンスモードのバイパス

シークレットトークンを使って特定のユーザーだけがアクセスできるようにするには `--secret` オプションを使います。

```shell theme={null}
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

`--with-secret` オプションを使うとLaravelがトークンを自動生成します。

```shell theme={null}
php artisan down --with-secret
```

### 複数サーバーでのメンテナンスモード

デフォルトではLaravelはファイルベースでメンテナンスモードを管理します。複数サーバー構成の場合は、キャッシュベースの方法が便利です。

```ini theme={null}
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database
```

### メンテナンスビューの事前レンダリング

デプロイ中に `php artisan down` を実行する場合、依存関係更新中にアクセスしたユーザーがエラーを目にすることがあります。これを防ぐには `--render` オプションでビューを事前レンダリングします。

```shell theme={null}
php artisan down --render="errors::503"
```

メンテナンスモード中にすべてのリクエストを特定のURLにリダイレクトすることもできます。

```shell theme={null}
php artisan down --redirect=/
```

### メンテナンスモードの無効化

```shell theme={null}
php artisan up
```

<Info>
  メンテナンスモードのデフォルトテンプレートは `resources/views/errors/503.blade.php` を作成することでカスタマイズできます。
</Info>

<Tip>
  ダウンタイムを完全になくしたい場合は、[Laravel Cloud](https://cloud.laravel.com) のようなフルマネージドプラットフォームの利用を検討してください。
</Tip>

## 次のステップ

<Card title="ルーティング" icon="route" href="/jp/routing">
  URLとコントローラーを結びつけるルーティングの基礎を学びます。
</Card>


## Related topics

- [データベース設定](/jp/database.md)
- [設定リファレンス - VOICEVOX for Laravel](/jp/packages/laravel-voicevox/configuration.md)
- [インストールと設定 - VOICEVOX for Laravel](/jp/packages/laravel-voicevox/installation.md)
- [パッケージ設定のマージとキャッシュ](/jp/advanced/package-config-merging.md)
- [WebSocket (Jetstream / Firehose)](/jp/packages/laravel-bluesky/websocket.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.