Bucle de Verificación Laravel

Ejecutar antes de PRs, después de cambios importantes y antes del despliegue.

Cuándo Usar

• Antes de abrir un pull request para un proyecto Laravel
• Después de refactorizaciones importantes o actualizaciones de dependencias
• Verificación previa al despliegue para staging o producción
• Ejecutar el pipeline completo de lint -> prueba -> seguridad -> preparación para despliegue

Cómo Funciona

• Ejecutar las fases secuencialmente desde las verificaciones de entorno hasta la preparación para despliegue, de modo que cada capa construya sobre la anterior.
• Las verificaciones de entorno y Composer son requisitos previos para todo lo demás; detener inmediatamente si fallan.
• El linting/análisis estático debe estar limpio antes de ejecutar pruebas completas y cobertura.
• Las revisiones de seguridad y migraciones ocurren después de las pruebas para verificar el comportamiento antes de los pasos de datos o lanzamiento.
• La preparación de build/despliegue y las verificaciones de cola/scheduler son los últimos filtros; cualquier fallo bloquea el lanzamiento.

Fase 1: Verificaciones de Entorno

php -v
composer --version
php artisan --version

• Verificar que .env esté presente y que las claves requeridas existan
• Confirmar APP_DEBUG=false para entornos de producción
• Confirmar que APP_ENV coincida con el despliegue objetivo (production, staging)

Si se usa Laravel Sail localmente:

./vendor/bin/sail php -v
./vendor/bin/sail artisan --version

Fase 1.5: Composer y Autoload

composer validate
composer dump-autoload -o

Fase 2: Linting y Análisis Estático

vendor/bin/pint --test
vendor/bin/phpstan analyse

Si el proyecto usa Psalm en lugar de PHPStan:

vendor/bin/psalm

Fase 3: Pruebas y Cobertura

php artisan test

Cobertura (CI):

XDEBUG_MODE=coverage php artisan test --coverage

Ejemplo de pipeline CI (formato -> análisis estático -> pruebas):

vendor/bin/pint --test
vendor/bin/phpstan analyse
XDEBUG_MODE=coverage php artisan test --coverage

Fase 4: Seguridad y Verificación de Dependencias

composer audit

Fase 5: Base de Datos y Migraciones

php artisan migrate --pretend
php artisan migrate:status

• Revisar cuidadosamente las migraciones destructivas
• Asegurarse de que los nombres de archivo de migración sigan el formato Y_m_d_His_* (ej. 2025_03_14_154210_create_orders_table.php) y describan el cambio claramente
• Asegurarse de que los rollbacks sean posibles
• Verificar los métodos down() y evitar la pérdida irreversible de datos sin copias de seguridad explícitas

Fase 6: Preparación de Build y Despliegue

php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

• Asegurarse de que los warmups de caché tengan éxito en la configuración de producción
• Verificar que los workers de cola y el scheduler estén configurados
• Confirmar que storage/ y bootstrap/cache/ sean escribibles en el entorno objetivo

Fase 7: Verificaciones de Cola y Scheduler

php artisan schedule:list
php artisan queue:failed

Si se usa Horizon:

php artisan horizon:status

Si queue:monitor está disponible, usarlo para verificar el backlog sin procesar jobs:

php artisan queue:monitor default --max=100

Verificación activa (solo staging): despachar un job no-op a una cola dedicada y ejecutar un solo worker para procesarlo (asegurarse de que esté configurada una conexión de cola que no sea sync).

php artisan tinker --execute="dispatch((new App\\Jobs\\QueueHealthcheck())->onQueue('healthcheck'))"
php artisan queue:work --once --queue=healthcheck

Verificar que el job produjera el efecto secundario esperado (entrada de log, fila en tabla de healthcheck o métrica).

Ejecutar esto solo en entornos que no sean producción donde procesar un job de prueba sea seguro.

Ejemplos

Flujo mínimo:

php -v
composer --version
php artisan --version
composer validate
vendor/bin/pint --test
vendor/bin/phpstan analyse
php artisan test
composer audit
php artisan migrate --pretend
php artisan config:cache
php artisan queue:failed

Pipeline estilo CI:

composer validate
composer dump-autoload -o
vendor/bin/pint --test
vendor/bin/phpstan analyse
XDEBUG_MODE=coverage php artisan test --coverage
composer audit
php artisan migrate --pretend
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan schedule:list