Laravel Doctor añade comprobaciones reales antes del despliegueLaravel Doctor añade comprobaciones reales antes del despliegue

El problema aparece cuando ya no estás delante

Una aplicación Laravel puede pasar tests, compilar activos y desplegar sin errores aparentes. Aun así, el proceso puede dejar una cola configurada como sync, un directorio sin permisos de escritura o una caché inaccesible. Son fallos que normalmente descubres después del despliegue, con tráfico real o tareas acumulándose. Laravel Doctor plantea una comprobación adicional para detectar esa clase de problemas antes.

No forma parte del instalador base de Laravel: es un paquete first-party que se instala como dependencia de desarrollo. Registra el comando php artisan doctor y ejecuta diagnósticos sobre la configuración, el entorno y servicios que la aplicación tiene configurados. La idea no es sustituir los tests, sino verificar que la aplicación puede operar con la infraestructura que espera encontrar.

composer require laravel/doctor --dev
 
php artisan doctor

Qué revisa el comando

La batería incluida cubre elementos que suelen romperse por diferencias entre desarrollo y producción. Comprueba la existencia de .env, la clave de aplicación, la versión de PHP, extensiones requeridas o recomendadas y la zona horaria. También revisa dependencias de Composer, la carga y caché de configuración, la conexión de base de datos y la existencia de migraciones pendientes.

Doctor también comprueba los drivers activos de caché, colas, sesiones y filesystem. Puede detectar conexiones Redis activas que no responden, avisar si una cola sync se utiliza fuera de un entorno local y confirmar que los directorios necesarios dentro de storage admiten escritura. Si la aplicación espera el enlace público de storage, también valida que exista.

El resultado distingue entre pass, notice, warn, fail, skip y error. Por defecto, un fallo o un error hacen que el comando termine con código de salida no válido. Si quieres que las advertencias bloqueen el proceso, puedes usar --fail-on=warn; si solo buscas un informe sin bloquear el pipeline, existe --fail-on=never.

Una puerta más en CI

Aquí es donde le veo más sentido en proyectos con despliegue propio. No hace falta convertir Doctor en un paso enorme ni ejecutar todos los diagnósticos en cada contexto. Puedes lanzarlo después de instalar dependencias y antes de promocionar una build, ajustando la severidad a lo que de verdad quieras impedir.

- name: Check Laravel deployment health
  run: php artisan doctor --format=github --fail-on=warn

El formato github genera anotaciones para GitHub Actions. Para otros consumidores automatizados está --format=json, mientras que --format=agent devuelve una salida compacta pensada para agentes de código. Además, puedes limitar el alcance con --only o excluir comprobaciones con --except, usando grupos, clases de diagnóstico o paquetes.

php artisan doctor --only=storage
php artisan doctor --except=laravel/*

El modo de entorno importa

Doctor no interpreta igual una aplicación local que una aplicación que sirve tráfico. En local, tener APP_DEBUG activo, una cola sync o cachés de bootstrap ausentes puede ser perfectamente razonable. En producción, esas mismas condiciones pueden convertirse en una advertencia o en un problema que conviene resolver antes de desplegar.

Reconoce de serie los entornos local, production y staging. Si usas nombres como dev, qa o cualquier variante propia, puedes publicar su configuración con php artisan vendor:publish --tag=doctor-config y asignarlos al modo local o producción. Esto merece atención: un entorno desconocido se trata como producción, una decisión conservadora que evita relajar comprobaciones por un nombre poco habitual.

'environments' => [
    'local' => ['local', 'dev'],
    'production' => ['production', 'staging', 'qa'],
],

Reparar lo seguro, no adivinar

La opción --fix puede aplicar reparaciones deterministas sin pedir confirmación. Entre los arreglos incluidos están crear un .env ausente, generar APP_KEY, desactivar el modo debug en producción, ignorar .env en Git, crear el enlace público de storage y corregir permisos de directorios de storage. No intenta decidir cambios que dependan de una elección humana.

Ese límite es importante. Si, por ejemplo, hay varios almacenes de caché posibles, Doctor puede mostrar opciones en ejecución interactiva, pero --fix no elige por su cuenta. Tampoco se permite combinar --fix con los formatos JSON o GitHub, precisamente para que una ejecución destinada a informar no modifique la aplicación. Yo dejaría --fix para máquinas locales o tareas explícitas de mantenimiento, nunca como un efecto secundario del pipeline de despliegue.

La letra pequeña

Doctor no demuestra que tu aplicación funcione de extremo a extremo. Puede validar que la base de datos sea accesible, pero no detectará una consulta lenta, una autorización mal planteada ni un flujo de negocio roto. Para eso siguen haciendo falta tests, observabilidad, alertas y comprobaciones reales tras el despliegue.

Tampoco conoce por defecto cada pieza de tu infraestructura. Si dependes de Horizon, un servicio interno, un bucket con políticas específicas o una API crítica, tendrás que añadir tus propios diagnósticos. El paquete ofrece make:diagnostic para generar una clase y permite registrarla mediante la fachada Doctor, así que se puede extender sin modificar el paquete.

Por último, instalarlo con --dev condiciona dónde estará disponible. Si tu imagen de producción instala Composer con --no-dev, no podrás ejecutarlo dentro de ese contenedor salvo que ajustes esa decisión. En muchos equipos tiene más sentido correrlo en una etapa preparada para validar el release, con una configuración representativa y acceso controlado a los servicios necesarios.

Fuente: Laravel Magazine Documentación oficial: Laravel Doctor