Composer
composer require rwsite/wp-queue
Вручную
Laravel Horizon-like queue manager for WordPress
Simple, powerful, and modern background job processing.
Features • Installation • Quick Start • Admin UI • REST API • Testing • RU version
wp-content/plugins/wp-queuecomposer installuse WPQueueJobsJob;
use WPQueueAttributes{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());
}
}
use WPQueueWPQueue;
// 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();
// 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);
});
#[Schedule]#[Schedule('hourly')] // Fixed interval
#[Schedule('daily', setting: 'my_opt')] // From wp_options
Available intervals: min, 5min, 10min, 15min, 30min, hourly, 2hourly, 3hourly, 6hourly, 8hourly, 12hourly, daily, twicedaily, weekly
#[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')]
// 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
});
use WPQueueWPQueue;
// 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
Access via WP Admin → WP Queue
| Tab | Description |
|---|---|
| Dashboard | Stats (pending, running, completed, failed), queue management |
| Scheduled Jobs | WP Queue jobs with "Run Now" button |
| Logs | Execution history with filtering |
| WP-Cron | All WordPress cron events monitoring |
| System | Environment status and health check |
View and manage all WordPress cron events:
Health check and environment info:
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
Two independent settings, both chosen in Queues → Drivers and System → Status (or with wp queue config):
| Driver | Description | Requirements |
|---|---|---|
database |
{prefix}queue_jobs table, atomic claim (default) |
None |
redis |
Lua scripts: atomic claim, delayed/reserved sets, crash recovery | phpredis or Predis (Redis Object Cache) |
memcached |
Not recommended: jobs can't be listed or moved | memcached extension |
| Runner | How jobs start |
|---|---|
auto (default) |
Fastest available: daemon if its heartbeat is fresh (< 10 min), else loopback, wp_cron, sync. The admin shows the actual runner and why |
daemon |
System cron or a daemon runs wp queue work --all (crontab line and heartbeat are shown in the admin) |
loopback |
Non-blocking POST to admin-ajax.php after dispatch (like Action Scheduler) |
wp_cron |
wp_queue_process WP-Cron event |
sync |
At the end of the request that dispatched the job |
Switching the driver with Make active moves waiting jobs (ready and delayed) to the new backend under the global worker lock; it is refused while jobs are being executed.
Precedence: constant in wp-config.php → plugin option → default.
define('WP_QUEUE_DRIVER', 'redis'); // database | redis | memcached
define('WP_QUEUE_RUNNER', 'daemon'); // auto | daemon | loopback | wp_cron | sync
// Legacy, still honoured: WP_QUEUE_RUNTIME_MODE ('daemon' | 'cron_loopback'), WP_QUEUE_LOOPBACK (false disables loopback)
// 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);
A constant anywhere in wp-config.php locks the setting in the admin ("set in wp-config.php"). Constants inside the plugin's own block stay editable from the admin:
// BEGIN WP Queue
// Managed by WP Queue (Tools > Queues). Edit in the admin or here.
define('WP_QUEUE_DRIVER', 'redis');
// END WP Queue
The plugin rewrites only this block: temp file + atomic rename, owner and permissions preserved, backup, PHP syntax check and a WordPress load check over HTTP; on failure the backup is restored. If the file is not writable, the admin shows the block to paste manually. Requires manage_options; every form has a nonce.
wp queue config # show driver, runner, reason, heartbeat
wp queue config --driver=redis --store=wp-config # move jobs, save in the WP Queue block
wp queue config --runner=daemon # save in the plugin option
See docs/runners-and-drivers.md for details.
use WPQueueWPQueue;
use WPQueueContractsQueueInterface;
// 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']);
});
If you use Redis Object Cache plugin, WP Queue will automatically use the same Redis connection settings. No additional configuration needed!
// 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
as_schedule_recurring_action(time(), HOUR_IN_SECONDS, 'my_hourly_task');
add_action('my_hourly_task', function() {
// task code
});
#[Schedule('hourly')]
class MyHourlyTask extends Job
{
public function handle(): void
{
// task code
}
}
// Register
add_action('wp_queue_schedule', fn($s) => $s->job(MyHourlyTask::class));
| Feature | Action Scheduler | WP Queue |
|---|---|---|
| Database | 2 custom tables | wp_options |
| API | 20+ functions | 1 facade |
| PHP version | 7.4+ | 8.3+ |
| Registration | Manual | Attributes |
| Retry logic | Complex | #[Retries(3)] |
| UI | Built-in | Built-in |
| File count | 50+ | ~15 |
WP Queue uses a CI-first testing approach with comprehensive test coverage.
Fast isolated tests without WordPress environment:
composer test:unit
Results: 69 tests, 130 assertions ✅
Integration tests with real WordPress run automatically in CI:
E2E tests run on every push to main/develop branches and in pull requests.
# Code style check
composer lint
# Run all tests
composer test
Note: Code coverage requires PCOV or Xdebug extension. In Docker environments, use:
docker exec wp_site-php composer lint
docker exec wp_site-php composer test:unit
See: tests/README.md
See a complete working example: wp-queue-example-plugin
The example plugin demonstrates:
Perfect for learning how to integrate WP Queue into your WordPress plugins!
GPL-2.0-or-later