> ## 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` 큐는 로컬 개발에서는 타당한 기본값이지만, 프로덕션 환경에서는 큐 잡이 웹 요청 내에서 동기 실행되는 것을 의미합니다. 이러한 판단을 위해 Doctor는 애플리케이션을 `local` 또는 `production` 두 가지 모드로 해결합니다.

| 모드           | 기대되는 상태                                                      |
| ------------ | ------------------------------------------------------------ |
| `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 이후의 애플리케이션 구조](/ko/advanced/app-structure.md)
- [Laravel Nightwatch 입문](/ko/blog/nightwatch-introduction.md)
- [Laravel 10에서 11로의 업그레이드](/ko/blog/upgrade-10-to-11.md)
- [Laravel 신규 코드 해석 에코시스템 — surveyor / ranger / roster](/ko/blog/laravel-ecosystem-analysis.md)
- [설치](/ko/installation.md)