QueueWorker Plugin for CakePHP

---

A lightweight, database-driven job queue plugin for CakePHP 5.
Supports asynchronous task execution, retries, error tracking, admin view, and CLI commands.

Features

• Simple job enqueueing: $queue->createJob('MyTask', [...]);
• CLI workers: bin/cake run_worker
• Task creation: bin/cake bake task MyTask
• Error/retry support
• Pluggable access control via static callback

Installation

You can install this plugin directly from GitHub using Composer:

1. Add the GitHub repository to your app's composer.json:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/mahankals/CakePHP-QueueWorker"
    }
]

2. Require the plugin via Composer:

composer require mahankals/cakephp-queueworker:dev-main

Load the plugin

Method 1: from terminal

bin/cake plugin load QueueWorker

Method 2: load in Application.php, bootstrap method

$this->addPlugin('QueueWorker');

Create tables with migration

  bin/cake migrations migrate --plugin QueueWorker

Permission (optional)

In src/Application.php, bootstrap method

  \QueueWorker\Controller\QueueJobsController::$accessPolicy = fn($req) =>
    $req->getAttribute('identity')?->get('role') === 'admin';

now queue jobs are available on http://localhost:8765/queue-worker/jobs

🛠 Creating a Task and Adding Jobs to the Queue

This plugin uses task classes located in src/Queue/Task/ to execute background jobs.

---

1. 🧱 Create a Task Class

Create a file:
src/Queue/Task/MyTaskTask.php

<?php
namespace App\Queue\Task;

class MyTaskTask
{
    public function run(array $data): void
    {
        // Example job logic
        echo "Running MyTask with data: " . json_encode($data) . PHP_EOL;
    }
}

You can use CLI to generate this:

bin/cake bake task MyTask

2. 📨 Add a Job to the Queue

In any controller, command, or service:

use QueueWorker\QueueWorker;

$queue = new QueueWorker();
$queue->createJob('MyTask', ['user_id' => 42, 'message' => 'Welcome']);

This stores the job in the database table (queue_jobs) and marks it as queued.

3. 🏃 Run the Queue Worker on local

Use the CLI to start processing jobs:

bin/cake queue start

The worker:

• Fetches one job at a time
• Executes the corresponding Task class
• Tracks attempts, errors, and status

3. 🏃 Run the Queue Worker on Production

1. with cronetab

export EDITOR=nano && crontab -e

* * * * * cd /var/www && bin/cake queue start --once >> ./logs/queue_start.log 2>&1

2. with Supervisor

Create /etc/supervisor/conf.d/cake_queue_worker.conf

[program:cake_queue_worker]
directory=/var/www/your-app
command=/usr/bin/php bin/cake queue start
autostart=true
autorestart=true
stderr_logfile=/var/www/your-app/logs/worker_error.log
stdout_logfile=/var/www/your-app/logs/worker_output.log
user=www-data
numprocs=1

Enable & Start Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start cake_queue_worker

Confirm Worker is Running

ps aux | grep 'queue start'

or

sudo supervisorctl status

💡 Tips

You can retry failed jobs manually:

Retry all failed jobs:

bin/cake queue retry

Retry a single job:

bin/cake queue retry 42

You can safely terminate queue worker manually:

bin/cake queue stop

Customization

You can publish templates for customization:

bin/cake queueworker publish