Workers

Workers are long-running processes that poll the database for pending jobs, execute them, and advance workflows. They run from a minimal PHP bootstrap without loading WordPress.

Starting a worker

wp queuety work

This starts a single worker on the default queue. It runs in a loop: claim a job, execute it, repeat. When the queue is empty, it sleeps for QUEUETY_WORKER_SLEEP seconds (default: 1) before polling again.

Options

# Process a specific queue
wp queuety work --queue=emails

# Process one batch and exit (useful for cron-based setups)
wp queuety work --once

# Run 4 concurrent workers
wp queuety work --workers=4

Multi-queue priorities

A single worker can process multiple queues in priority order. Pass a comma-separated list of queue names to --queue:

wp queuety work --queue=critical,default,low

The worker tries to claim a job from each queue in the listed order. It checks critical first. If critical has a job, it processes that job. If critical is empty, it moves on to default, and then to low. This means higher-priority queues always drain before lower-priority ones.

How priority ordering works

On each iteration of the worker loop:

1. Try to claim from the first queue in the list
2. If that queue is empty (or paused), try the next queue
3. Repeat until a job is claimed or all queues are exhausted
4. If no job is found in any queue, sleep and retry

This is a strict priority model. A steady stream of critical jobs will starve default and low. If you need guaranteed throughput on lower-priority queues, use dedicated workers instead (see below).

Using multi-queue in PHP

The Worker::run() and Worker::flush() methods accept either a string or an array:

// Comma-separated string
Queuety::worker()->run( 'critical,default,low' );

// Array
Queuety::worker()->run( [ 'critical', 'default', 'low' ] );

// flush() also supports multi-queue
$count = Queuety::worker()->flush( 'critical,default,low' );

Deployment strategies

Dedicated workers per queue give you full control over concurrency and isolation. Each queue gets its own worker process(es) and cannot be starved by other queues:

[program:queuety-critical]
command=wp queuety work --queue=critical
numprocs=4

[program:queuety-default]
command=wp queuety work --queue=default
numprocs=2

[program:queuety-low]
command=wp queuety work --queue=low
numprocs=1

Priority ordering with a single worker is simpler to manage and works well when lower-priority queues can tolerate delays:

[program:queuety-worker]
command=wp queuety work --queue=critical,default,low
numprocs=2

You can also combine both approaches: dedicated workers for critical to guarantee throughput, and a priority-ordered worker for everything else:

[program:queuety-critical]
command=wp queuety work --queue=critical
numprocs=2

[program:queuety-fallback]
command=wp queuety work --queue=default,low
numprocs=2

Worker lifecycle

A worker stops gracefully when any of these conditions are met:

After stopping, the worker exits cleanly. In production, a process manager restarts it automatically.

Multi-worker concurrency

The --workers=N flag forks N child processes using pcntl_fork(). Each child creates its own database connection and processes jobs independently. The parent process monitors children and restarts any that crash.

wp queuety work --queue=default --workers=4

Requirements:

• The pcntl PHP extension must be installed
• Each child uses its own database connection, so ensure your MySQL max_connections can accommodate the pool

Stale job recovery

If a worker crashes while processing a job, the job is left in processing status. Queuety automatically detects jobs that have been in processing longer than QUEUETY_STALE_TIMEOUT seconds and resets them to pending.

Recover stale jobs manually:

wp queuety recover

Flush mode

Process all pending jobs and exit. Useful for testing or one-off batch processing:

wp queuety flush
wp queuety flush --queue=emails

Production deployment

For production, use a process manager to keep workers running. Here are two common approaches.

Supervisord

[program:queuety-default]
command=wp queuety work --queue=default
directory=/var/www/html
autostart=true
autorestart=true
numprocs=2
process_name=%(program_name)s_%(process_num)02d
stdout_logfile=/var/log/queuety-default.log
stderr_logfile=/var/log/queuety-default-error.log

[program:queuety-emails]
command=wp queuety work --queue=emails
directory=/var/www/html
autostart=true
autorestart=true
numprocs=1
stdout_logfile=/var/log/queuety-emails.log
stderr_logfile=/var/log/queuety-emails-error.log

Systemd

[Unit]
Description=Queuety Worker (default queue)
After=mysql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/html
ExecStart=/usr/local/bin/wp queuety work --queue=default
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable queuety-worker
sudo systemctl start queuety-worker

Deployment tips

• Run separate workers for separate queues to isolate workloads
• Use --workers=N for CPU-bound handlers, individual workers for I/O-bound handlers
• Set QUEUETY_WORKER_MAX_JOBS to force periodic restarts and free memory
• Monitor the buried count and set up alerts using webhooks or metrics