> ## 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 — herramienta de diagnóstico de la aplicación

> Presentación de laravel/doctor. Paquete oficial de Laravel que diagnostica problemas comunes de configuración, entorno e infraestructura y aplica correcciones automáticas cuando son seguras. Se ejecuta con el comando php artisan doctor. Lanzado el 28 de julio de 2026.

## Introducción

[laravel/doctor](https://github.com/laravel/doctor) es el paquete oficial que diagnostica problemas comunes de configuración, entorno e infraestructura en una aplicación Laravel. La v0.1.0 se lanzó el 28 de julio de 2026.

Cada diagnóstico es una única comprobación. Por ejemplo, inspecciona «si Laravel puede escribir en el directorio storage» y reporta uno de varios estados posibles. Cuando es posible reparar de forma segura y determinista, ofrece una corrección automática; para los problemas que no pueden repararse automáticamente, como un fallo en la compilación de assets, se muestran los pasos de remediación.

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

## Cómo ejecutarlo

Tras la instalación, se registra el comando Artisan `doctor`.

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

Si Doctor encuentra un problema que puede corregir, reporta el problema y pide confirmación para aplicar la corrección.

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

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

Si quieres aplicar la corrección sin confirmación, usa la opción `--fix`.

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

Las correcciones estándar cubren reparaciones locales deterministas: crear `.env`, generar `APP_KEY`, deshabilitar el modo debug en producción, añadir `.env` a `.gitignore`, crear `storage:link`, arreglar los permisos de escritura del directorio storage, etc.

<Info>
  La funcionalidad de corrección solo está disponible en los formatos de salida CLI y agent. En los formatos de reporte JSON y GitHub, `--fix` se rechaza para que el reporte legible por máquina no altere la aplicación.
</Info>

Con `--bail`, la ejecución se detiene en el primer diagnóstico que resulte fallido o con error.

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

## Estados de los diagnósticos

Cada diagnóstico devuelve uno de los siguientes estados.

| Estado   | Significado                                                      | Afecta al código de salida |
| -------- | ---------------------------------------------------------------- | -------------------------- |
| `pass`   | La comprobación se supera sin problemas                          | No                         |
| `notice` | Información que merece la pena transmitir al desarrollador       | No                         |
| `warn`   | Problema potencial que puede no requerir acción                  | Solo con `--fail-on=warn`  |
| `fail`   | Se detecta un problema que hay que resolver                      | Sí                         |
| `error`  | Se ha lanzado una excepción durante la ejecución del diagnóstico | Sí                         |
| `skip`   | No aplica al entorno actual                                      | No                         |

Por defecto, si hay un `fail` o un `error`, se termina con estado de fallo. Con `--fail-on=warn` también fallan las advertencias; con `--fail-on=never`, solo se reportan los problemas.

## Selección de diagnósticos

Puedes seleccionar o excluir diagnósticos por nombre de clase, grupo, paquete o comodín de paquete.

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

php artisan doctor --only=StorageIsWritable

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

Si publicas el archivo de configuración, también puedes fijar selecciones de forma permanente.

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

## Modos de entorno

La cola `sync` es un valor por defecto razonable en desarrollo local, pero en producción significa que los jobs de la cola se ejecutan de forma síncrona dentro de la petición web. Para tomar este tipo de decisiones, Doctor resuelve la aplicación a uno de dos modos: `local` o `production`.

| Modo         | Estado esperado                                                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `local`      | En desarrollo. El modo debug, la cola `sync` y no tener cacheados los archivos de bootstrap es normal                                     |
| `production` | Sirve tráfico real. El modo debug es un riesgo de seguridad, la cola debe ser asíncrona y los archivos de bootstrap deben estar cacheados |

Los nombres de entorno estándar de Laravel `local`, `production` y `staging` se reconocen automáticamente. Si usas otros nombres, agrúpalos por modo en el archivo de configuración.

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

## Diagnósticos estándar

Doctor incluye por defecto una suite de diagnósticos que abarca los siguientes ámbitos.

* **Entorno** — existencia de `.env`, `APP_KEY`, versión de PHP, extensiones necesarias, zona horaria.
* **Composer** — estado de instalación de dependencias, optimización del autoload, autorreparación de `composer.lock`.
* **Configuración** — posibilidad de leer y cachear los archivos de configuración, valores requeridos por los drivers activos.
* **Base de datos** — accesibilidad de la conexión, existencia del archivo SQLite, aplicación automática de migraciones pendientes.
* **Caché, colas, scheduler y sesiones** — accesibilidad de los drivers configurados, detección de cola `sync` fuera de producción.
* **Storage** — accesibilidad del disco por defecto, permisos de escritura de los directorios necesarios, existencia de `storage:link`.
* **Seguridad** — coherencia entre modo debug y entorno, registro de `.env` en `.gitignore`, auditoría de dependencias de Composer.

## Crear diagnósticos propios

Basta con extender `Laravel\Doctor\Diagnostic` e implementar el método `check()` para crear una clase de diagnóstico propia. También hay scaffolding con el comando Artisan `make:diagnostic`.

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

A continuación se muestra un ejemplo de diagnóstico que comprueba la configuración de `APP_KEY` y, si no está definida, la genera automáticamente.

```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');
    }
}
```

Cuando tenga sentido ofrecer opciones de corrección, puedes declararlas con `fixOptions()`. La CLI mostrará una lista de selección y el valor elegido se pasará a `fix()`.

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

Al final de la lista de selección siempre se añade una opción para saltarse la corrección (por defecto `Skip — leave unfixed`). Si conviene expresarlo como «mantener la selección actual», puedes especificar la etiqueta `decline`.

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

### Helpers para diagnósticos

Como muchas aplicaciones y paquetes acaban repitiendo el mismo tipo de comprobaciones, Doctor ofrece helpers para patrones frecuentes en el espacio de nombres `Laravel\Doctor\Support`.

El helper `Configured` lee los valores de configuración de forma defensiva. Como los diagnósticos deben poder inspeccionar aplicaciones con configuración rota sin lanzar excepciones antes de reportar, estos métodos —a diferencia de los accesores tipados del repositorio de configuración— no lanzan excepciones ante tipos inesperados.

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

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

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

El helper `ActiveDrivers` resuelve los drivers envolventes —como el canal de logs por defecto `stack` o el mailer `failover`— a los canales o mailers concretos que se están utilizando realmente.

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

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

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

El helper `Details` formatea la información probatoria que se adjunta con `withDetails()`. `Details::bullets()` convierte una lista de cadenas en viñetas, `Details::failures()` genera mensajes de fallo con clave y `Details::processOutput()` selecciona el stream de salida más útil de un proceso finalizado.

```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.']);
```

Los paquetes pueden registrar sus propios diagnósticos desde un service provider con la misma API.

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

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

El reporte muestra el paquete de origen de cada diagnóstico.

```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.
```

## Ejecución programática

También puedes invocar `Doctor::run()` sin usar el comando Artisan.

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

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

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

Si además quieres aplicar correcciones desde la ejecución programática, configura `fixUsing`. El callback recibe un diagnóstico fallido que ofrece corrección y puede devolver `false` para omitir, `true` para aplicar la corrección estándar, o el valor de una opción de corrección para aplicar la corrección con esa selección. Cuando se aplica una corrección, Doctor vuelve a ejecutar el diagnóstico para reflejar el resultado en el reporte.

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

$report->fixes();
```

## Formatos de salida y soporte para agentes de IA

Doctor emite por defecto una salida CLI legible, pero también admite los formatos JSON y de anotaciones de GitHub Actions.

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

php artisan doctor --format=github
```

Cuando detecta que se está ejecutando dentro de un agente de codificación de IA como Claude Code o Cursor mediante [Laravel Agent Detector](https://github.com/laravel/agent-detector), el formato por defecto pasa a ser el formato optimizado para agentes, que sigue las mismas convenciones que [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}]}
```

Los problemas con `fixable: true` pueden corregirse volviendo a ejecutar `--fix`. Para probar este formato fuera de un agente, ejecuta `AI_AGENT=test php artisan doctor`.

## Resumen

`laravel/doctor` es una herramienta que, con solo ejecutar `php artisan doctor`, permite detectar rápidamente problemas de configuración, entorno e infraestructura de la aplicación. Su afinidad con los agentes de codificación de IA también es alta: emite una salida fácil de interpretar por agentes siguiendo las mismas convenciones que Laravel PAO, así que merece la pena valorar integrarlo en flujos de CI/CD o en flujos de reparación automática mediante agentes de IA.

<Card title="Repositorio de laravel/doctor" icon="github" href="https://github.com/laravel/doctor">
  El código fuente y la información más reciente están aquí.
</Card>


## Related topics

- [FAQ de la nueva estructura de aplicación de Laravel 11 y posteriores](/es/advanced/app-structure-faq.md)
- [Herramientas](/es/packages/laravel-copilot-sdk/tools.md)
- [Laravel y el desarrollo con IA](/es/ai.md)
- [Laravel LSP — extensión de funciones del IDE mediante Language Server Protocol](/es/blog/laravel-lsp-introduction.md)
- [Nuevo ecosistema de análisis de código de Laravel — surveyor / ranger / roster](/es/blog/laravel-ecosystem-analysis.md)