Colas y trabajo programado

Esta guía cubre las dos cosas que pasan fuera de una petición web: los jobs que esperan en una cola a un worker, y las tareas que el programador corre con un reloj. La necesitas cuando un job no corre, cuando un despliegue no surtió efecto en segundo plano, o cuando agregas trabajo propio.

La conexión de la cola

config/queue.php lee QUEUE_CONNECTION, por omisión database: los jobs son filas de la tabla jobs, que las migraciones del kit crean, y los jobs fallidos van a failed_jobs (driver database-uuids). No hace falta ningún servicio extra. Las conexiones y sus variables:

QUEUE_FAILED_DRIVER (por omisión database-uuids) elige dónde se guardan los jobs fallidos. Los lotes de jobs usan la tabla job_batches.

Lo que el kit encola

Lo que no se encola, para que sepas dónde buscar cuando algo va lento: las notificaciones construidas sobre App\Notifications\Notification se envían durante la petición, fila de base de datos, correo y push incluidos, porque la clase base usa Queueable sin ShouldQueue. El código de verificación de correo se envía de forma sincrónica con Mail::mailer(...)->send(), y el código por SMS también sale de forma sincrónica. Agrega implements ShouldQueue a una notificación tuya cuando se reparte a muchas personas; el job de avisos es el patrón para hacerlo en masa.

Para crear un job en cola usa el stub del proyecto, que ya implementa ShouldQueue:

php artisan make:job Orders/ArchiveOldOrders

Corre el worker en local

composer dev arranca cuatro procesos en una terminal: php artisan serve, php artisan queue:listen --tries=1, php artisan pail --timeout=0 (la cola del log) y npm run dev. Un job que despaches corre un momento después y su salida aparece en la misma terminal. queue:listen recarga el código en cada job, así que no lo reinicias después de editar una clase de job; por eso se usa aquí y no en producción.

Si prefieres no correr un worker, pon QUEUE_CONNECTION=sync en tu .env local. Todo corre en línea y las excepciones aparecen en la petición que las causó.

Corre el worker en producción

El worker es un proceso de larga vida:

php artisan queue:work --sleep=3 --tries=3 --max-time=3600

queue:work carga la aplicación una vez y la mantiene en memoria, que es lo que lo hace rápido y lo que lo deja viejo después de un despliegue. Mantenlo vivo con Supervisor; el bloque de programa completo está en /help/deploy-your-project. --sleep=3 es la pausa cuando la cola está vacía, --tries=3 los intentos antes de marcar un job como fallido, y --max-time=3600 la vida tras la cual el worker sale para que Supervisor lo reinicie.

Agrega --queue=high,default para atender varias colas con nombre en orden de prioridad, y --timeout=60 para matar un job que corra más de un minuto (mantenlo por debajo del retry_after de la conexión).

Reinícialo en cada despliegue

php artisan queue:restart

El comando escribe una marca de tiempo en el caché; cada worker la revisa después de cada job y sale cuando es más nueva que su propio arranque. Supervisor entonces arranca un worker nuevo, que carga el código nuevo. Dos consecuencias: el almacén de caché tiene que ser uno que compartan el worker y el proceso web (database o redis, nunca array), y un job que está corriendo cuando lo llamas termina primero. Sin este comando el worker sigue ejecutando la versión anterior: una notificación cuyo texto cambiaste sigue llegando con el texto viejo hasta que el worker muera por casualidad.

Jobs fallidos

Un job que lanza una excepción en cada uno de sus --tries intentos cae en failed_jobs con su excepción. La excepción también se reporta por los canales normales: el log, y Slack cuando SLACK_BOT_TOKEN está definido.

php artisan queue:failed            # listarlos, con id, conexión, cola y fecha
php artisan queue:retry 9f1c-...    # devolver uno a la cola por su id
php artisan queue:retry all         # devolverlos todos
php artisan queue:forget 9f1c-...   # borrar uno sin reintentar
php artisan queue:flush             # borrarlos todos
php artisan queue:prune-failed --hours=168   # borrar los de más de una semana

Reintenta después de corregir la causa y reiniciar el worker; reintentar un job sobre el código viejo lo vuelve a fallar.

Tareas programadas

El programador corre todo lo registrado con Schedule:: en routes/console.php y en los service providers de los paquetes. Dos tareas vienen con el kit:

Las horas están en la zona horaria de la aplicación, UTC en config/app.php. php artisan schedule:list imprime la tabla con la próxima ejecución de cada una.

Nada corre a menos que cron llame al programador cada minuto:

* * * * * cd /var/www/your-project && php artisan schedule:run >> /dev/null 2>&1

schedule:run mira el reloj, corre lo que toque y sale. En local, php artisan schedule:work hace lo mismo en primer plano una vez por minuto, y php artisan schedule:test te deja elegir una tarea y correrla ahora.

Agrega las tuyas

Un job va en app/Jobs, un comando en app/Console/Commands (se registra solo), y su programación en routes/console.php:

Schedule::command('orders:archive-old')->dailyAt('03:00');
Schedule::job(new ArchiveOldOrders)->weeklyOn(1, '04:00');

Un comando programado que tarda, o que no debe traslaparse consigo mismo, lleva ->withoutOverlapping(); uno que deba correr en un solo servidor cuando tienes varios lleva ->onOneServer(), que necesita un almacén de caché compartido.