Creating and Dispatching Queue Jobs

Introduction

This guide explains how to create, register, and dispatch custom background jobs inside the Zero CMS Job Queue system. It walks through building a stateless job, queueing it from code, and running the processing pipeline.

Step 1: Build a Stateless Job Class

Every background job in the system must implement the Zero\Interfaces\Job interface. To maintain loose coupling, place your jobs inside your module's Jobs/ directory. Keep the job class stateless; all dynamic data should be passed via a primitive parameters payload:

<?php

namespace Zero\Modules\Shop\Jobs;

use Exception;
use Zero\Core\App;
use Zero\Core\Env;
use Zero\Database\DB;
use Zero\Interfaces\BlockHelperInterface;
use Zero\Interfaces\Controller;
use Zero\Interfaces\Job as JobInterface;
use Zero\Interfaces\Model;
use Zero\Interfaces\SeederInterface;
use Zero\Models\Traits\HasSlug;
use Zero\Models\Traits\IsModel;
use App\Modules\Blog\Models\Post;
use Zero\Modules\Search\Traits\Searchable;
use Zero\Modules\Shop\Jobs\SendOrderReceipt;
use Zero\Support\Emailer;
use Zero\Support\Security;

class SendOrderReceipt implements JobInterface
{
    public function execute(array $payload): void
    {
        $orderId = $payload['order_id'];
        $email = $payload['email'];
        
        // Execute raw SMTP Socket mailer
        Emailer::send($email, "Order Receipt #{$orderId}", "Thank you for your purchase!");
    }
}

Step 2: Dispatch the Job to the Queue

To queue your task, invoke the static QueueManager::dispatch() helper from anywhere in your application (controllers, hooks, model events, etc.). The dispatcher automatically serializes parameters to JSON and generates a unique UUIDv7 tracking ID:

use Zero\Modules\Queue\Support\QueueManager;
// Queue receipt dispatching
$jobId = QueueManager::dispatch(
    jobClass: SendOrderReceipt::class,
    payload: [
        'order_id' => $order->id,
        'email' => $order->customer_email
    ]
);

Step 3: Process the Job Queue

To run the background processor, you can use either the console runner or trigger the API endpoint:

Console Command: Execute the processing script sequentially:
```
php bin/queue-runner
```
Web Endpoint Callback: Make an HTTP POST call to the webhook processor callback endpoint:
```
curl -X POST http://mysite.zero/api/v1/queue/process
```