Cómo diseñar una cola de tareas para operaciones lentas en PHP

Una operación que tarda varios segundos puede dejar una petición HTTP abierta, consumir recursos del servidor web y ofrecer al usuario una experiencia incierta si la conexión se interrumpe. Los procesos en segundo plano en PHP permiten aceptar el trabajo y ejecutarlo fuera del ciclo de vida de esa petición. Para que la solución sea útil, no basta con añadir una cola: hay que definir qué recibe el usuario, cómo consulta el estado y qué ocurre ante una interrupción.

Reconocer qué operaciones deben ejecutarse en segundo plano

Conviene evaluar el impacto de una operación, no aplicar una regla basada únicamente en su duración. Una tarea puede ser candidata si su tiempo es variable, requiere esperar a un sistema externo o procesa muchos elementos. Algunos ejemplos son generar un informe extenso, importar un archivo, transformar documentos o sincronizar datos con una API.

En cambio, si el usuario necesita una decisión inmediata para continuar —como validar un dato esencial antes de guardar— puede ser mejor mantener esa parte en la petición y separar únicamente el trabajo posterior. También hay tareas lentas que requieren una respuesta síncrona por requisitos de negocio. La arquitectura debe responder a las necesidades del flujo, no convertir cada operación en un trabajo asíncrono.

Antes de cambiar el diseño, identifica cuánto tarda la operación, qué parte consume ese tiempo y qué pasa si falla. Una cola no corrige por sí sola consultas ineficientes, límites mal configurados ni dependencias externas inestables; puede trasladar esos problemas a los trabajadores de fondo.

Responder con una tarea aceptada, no con un resultado inventado

Cuando el trabajo se acepta para ejecución posterior, la respuesta de la aplicación debe distinguir claramente entre aceptado y completado. Puede devolver un identificador de tarea y una indicación de que el procesamiento está pendiente. No debe presentar como terminado un resultado que todavía no existe.

Una estimación de duración sólo es apropiada si hay información suficiente para calcularla y comunicar su incertidumbre. En muchos sistemas es más honesto mostrar un estado como “en cola” o “procesando” que prometer una hora de finalización. Si la tarea puede completarse con rapidez, la interfaz aún puede consultar el estado y mostrar el resultado cuando esté disponible, sin bloquear la petición original.

Define también qué ocurre si falla el envío a la cola: la aplicación no debe confirmar la aceptación si no puede registrar de forma fiable el trabajo. El mecanismo concreto depende de la arquitectura, pero la respuesta y el estado persistido deben ser coherentes.

Definir estados y transiciones válidas

Un ciclo de vida pequeño y explícito facilita la experiencia del usuario y la operación. Como base, se pueden contemplar pendiente, en_proceso, cancelacion_solicitada, completada, fallida y cancelada. Los nombres pueden variar; las transiciones, en cambio, deben ser válidas y verificables, no una combinación libre de estados.

• Transiciones normales: pendiente → en_proceso y, desde en_proceso, completada o fallida.
• Cancelación antes de empezar: pendiente → cancelada si se confirma que el trabajador aún no inició el trabajo.
• Cancelación durante la ejecución: en_proceso → cancelacion_solicitada. Desde ese estado, la tarea pasa a cancelada si se detiene de forma segura; puede pasar a completada si terminó antes de atender la solicitud, o a fallida si se produjo un error.
• Estados finales: completada, fallida y cancelada no deberían volver a estados activos. Si se permite repetir una tarea, crea una nueva ejecución o define expresamente un ciclo distinto.

El sistema debe impedir transiciones no permitidas y registrar cuándo se produjo cada cambio. Si un trabajador se interrumpe y deja una tarea en en_proceso, no la marques automáticamente como completada. Una política de recuperación puede devolverla a pendiente cuando sea seguro reanudarla, o marcarla como fallida para revisión. La decisión depende de si el trabajo puede retomarse sin duplicar efectos. La coordinación de reintentos e idempotencia requiere decisiones propias; no debe confundirse con el modelo visible de estados.

Comunicar progreso, resultado y errores

El progreso debe basarse en hitos medibles. Si no es posible calcular un porcentaje real, es preferible informar la fase (“validando datos”, “generando informe”) o mantener el estado “en proceso”. Un porcentaje que se queda inmóvil o retrocede sin explicación reduce la confianza.

Al completar, ofrece el resultado de negocio: por ejemplo, un resumen de elementos procesados o una referencia al recurso generado, sujeto a permisos y disponibilidad. El estado de la tarea no tiene por qué almacenar todo el resultado. Puede guardar una referencia a datos gestionados por el dominio de la aplicación.

Al fallar, presenta un mensaje que ayude a decidir el siguiente paso, como corregir un archivo o volver a intentarlo cuando corresponda. Registra por separado el error técnico necesario para diagnóstico, con acceso restringido. No expongas trazas, credenciales, rutas internas ni datos sensibles en la interfaz o en una API pública.

