Skip to main content

Introducción

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.

Cómo ejecutarlo

Tras la instalación, se registra el comando Artisan doctor.
Si Doctor encuentra un problema que puede corregir, reporta el problema y pide confirmación para aplicar la corrección.
Si quieres aplicar la corrección sin confirmación, usa la opción --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.
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.
Con --bail, la ejecución se detiene en el primer diagnóstico que resulte fallido o con error.

Estados de los diagnósticos

Cada diagnóstico devuelve uno de los siguientes estados. 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.
Si publicas el archivo de configuración, también puedes fijar selecciones de forma permanente.

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

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.
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.
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().
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.

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.
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.
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.
Los paquetes pueden registrar sus propios diagnósticos desde un service provider con la misma API.
El reporte muestra el paquete de origen de cada diagnóstico.

Ejecución programática

También puedes invocar Doctor::run() sin usar el comando Artisan.
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.

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.
Cuando detecta que se está ejecutando dentro de un agente de codificación de IA como Claude Code o Cursor mediante Laravel Agent Detector, el formato por defecto pasa a ser el formato optimizado para agentes, que sigue las mismas convenciones que Laravel PAO.
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.

Repositorio de laravel/doctor

El código fuente y la información más reciente están aquí.
Última modificación el 2 de agosto de 2026