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 Artisandoctor.
--fix.
.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.--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.Modos de entorno
La colasync 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
syncfuera 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
.enven.gitignore, auditoría de dependencias de Composer.
Crear diagnósticos propios
Basta con extenderLaravel\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.
APP_KEY y, si no está definida, la genera automáticamente.
fixOptions(). La CLI mostrará una lista de selección y el valor elegido se pasará a fix().
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 nombresLaravel\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.
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.
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.
Ejecución programática
También puedes invocarDoctor::run() sin usar el comando Artisan.
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.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í.