Tratar la cancelación como una solicitud con límites

Cancelar una tarea no siempre significa que pueda detenerse inmediatamente. Un trabajador puede estar ejecutando una llamada externa, escribiendo datos o dentro de una fase que no admite interrupciones seguras. Por eso, la interfaz debe distinguir entre cancelacion_solicitada y cancelada: la primera indica que se recibió la petición; la segunda, que el sistema confirmó la detención.

La implementación puede comprobar una señal de cancelación en puntos seguros y dejar de iniciar pasos posteriores. Si el efecto ya se confirmó en un sistema externo, no debe afirmarse que se deshizo. Explica al usuario qué resultado cabe esperar y registra quién solicitó la cancelación cuando esa información sea relevante para auditoría.

Separar el registro de tarea del resultado de negocio

El registro de una tarea sirve para coordinar ejecución y consulta: puede incluir un identificador, estado, fechas, solicitante y referencias de diagnóstico. El resultado de negocio —por ejemplo, un informe o los registros importados— pertenece al modelo de datos que representa ese resultado.

Separarlos evita que una tarea con información temporal se convierta en la única fuente del negocio. También permite definir retención: cuánto tiempo se conserva el estado, cuándo se elimina un archivo y qué información debe mantenerse por obligaciones operativas o normativas. Los estados antiguos no deberían acumularse sin política de limpieza.

Proteger las consultas y limitar el consumo de recursos

Consultar una tarea requiere autorización igual que consultar cualquier otro recurso. El identificador no sustituye el control de acceso: verifica que la persona o sistema solicitante puede ver esa tarea y su resultado. Limita también la frecuencia y el volumen de consultas para evitar sondeos excesivos, y considera notificaciones cuando el caso de uso no necesite actualizaciones constantes.

La ejecución debe tener límites de concurrencia y recursos adecuados al tipo de trabajo. Demasiados trabajadores pueden saturar la base de datos, servicios externos o almacenamiento; muy pocos pueden acumular tareas y retrasar resultados. Observa el volumen pendiente, la antigüedad de las tareas y las duraciones, además de los errores. Esas señales ayudan a distinguir una dependencia lenta de un problema de capacidad.

Probar el ciclo completo antes de desplegar

Las pruebas de aceptación deben cubrir el comportamiento visible y la persistencia, no sólo que el trabajador invoque una función. Comprueba al menos estos escenarios:

• La petición crea una tarea y devuelve una referencia sin afirmar que ya terminó.
• Una tarea completada muestra el estado final y permite acceder al resultado con los permisos correctos.
• Una tarea fallida comunica un mensaje seguro y deja información diagnóstica accesible al equipo autorizado.
• Una tarea abandonada o interrumpida no permanece indefinidamente como “en proceso”; existe una forma operativa de detectarla y tratarla.
• Una solicitud de cancelación respeta las fases seguras y no promete revertir efectos ya realizados.

En un sistema existente, introduce el cambio por una operación acotada y valida también la experiencia cuando la cola está retrasada o no disponible. La aplicación necesita una respuesta clara para esos casos: informar que no pudo aceptar el trabajo, ofrecer una alternativa segura o permitir que el usuario vuelva a intentarlo. La decisión depende del impacto de la operación y de las garantías que el negocio pueda sostener.

Lista de comprobación para introducir una cola en un sistema existente

Antes de habilitar el procesamiento en segundo plano, revisa estos puntos con los equipos responsables de la aplicación y de su operación:

• Alcance: se ha elegido una operación concreta y se ha definido qué parte sigue siendo síncrona y qué trabajo se ejecuta en segundo plano.
• Persistencia: la aceptación de la tarea y su estado se guardan de forma coherente; existe una política para interrupciones, recuperación y cambios de estado.
• Contrato con el usuario: la respuesta inicial distingue aceptación de finalización, y la interfaz explica cómo consultar progreso, resultado y errores.
• Permisos y datos: consultar una tarea o su resultado requiere autorización; se minimizan los datos almacenados y se restringe el acceso a diagnósticos.
• Recursos: se han fijado límites de concurrencia, tiempo de ejecución, memoria y frecuencia de consulta adecuados para la operación y sus dependencias.
• Observabilidad: se pueden detectar acumulación, tareas antiguas en proceso, fallos y duración anómala sin incluir secretos en los registros.
• Retención: se ha decidido cuánto conservar los estados, resultados, archivos y datos de diagnóstico, y cómo eliminarlos de forma controlada.
• Pruebas y operación: se han probado los caminos de finalización, fallo, cancelación e interrupción, y el equipo sabe qué hacer si la cola no acepta trabajo o se retrasa.

Desplegar el código no equivale a habilitar de inmediato todos los flujos: puedes introducir la nueva ruta de ejecución de forma gradual y comprobar sus señales antes de ampliarla. Mantén una alternativa operativa apropiada si la cola o sus trabajadores no están disponibles; no confirmes trabajos que el sistema no haya podido registrar.