La cola de trabajos
En ocasiones queremos ejecutar procesos en "segundo plano", por ejemplo, actualizar el número de productos de una familia cuando se añade un producto. Este proceso no es fundamental, es decir, no necesitamos ese contador actualizado al momento de añadir el producto. Para este tipo de procesos usamos la cola de trabajos.
La cola de trabajos se ejecuta al final de cada ejecución. Es decir, cada vez que abrimos una página (como por ejemplo un producto o el listado de clientes), al final del proceso se ejecuta la cola de trabajos. Por tanto estos trabajos en "segundo plano" se ejecutan al final y de uno en uno. Por eso se usa para procesos no fundamentales.
Eventos y workers
La cola de trabajos se compone de eventos y workers. Cada vez que se añade un producto, cliente, etc, se lanza un evento. Por otro lado tenemos los workers, que son clases PHP registradas para "escuchar" estos eventos y procesar.
Eventos de los modelos
Todos los modelos lanzan automáticamente eventos cuando se añade, modifica o elimina contenido. Por ejemplo:
- Cuando añadimos un producto se lanzan los eventos
Model.Producto.Insert
yModel.Producto.Save
- Cuando modificamos un producto se lanza el evento
Model.Producto.Update
yModel.Producto.Save
- Cuando eliminamos un producto se lanza el evento
Model.Producto.Delete
Para otros modelos se lanzan los mismos eventos, pero con el nombre del modelo en cuestión.
Lanzar eventos personalizados
Podemos lanzar un evento en cualquier momento llamando a WorkQueue::send()
.
// lanzamos el evento 'test-event' con el valor 'test-value'
WorkQueue::send('test-event', 'test-value');
En la versión 2024.94 se añadió la opción de lanzar eventos para ejecutar pasados unos segundos llamando a WorkQueue::sendFuture()
.
// lanzamos el evento 'test-event' para que se procese en 300 segundos (5 minutos)
WorkQueue::sendFuture(300, 'test-event', 'test-value');
Workers
Los workers son clases PHP que se encuentran en la carpeta Worker y que podemos registrar en la cola de trabajos para procesar ciertos eventos. Este sería un ejemplo básico de worker:
namespace FacturaScripts\Plugins\MiPlugin\Worker;
use FacturaScripts\Core\Model\WorkEvent;
use FacturaScripts\Core\Template\WorkerClass;
class MiWorker extends WorkerClass
{
public function run(WorkEvent $event): bool
{
// tu código aquí
return $this->done();
}
}
Registrar un worker
Para hacer que un worker "escuche" un evento podemos llamar a WorkQueue::addWorker()
en la función init()
del archivo Init.php de nuestro plugin. En el siguiente ejemplo registraremos el worker MiWorker para que escuche el evento de cuando se modifica un producto.
WorkQueue::addWorker('MiWorker', 'Model.Producto.Update');
Con esto conseguimos que nuestro worker se ejecute si se modifica algún producto. Podemos registrar un worker para muchos eventos, simplemente hay que registrarlo varias veces:
WorkQueue::addWorker('MiWorker', 'Model.Producto.Insert');
WorkQueue::addWorker('MiWorker', 'Model.Producto.Delete');
// esta es otra opción
WorkQueue::addWorker('MiWorker', 'Model.Producto.*');
Incluso podemos hacer que escuche todos los eventos:
WorkQueue::addWorker('MiWorker', '*');
Eventos en el Init::update()
El método Init::update()
de los plugins se ejecuta antes del Init::init()
, por lo que si lanzas algún evento en el update, debes añadir los workers necesarios también en el update().
Evitar bucles de eventos
En ocasiones queremos ejecutar un trabajo cuando se modifica un producto, y este trabajo modifica a su vez el producto, por lo que se crea un nuevo evento que desencadena un bucle infinito. Para evitar este problema, podemos desactivar la generación de ese evento en el propio worker llamando al método preventNewEvents()
:
namespace FacturaScripts\Plugins\MiPlugin\Worker;
use FacturaScripts\Core\Model\WorkEvent;
use FacturaScripts\Core\Template\WorkerClass;
class MiWorker extends WorkerClass
{
public function run(WorkEvent $event): bool
{
// evitamos que se creen nuevos eventos de tipo Model.Producto.Save
$this->preventNewEvents(['Model.Producto.Save']);
// tu código aquí
return $this->done();
}
}
Ver la cola de trabajos
Podemos ver la lista de eventos a procesar desde el menú administrador, logs. En la pestaña de eventos de trabajos.