Download the PHP package deverity/spawn-queue without Composer

SpawnQueue — CakePHP Queue Plugin

A robust queue engine for CakePHP 4 that runs each job in its own isolated process, eliminating the most common failure modes of long-lived single-process workers.

Why SpawnQueue?

Requirements

• PHP 8.1+
• CakePHP 4.5+
• MySQL 8.0+ or MariaDB 10.6+ (for SELECT … FOR UPDATE SKIP LOCKED) Older versions fall back automatically — see Claim Strategy
• Linux recommended for production (graceful shutdown via POSIX signals)

Installation

Via Composer

Load the plugin in src/Application.php:

Local / in-monorepo development

Add the namespace to your app's composer.json autoload:

Run the migration

SpawnQueue auto-detects whether dereuromark/cakephp-queue is already installed:

• Table exists → adds only the 4 missing columns (queue, max_attempts, pid, failed_at)
• Fresh install → creates the full queued_jobs table from scratch

Configuration

Override defaults in config/app_local.php or any file loaded in your bootstrap:

Creating Handlers

Implement JobHandlerInterface for new-style handlers:

Dependency note: Handlers are instantiated with new ClassName(). Use LocatorAwareTrait, ConnectionManager, or other CakePHP service locators for dependencies — constructor injection is not supported in this version.

Exception / return reference

Legacy dereuromark/cakephp-queue Tasks

Existing tasks that extend Queue\Queue\Task work without any modification. SpawnQueue wraps them automatically via LegacyTaskAdapter:

Enqueuing Jobs

Running the Coordinator

Run one coordinator per queue when you want separate OS processes, independent restart control, or stronger isolation between high-traffic queues:

For smaller deployments, queue:work-all starts one long-running process that manages every configured queue:

queue:work-all reads queue names from Configure::read('SpawnQueue.queues'). Both config shapes are supported:

If no queues are configured, queue:work-all falls back to default. Internally it still creates one QueueCoordinator per queue, each with its own worker pool and timeout settings, but all coordinators share a single parent process and one combined TUI dashboard.

Use queue:work-all when operational simplicity matters more than per-queue process isolation. Use separate queue:work <queue> processes when one queue has heavy traffic, long-running jobs, or different restart/deploy needs.

Commands Reference

Terminal Output Modes

Controlled by SpawnQueue.show_type config or the --show CLI option:

Note: In tui mode the log lines from child processes are suppressed. The dashboard refreshes in-place — do not redirect stdout to a file in this mode.

Job States

Production Setup

Supervisor (recommended)

Single process for all queues:

Separate process per queue:

systemd

Single process for all queues:

Separate process per queue:

Deploy without downtime

Architecture

Claim Strategy

SpawnQueue tries SELECT … FOR UPDATE SKIP LOCKED first. On older databases (MySQL < 8.0, MariaDB < 10.6) it falls back to a conditional UPDATE — safe but may cause minor contention on very busy queues.

Migrating from dereuromark/cakephp-queue

1. Install SpawnQueue and run the migration (adds columns, keeps all existing jobs)
2. Keep dereuromark installed — your app still uses it to write jobs
3. Stop the old bin/cake queue:worker processes
4. Start SpawnQueue coordinators
5. Gradually migrate task classes to implement JobHandlerInterface
6. Once all tasks are migrated, remove the dereuromark dependency

SpawnQueue picks up both old-style (no queue column) and new-style jobs. Old jobs are routed to the default coordinator.

Backoff Schedule

Override for a specific failure: throw new RetryableJobException($msg, retryAfterSeconds: 3600);

License

MIT