Nhance uses a database-backed job queue for long-running or deferred work. A producer adds a row into the jobs table through Jobs::addJob(), and the CLI worker in JobWorker picks up queued rows, executes the mapped handler, and writes the final status and response back to the same record.

Overview

The queue flow is simple: enqueue, store, process, update. It is used for tasks such as file validation, employee processing, claim import work, API sync jobs, bulk mail, and batch e-card generation.

Queueing jobs

New jobs are inserted through Jobs::addJob(array $payload). The method validates the input, generates a UUID, JSON-encodes the inner payload, and stores the row with status queued unless a custom status is provided.

$job = Jobs::addJob([
    'job_name' => 'memberDataListExcelFileFormatValidation',
    'payload'  => [
        'lead_id' => $lead_id,
        'age_validation' => true,
    ],
]);

The method returns an array with id, uuid, and job_name. Real code paths already use this pattern, for example after lead placement data is saved and then queued for validation.

Worker lifecycle

JobWorker is the execution engine. It defines four statuses: queued, running, done, and failed.

1. processJobs() fetches all queued rows

   Jobs are selected from jobs ordered by created_dt ASC.

2. Each queued row is forwarded to processJob()

   The worker can process the next queued row, or a specific id plus uuid pair.

3. Status changes to running

   Once picked, the worker updates the row before invoking the handler.

4. The handler receives the decoded payload

   The worker resolves the handler from the event map and passes the job payload into it.

5. The row is finalized

   After execution, the worker stores the final status, runtime, and response JSON back into the same job row.

Handler registry

Every executable job must be registered in JobWorker::$event_class_mapping. Each entry defines a handler category and a target class or function.

Resolution order inside the worker is:

1. Look up the job name in the mapping

   If the name is missing, the worker throws an exception and marks the job failed.

2. Instantiate the mapped class for CC or HC

   The mapped class must exist.

3. Choose the callable

   If a method matching the job name exists, it is used first; otherwise the worker falls back to handle().

4. For HF, call the mapped function directly

   The handler value itself is treated as the callable.

Sample handlers

The app/Controllers/Jobs/ directory currently contains two simple examples that show the expected pattern for small job classes:

namespace App\Controllers\Jobs;

use App\Controllers\PublicController;

class ExampleJob extends PublicController
{
    public function handle($payload)
    {
        return [
            'ok' => true,
            'received' => $payload,
        ];
    }
}

Status lifecycle

The queue storage model is app/Models/JobModel.php, which maps to the jobs table and allows these main fields:

Failure behavior

Both worker-level failures and handler-level failures are caught and written back into jobs.response as structured JSON. The stored data includes the error message, file, line, trace, and whether the failure happened in the task or the worker wrapper.

Running via CLI

The worker is exposed through CLI routes in app/Config/Routes.php.

php spark cli/processjob
php spark cli/processjobs

There is also a web route named processjob, but operationally this queue should be treated as a CLI worker flow.

Live runner script

For live environments where the worker should keep polling continuously, a simple shell loop can call the queue worker across all required applications. Use the root-level phpqueue.sh script and replace the placeholder app paths with your deployment-specific values.

#!/bin/bash

PHP_BIN="${PHP_BIN:-/usr/bin/php}"

# Dummy example paths for documentation.
# Replace each one with the real public/index.php path in that environment.
APP_INDEXES=(
    "/var/www/example-suite/zenith-app/public/index.php"
    "/var/www/example-suite/enrolment-app/public/index.php"
    "/var/www/example-suite/partner-api/public/index.php"
)

while true; do
    echo "Running job at $(date)"

    for index_file in "${APP_INDEXES[@]}"; do
        "${PHP_BIN}" "${index_file}" cli/processjob
    done

    sleep 1
done

Systemd service

For Ubuntu-style live deployments, keep a systemd unit file such as nhance_php_queue_server.service. The repository now includes a sanitized template with placeholder values.

[Unit]
Description=Nhance PHP Queue Server
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/example-suite/nhance-app
ExecStart=/bin/bash /var/www/example-suite/nhance-app/phpqueue.sh
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target

After replacing the placeholders, deploy and enable it with standard systemd commands:

sudo mv nhance_php_queue_server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable nhance_php_queue_server.service
sudo systemctl start nhance_php_queue_server.service
sudo systemctl restart nhance_php_queue_server.service

Permissions setup

The queue runner script should live in the project root as phpqueue.sh, and its ownership plus execute permission should be set for the service user and group used by PHP in that environment.

sudo chown <service-user>:<service-group> phpqueue.sh
sudo chmod 750 phpqueue.sh

Checking status

app/Libraries/JobStatusService.php now supports lookup by job name, by job id, and by job uuid. All methods normalize the decoded response and runtime before returning them.

$service = new \App\Libraries\JobStatusService();
$status = $service->getJobStatusByName('bulkGenerateEcardAndStoreinS3');

$job = Jobs::addJob([
    'job_name' => 'exampleJob',
    'payload' => [
        'file_id' => 123,
    ],
]);

$service = new \App\Libraries\JobStatusService();
$statusById = $service->getJobStatusById((int) $job['id']);
$statusByUuid = $service->getJobStatusByUuid($job['uuid']);

The service returns success, job_name, status, response, job_id, uuid, run_time, and a message.

Adding a new handler

1. Create the handler class or function

   For small custom jobs, app/Controllers/Jobs/ is already used as a simple home for dedicated job handlers.

2. Register the job in JobWorker::$event_class_mapping

   Pick the correct type: CC, HC, or HF.

3. Expose a callable method

   The worker first looks for a method matching the job name, then falls back to handle().

4. Queue the job through Jobs::addJob()

   Pass a stable job name and only the payload fields the handler actually needs.

5. Run the worker and inspect the job row

   Validate the final status, runtime, and response before integrating the job into larger workflows.

// 1. Register in JobWorker::$event_class_mapping
'exampleJob' => [
    'type' => 'CC',
    'handler' => 'App\Controllers\Jobs\ExampleJob',
],

// 2. Queue it
Jobs::addJob([
    'job_name' => 'exampleJob',
    'payload' => [
        'file_id' => 123,
        'source' => 'manual-test',
    ],
]);