WP Queue

Features

Requirements

Installation

Quick Start

Create a Job

use WPQueue\Jobs\Job;
use WPQueue\Attributes\{Schedule, Queue, Timeout, Retries};
#[Schedule('hourly')]
#[Queue('imports')]
#[Timeout(120)]
#[Retries(5)]
class ImportProductsJob extends Job
{
 public function __construct(
 private array $productIds
 ) {
 parent::__construct();
 }
 public function handle(): void
 {
 foreach ($this->productIds as $id) {
 // Import logic here
 }
 }
 
 public function failed(\Throwable $e): void
 {
 // Handle failure
 error_log('Import failed: ' . $e->getMessage());
 }
}

Dispatch Jobs

use WPQueue\WPQueue;
// Dispatch to queue
WPQueue::dispatch(new ImportProductsJob([1, 2, 3]));
// With delay (seconds)
WPQueue::dispatch(new ImportProductsJob($ids))->delay(60);
// To specific queue
WPQueue::dispatch(new ImportProductsJob($ids))->onQueue('high-priority');
// Synchronous (bypass queue)
WPQueue::dispatchSync(new ImportProductsJob($ids));
// Chain jobs
WPQueue::chain([
 new FetchProductsJob(),
 new ImportProductsJob($ids),
 new NotifyAdminJob(),
])->dispatch();
// Batch jobs
WPQueue::batch([
 new ImportProductJob($id1),
 new ImportProductJob($id2),
 new ImportProductJob($id3),
])->dispatch();

Schedule Jobs

// In your plugin
add_action('wp_queue_schedule', function ($scheduler) {
 // Using attributes (automatic)
 $scheduler->job(ImportProductsJob::class);
 
 // Manual scheduling
 $scheduler->job(CleanupJob::class)->daily();
 
 // Custom interval
 $scheduler->job(CheckStopListJob::class)->everyMinutes(15);
 
 // Conditional
 $scheduler->job(SyncJob::class)
 ->hourly()
 ->when(fn() => get_option('sync_enabled'));
 
 // From settings
 $scheduler->job(BackupJob::class)
 ->interval(get_option('backup_interval', 'daily'));
 // One-time execution (at specific timestamp)
 $scheduler->job(OneTimeJob::class)->at(time() + 3600);
});

PHP 8 Attributes

#[Schedule]

#[Schedule('hourly')] // Fixed interval
#[Schedule('daily', setting: 'my_opt')] // From wp_options

#[Queue]

#[Queue('default')] // Queue name
#[Queue('high')] // Priority queue

#[Timeout]

#[Timeout(60)] // 60 seconds
#[Timeout(300)] // 5 minutes

#[Retries]

#[Retries(3)] // Max 3 attempts
#[Retries(5)] // Max 5 attempts

#[UniqueJob]

#[UniqueJob] // Prevent duplicate jobs
#[UniqueJob(key: 'custom_key')]

Events (Hooks)

// Before job execution
add_action('wp_queue_job_processing', function($event) {
 // $event->job, $event->queue
});
// After successful execution
add_action('wp_queue_job_processed', function($event) {
 // $event->job, $event->queue
});
// On failure
add_action('wp_queue_job_failed', function($event) {
 // $event->job, $event->queue, $event->exception
});
// On retry
add_action('wp_queue_job_retrying', function($event) {
 // $event->job, $event->queue, $event->attempt, $event->exception
});

Queue Management

use WPQueue\WPQueue;
// Check status
WPQueue::isProcessing('default'); // bool
WPQueue::isPaused('default'); // bool
WPQueue::queueSize('default'); // int
// Control
WPQueue::pause('default');
WPQueue::resume('default');
WPQueue::cancel('default'); // Clear + pause
WPQueue::clear('default'); // Remove all jobs
// Logs
WPQueue::logs()->recent(100);
WPQueue::logs()->failed();
WPQueue::logs()->forJob(ImportProductsJob::class);
WPQueue::logs()->metrics();
WPQueue::logs()->clearOld(7); // Clear logs older than 7 days

Admin UI

Tabs

WP-Cron Monitor

System Status

REST API

GET  /wp-json/wp-queue/v1/queues
POST  /wp-json/wp-queue/v1/queues/{queue}/pause
POST  /wp-json/wp-queue/v1/queues/{queue}/resume
POST  /wp-json/wp-queue/v1/queues/{queue}/clear
POST  /wp-json/wp-queue/v1/jobs/{job}/run
GET  /wp-json/wp-queue/v1/logs
POST  /wp-json/wp-queue/v1/logs/clear
GET  /wp-json/wp-queue/v1/metrics
# Cron & System
GET  /wp-json/wp-queue/v1/cron
POST  /wp-json/wp-queue/v1/cron/run
POST  /wp-json/wp-queue/v1/cron/delete
GET  /wp-json/wp-queue/v1/system

Queue Drivers

Configuration

// Select queue driver
define('WP_QUEUE_DRIVER', 'redis'); // or 'memcached', 'database', 'sync', 'auto'
// Redis settings (compatible with redis-cache plugin)
define('WP_REDIS_HOST', 'redis'); // or '127.0.0.1'
define('WP_REDIS_PORT', '6379');
define('WP_REDIS_PREFIX', 'mysite_'); // optional
define('WP_REDIS_PASSWORD', 'secret'); // optional
define('WP_REDIS_DATABASE', 0); // optional, 0-15
// Memcached settings
define('WP_MEMCACHED_HOST', '127.0.0.1');
define('WP_MEMCACHED_PORT', 11211);

Programmatic Configuration

use WPQueue\WPQueue;
use WPQueue\Contracts\QueueInterface;
// Set driver programmatically
WPQueue::manager()->setDefaultDriver('redis');
// Check available drivers
$drivers = WPQueue::manager()->getAvailableDrivers();
// ['database' => ['available' => true, 'info' => '...'], ...]
// Check if specific driver is available
if (WPQueue::manager()->isDriverAvailable('redis')) {
 WPQueue::manager()->setDefaultDriver('redis');
}
// Register custom driver
WPQueue::manager()->extend('sqs', function() {
 return new SqsQueue(['region' => 'us-east-1']);
});

Redis with redis-cache Plugin

// These constants from redis-cache are automatically used:
// WP_REDIS_HOST, WP_REDIS_PORT, WP_REDIS_PASSWORD, WP_REDIS_DATABASE
// WP_REDIS_PREFIX, WP_REDIS_SCHEME, WP_REDIS_PATH, WP_REDIS_TIMEOUT

Migration from Action Scheduler

Before (Action Scheduler)

as_schedule_recurring_action(time(), HOUR_IN_SECONDS, 'my_hourly_task');
add_action('my_hourly_task', function() {
 // task code
});

After (WP Queue)

#[Schedule('hourly')]
class MyHourlyTask extends Job
{
 public function handle(): void
 {
 // task code
 }
}
// Register
add_action('wp_queue_schedule', fn($s) => $s->job(MyHourlyTask::class));

Comparison with Action Scheduler

Testing

Unit Tests (Local)

composer test:unit

E2E Tests (GitHub Actions)

Code Quality

# Code style check
composer lint
# Run all tests
composer test

docker exec wp_site-php composer lint
docker exec wp_site-php composer test:unit

Example Plugin

License