> ## 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 Doctor — アプリケーション診断ツール

> laravel/doctorの紹介。設定・環境・インフラの一般的な問題を診断し、安全なものは自動修正するLaravel公式パッケージ。php artisan doctorコマンドで実行。2026年7月28日リリース。

## はじめに

[laravel/doctor](https://github.com/laravel/doctor) は、Laravelアプリケーションにおける一般的な設定・環境・インフラストラクチャの問題を診断する公式パッケージです。2026年7月28日にv0.1.0がリリースされました。

それぞれの診断（diagnostic）は単一のチェックです。例えば「Laravelがstorageディレクトリに書き込めるか」を検査し、複数のステータスのいずれかを報告します。安全かつ決定的に修復できる場合は自動修正も提供され、アセットビルド失敗のように自動修復できない問題には対応手順（remediation）が提示されます。

```bash theme={null}
composer require laravel/doctor --dev
```

## 実行方法

インストール後、`doctor` Artisanコマンドが登録されます。

```bash theme={null}
php artisan doctor
```

修正可能な問題が見つかると、Doctorは問題を報告したうえで修正の確認を求めます。

```text theme={null}
Storage is writable: The application cannot write to every required storage directory.

 Make the storage directories writable? (yes/no) [yes]
```

確認なしで修正を適用したい場合は `--fix` オプションを使います。

```bash theme={null}
php artisan doctor --fix
```

標準の修正は、`.env` の作成、`APP_KEY` の生成、本番環境でのデバッグモード無効化、`.env` の `.gitignore` 追加、`storage:link` の作成、storageディレクトリの書き込み権限修復など、決定的なローカル修復をカバーします。

<Info>
  修正機能はCLIとagent出力形式でのみ利用可能です。JSONおよびGitHubレポート形式では、機械可読なレポートがアプリケーションを変更しないよう`--fix`は拒否されます。
</Info>

`--bail` を使うと、失敗またはエラーになった最初の診断で実行を停止します。

```bash theme={null}
php artisan doctor --bail
```

## 診断ステータス

各診断は次のいずれかのステータスを返します。

| ステータス    | 意味                | 終了コードに影響               |
| -------- | ----------------- | ---------------------- |
| `pass`   | チェックに成功し問題なし      | なし                     |
| `notice` | 開発者に伝える価値のある情報    | なし                     |
| `warn`   | 対応が不要な場合もある潜在的な問題 | `--fail-on=warn` の場合のみ |
| `fail`   | 解決すべき問題を検出        | あり                     |
| `skip`   | 現在の環境には該当しない      | なし                     |
| `error`  | 診断の実行中に例外が発生      | あり                     |

デフォルトでは `fail` または `error` があると失敗ステータスで終了します。`--fail-on=warn` で警告でも失敗させたり、`--fail-on=never` で問題の報告のみに留めることもできます。

## 診断の選択

クラス名・グループ・パッケージ・パッケージのワイルドカードで診断を選択・除外できます。

```bash theme={null}
php artisan doctor --only=storage

php artisan doctor --only=StorageIsWritable

php artisan doctor --except=laravel/*
```

設定ファイルを公開すれば、永続的な選択設定も可能です。

```bash theme={null}
php artisan vendor:publish --tag=doctor-config
```

## 環境モード

`sync` キューはローカル開発では妥当なデフォルトですが、本番環境ではキュージョブがWebリクエスト内で同期実行されてしまうことを意味します。このような判断のため、Doctorはアプリケーションを `local` または `production` の2つのモードに解決します。

| モード          | 期待される状態                                                           |
| ------------ | ----------------------------------------------------------------- |
| `local`      | 開発中。デバッグモード、`sync` キュー、未キャッシュのbootstrapファイルは正常                    |
| `production` | 実トラフィックを処理。デバッグモードはセキュリティリスク、キューは非同期実行、bootstrapファイルはキャッシュ済みであるべき |

Laravel標準の `local`・`production`・`staging` という環境名は自動認識されます。それ以外の名前を使う場合は設定ファイルでモードにグループ分けします。

```php theme={null}
'environments' => [
    'local' => ['local', 'dev'],
    'production' => ['production', 'staging', 'qa'],
],
```

## 標準診断

Doctorには以下を含む診断スイートが標準で搭載されています。

* **環境** — `.env` の存在、`APP_KEY`、PHPバージョン、必要な拡張機能、タイムゾーン
* **Composer** — 依存関係のインストール状態、オートロード最適化、`composer.lock` の自動修復
* **設定** — 設定ファイルの読み込み・キャッシュ可否、有効なドライバーが必要とする設定値
* **データベース** — 接続の到達性、SQLiteファイルの存在、保留中マイグレーションの自動適用
* **キャッシュ・キュー・スケジューラ・セッション** — 設定済みドライバーの到達性、本番環境外の `sync` キュー検出
* **ストレージ** — デフォルトディスクの到達性、必要ディレクトリの書き込み権限、`storage:link` の存在
* **セキュリティ** — デバッグモードと環境の整合性、`.env` の `.gitignore` 登録、Composer依存関係の監査

## 独自診断の作成

`Laravel\Doctor\Diagnostic` を継承し `check()` メソッドを実装するだけで独自の診断クラスを作成できます。`make:diagnostic` Artisanコマンドでスキャフォールドも可能です。

```bash theme={null}
php artisan make:diagnostic HorizonIsRunning --fixable
```

以下は `APP_KEY` の設定を確認し、未設定であれば自動生成する診断の例です。

```php theme={null}
namespace App\Doctor\Diagnostics;

use Illuminate\Support\Facades\Artisan;
use Laravel\Doctor\Contracts\Fixable;
use Laravel\Doctor\Diagnostic;
use Laravel\Doctor\EnvironmentMode;
use Laravel\Doctor\Results\DiagnosticResult;
use Laravel\Doctor\Results\FixResult;

class ApplicationKeyIsSet extends Diagnostic implements Fixable
{
    public string $name = 'App key is set';

    public string $group = 'environment';

    protected function messages(): array
    {
        return [
            'configured' => 'The application key is configured.',
            'missing' => 'The application key is not configured.',
            'generated' => 'The application key was generated.',
        ];
    }

    public function check(): DiagnosticResult
    {
        $key = config('app.key');

        if (is_string($key) && trim($key) !== '') {
            return $this->pass('configured');
        }

        return $this->fail('missing')->fixable(EnvironmentMode::Local);
    }

    public function fix(DiagnosticResult $result): FixResult
    {
        Artisan::call('key:generate', ['--force' => true]);

        return $this->fixed('generated');
    }
}
```

選択肢のある修正が妥当な場合は、`fixOptions()` で選択肢を宣言できます。CLIはこれを選択リストとして表示し、選ばれた値が `fix()` に渡されます。

```php theme={null}
return $this->fail('unreachable')
    ->fixable(EnvironmentMode::Local)
    ->fixOptions(['file' => 'File', 'redis' => 'Redis']);
```

選択リストの末尾には常に修正を見送る選択肢が追加されます（デフォルトは `Skip — leave unfixed`）。現在の選択を保つ表現の方が分かりやすい場合は `decline` ラベルを指定できます。

```php theme={null}
->fixOptions(['file' => 'File'], decline: 'Keep Redis (repair it manually)');
```

### 診断ヘルパー

多くのアプリケーションやパッケージは同じような種類のチェックを繰り返し書くことになるため、Doctorは `Laravel\Doctor\Support` 名前空間で頻出パターン向けのヘルパーを提供しています。

`Configured` ヘルパーは設定値を防御的に読み取ります。診断は設定が壊れたアプリケーションも報告前に例外を投げずに検査できる必要があるため、これらのメソッドは設定リポジトリの型付きアクセサとは違い、想定外の型でも例外を投げません。

```php theme={null}
use Laravel\Doctor\Support\Configured;

$connection = Configured::string('queue.default', 'database');

$missing = Configured::missing([
    'services.stripe.key',
    'services.stripe.secret',
]);
```

`ActiveDrivers` ヘルパーは、デフォルトのログチャンネルが `stack` であったりメーラーが `failover` であったりするラッパードライバーを、実際に使われている具体的なチャンネルやメーラーに解決します。

```php theme={null}
use Laravel\Doctor\Support\ActiveDrivers;

$channels = ActiveDrivers::logChannels(Configured::string('logging.default', 'stack'));

$mailers = ActiveDrivers::mailers(Configured::string('mail.default', 'log'));
```

`Details` ヘルパーは `withDetails()` に添付する証拠情報を整形します。`Details::bullets()` は文字列のリストを箇条書きに、`Details::failures()` はキー付き失敗メッセージを、`Details::processOutput()` は完了したプロセスから最も有用な出力ストリームを選択します。

```php theme={null}
use Laravel\Doctor\Support\Details;

Details::bullets(['services.stripe.key', 'services.stripe.secret']);

Details::failures(['media' => 'The disk root is not writable.']);
```

パッケージも同じAPIでサービスプロバイダーから診断を登録できます。

```php theme={null}
use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;

public function boot(): void
{
    Doctor::diagnostic(HorizonIsRunning::class);
}
```

レポートには診断の提供元パッケージが表示されます。

```text theme={null}
[fail] Storage is writable (laravel/doctor): The application cannot write to every required storage directory.
[warn] Horizon is running (laravel/horizon): Horizon is not currently running.
```

## プログラムからの実行

Artisanコマンドを使わずに `Doctor::run()` を呼び出すこともできます。

```php theme={null}
use Laravel\Doctor\Facades\Doctor;

$report = Doctor::only('security')
    ->except(SomeDiagnostic::class)
    ->run();

if ($report->hasFailures()) {
    // ...
}
```

プログラム実行で修正も適用したい場合は `fixUsing` を設定します。コールバックは修正を提供する失敗診断を受け取り、`false` でスキップ、`true` で通常の修正を適用、または修正オプションの値を返してその選択で修正を適用します。修正が適用されると、Doctorはレポートに反映させるため診断を再実行します。

```php theme={null}
$report = Doctor::fixUsing(
    fn ($outcome) => $outcome->fixRequiresOption() ? false : true,
)->run();

$report->fixes();
```

## 出力形式とAIエージェント対応

Doctorはデフォルトで読みやすいCLI出力を行いますが、JSONやGitHub Actionsアノテーション形式も選択できます。

```bash theme={null}
php artisan doctor --format=json

php artisan doctor --format=github
```

[Laravel Agent Detector](https://github.com/laravel/agent-detector) を使ってClaude CodeやCursorのようなAIコーディングエージェント内での実行を検出すると、[Laravel PAO](https://github.com/laravel/pao) と同じ規約に従ったエージェント最適化フォーマットがデフォルトになります。

```json theme={null}
{"tool":"doctor","result":"failed","diagnostics":27,"failed":1,"warnings":1,"notices":0,"passed":19,"skipped":6,"issues":[{"name":".env file exists","status":"fail","summary":"The application does not have an environment file.","fix":"Run `cp .env.example .env`, then review the copied values.","fixable":true}]}
```

`fixable: true` の問題は `--fix` の再実行で修正できます。エージェント外でこのフォーマットを試す場合は `AI_AGENT=test php artisan doctor` を実行します。

## まとめ

`laravel/doctor` は、`php artisan doctor` の実行だけでアプリケーションの設定・環境・インフラの問題を素早く洗い出せるツールです。AIコーディングエージェントとの親和性も高く、Laravel PAOと同じ規約でエージェントが解釈しやすい出力を返すため、CI/CDやAIエージェントによる自動修復ワークフローへの組み込みも検討する価値があります。

<Card title="laravel/doctor リポジトリ" icon="github" href="https://github.com/laravel/doctor">
  ソースコードと最新情報はこちら。
</Card>


## Related topics

- [Laravel 11以降のアプリケーション構造](/jp/advanced/app-structure.md)
- [インストール](/jp/installation.md)
- [Laravel Boost](/jp/boost.md)
- [Laravel MCP](/jp/mcp.md)
- [リクエストライフサイクル](/jp/lifecycle.md)