PHPackages                             duckdev/wp-queue-process - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. duckdev/wp-queue-process

ActiveLibrary[Queues & Workers](/categories/queues)

duckdev/wp-queue-process
========================

WordPress non-blocking async requests and background queue processing with a swappable storage driver, server-load aware batching, and a self-healing cron.

2.0.0(3w ago)043GPL-2.0-or-laterPHPPHP >=7.4CI passing

Since Aug 1Pushed 2w ago1 watchersCompare

[ Source](https://github.com/duckdev/wp-queue-process)[ Packagist](https://packagist.org/packages/duckdev/wp-queue-process)[ Docs](https://github.com/duckdev/wp-queue-process)[ RSS](/packages/duckdev-wp-queue-process/feed)WikiDiscussions main Synced today

READMEChangelog (4)Dependencies (6)Versions (5)Used By (0)

[ ![](https://camo.githubusercontent.com/838ee08209c53949b986b1d1c9c01b23693a9c2f6438a28e370f26c630223818/68747470733a2f2f6475636b6465762e636f6d2f77702d636f6e74656e742f75706c6f6164732f323032302f31322f63726f707065642d6475636b6465762d6c6f676f2d6d69642e706e67)](http://duckdev.com)

WP Queue Process
================

[](#wp-queue-process)

WP Queue Process is a WordPress library for firing off non-blocking asynchronous requests and for running long jobs as a background queue. Items pushed onto the queue are worked through in batches that bail out before exhausting the server's time or memory budget, each finished batch chains the next instantly, and a self-healing cron restarts a stalled queue.

- Inspired by [TechCrunch WP Asynchronous Tasks](https://github.com/techcrunch/wp-async-task).
- Forked from [WP Background Processing](https://github.com/deliciousbrains/wp-background-processing), modernised with a swappable storage driver, a server-load guard, and a full test suite.

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- WordPress 6.0+
- Composer

Installation
------------

[](#installation)

```
composer require duckdev/wp-queue-process
```

The library autoloads under the `DuckDev\Queue\` namespace via PSR-4.

Architecture
------------

[](#architecture)

Consumers extend one of two abstract classes — `Async` for a one-off request, `Task` for a queue. Everything else is a collaborator that `Task` wires up for you and that you can swap or mock through the constructor. The folder layout mirrors the namespace:

```
src/
├── Async.php                     # Abstract non-blocking request
├── Task.php                      # Abstract background queue (extends Async)
├── Contracts/
│   └── StoreInterface.php        # Where batches are persisted
├── Storage/
│   └── OptionStore.php           # Default driver: (network) options table
├── Support/
│   ├── Batch.php                 # Value object: one stored batch
│   ├── ServerLimits.php          # Time/memory budget guard
│   └── ProcessLock.php           # Single-worker lock (site transient)
└── Exceptions/
    └── QueueException.php

```

`Task` delegates persistence to a `StoreInterface`, load-guarding to `ServerLimits`, and single-worker locking to `ProcessLock`. All three are injected through the constructor (with WordPress-backed defaults), so the batch loop can be unit-tested without a database.

Usage
-----

[](#usage)

### Async Request

[](#async-request)

Async requests are useful for pushing slow one-off tasks — sending an email, warming a cache — to a background process. Once dispatched, the request processes immediately and out of band.

Extend `\DuckDev\Queue\Async`:

```
class WP_Example_Request extends \DuckDev\Queue\Async {

	/**
	 * @var string Unique action name.
	 */
	protected $action = 'example_request';

	/**
	 * Perform the work. The dispatched data is available in $_POST.
	 */
	protected function handle() {
		// Actions to perform.
	}
}
```

Dispatch it (chaining is supported):

```
$this->example_request = new WP_Example_Request();
$this->example_request->data( array( 'value1' => $value1, 'value2' => $value2 ) )->dispatch();
```

### Background Process

[](#background-process)

Background processes queue tasks and work through them in batches. Higher-end servers process more items per batch. A health check runs by default every 5 minutes to restart the queue if it ever fails; queues are processed first-in-first-out, so items can be pushed even while one is already running.

Extend `\DuckDev\Queue\Task`:

```
class WP_Example_Process extends \DuckDev\Queue\Task {

	/**
	 * @var string Unique action name.
	 */
	protected $action = 'example_process';

	/**
	 * Process a single queue item.
	 *
	 * Return the (optionally modified) item to push it back for another
	 * pass, or false to remove it from the queue.
	 *
	 * @param mixed  $item  Queue item to process.
	 * @param string $group Group name the item was saved under.
	 *
	 * @return mixed
	 */
	protected function task( $item, $group ) {
		// Actions to perform.

		return false;
	}

	/**
	 * Optional. Runs once the queue is fully drained.
	 */
	protected function complete() {
		parent::complete();

		// Show a notice, log, etc.
	}
}
```

Instantiate the process **unconditionally** (every request, even when nothing is queued), push items, then save and dispatch:

```
$this->example_process = new WP_Example_Process();

foreach ( $items as $item ) {
	$this->example_process->push_to_queue( $item );
}

// Or set the whole queue at once when the data is already shaped correctly:
// $this->example_process->set_queue( $items );

$this->example_process->save( 'my-group' )->dispatch();
```

#### Public methods

[](#public-methods)

MethodDescription`push_to_queue( $item )`Append a single item to the in-memory queue.`set_queue( array $items )`Replace the in-memory queue wholesale.`save( string $group = 'default' )`Persist the in-memory queue as a new batch.`dispatch()`Schedule the health-check cron and start processing.`update( string $key, array $data )`Replace the items of an existing batch.`delete( string $key )`Delete a batch entirely.`cancel_process()`Drop the current batch and clear the cron.### Swapping the storage driver

[](#swapping-the-storage-driver)

The default `OptionStore` keeps batches in the (network) options table. Pass your own `StoreInterface` — or a custom `ServerLimits` / `ProcessLock` — to the constructor to change where batches live or how aggressively a batch runs:

```
$process = new WP_Example_Process( new MyCustomStore( 'my_plugin_example_process' ) );
```

Filters
-------

[](#filters)

Every filter is namespaced with the process identifier (`{prefix}_{action}`, e.g. `duckdev_example_process`):

FilterDefaultPurpose`{id}_query_args`action + nonceQuery args added to the dispatch URL.`{id}_query_url``admin-ajax.php`URL the request is dispatched to.`{id}_post_args`non-blocking POSTArguments passed to `wp_remote_post()`.`{id}_default_time_limit``20`Per-batch time budget, in seconds.`{id}_time_exceeded`computedOverride whether the time budget is spent.`{id}_memory_exceeded`computedOverride whether the memory budget is spent.`{id}_queue_lock_time``60`Process lock duration, in seconds.`{id}_cron_interval``5`Health-check interval, in minutes.### BasicAuth

[](#basicauth)

If your site is behind BasicAuth, requests rely on the [WordPress HTTP API](https://developer.wordpress.org/plugins/http-api/)and need credentials attached:

```
add_filter( 'http_request_args', function ( $r ) {
	$r['headers']['Authorization'] = 'Basic ' . base64_encode( USERNAME . ':' . PASSWORD );

	return $r;
} );
```

Upgrading from 1.x
------------------

[](#upgrading-from-1x)

The 2.0 release is a structural rewrite. The classes you extend (`Async`, `Task`) and their public methods (`push_to_queue()`, `set_queue()`, `save()`, `dispatch()`, `update()`, `delete()`, `cancel_process()`) and every filter are unchanged, so most consumers only need to bump the requirement.

What changed:

- **PHP 7.4+** is now required (was 5.6); properties and signatures are typed.
- Persistence, load-guarding, and locking moved into injectable collaborators (`StoreInterface`, `ServerLimits`, `ProcessLock`). The internal protected helpers from 1.x (`is_queue_empty()`, `get_batch()`, `memory_exceeded()`, …) were removed — override `task()` / `complete()` or inject a collaborator instead.
- `set_queue()` and `save()` now type-hint their arguments.

Development
-----------

[](#development)

```
composer install
composer test     # PHPUnit (Brain\Monkey, no WordPress install needed)
composer phpcs    # WordPress Coding Standards
composer phpcbf   # Auto-fix coding standard violations
```

### Credits

[](#credits)

- A forked, modernised library of [WP Background Processing](https://github.com/deliciousbrains/wp-background-processing).
- Maintained by [Joel James](https://github.com/joel-james/)

### License

[](#license)

[GPLv2+](http://www.gnu.org/licenses/gpl-2.0.html)

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance96

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~591 days

Total

4

Last Release

23d ago

Major Versions

v1.0.2 → 2.0.02026-06-10

PHP version history (2 changes)v1.0.0PHP >=5.6

2.0.0PHP >=7.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/17586?v=4)[Schmidt](/maintainers/Jo)[@jo](https://github.com/jo)

---

Top Contributors

[![Joel-James](https://avatars.githubusercontent.com/u/7510463?v=4)](https://github.com/Joel-James "Joel-James (8 commits)")

---

Tags

background-processingqueuewordpressasyncwordpressqueuecronbackground processing

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/duckdev-wp-queue-process/health.svg)

```
[![Health](https://phpackages.com/badges/duckdev-wp-queue-process/health.svg)](https://phpackages.com/packages/duckdev-wp-queue-process)
```

###  Alternatives

[jms/job-queue-bundle

Allows to run and schedule Symfony console commands as background jobs.

3452.3M5](/packages/jms-job-queue-bundle)[dereuromark/cakephp-queue

The Queue plugin for CakePHP provides deferred task execution.

308954.9k25](/packages/dereuromark-cakephp-queue)[orisai/scheduler

Cron job scheduler - with locks, parallelism and more

4044.1k5](/packages/orisai-scheduler)[eyewitness/eye

Eyewitness.io client for Laravel 5 applications

116151.8k](/packages/eyewitness-eye)[g4/tasker

Application asynchronous tasks manager and runner, cron-like PHP implementation with ability to run tasks with resolution in seconds

1455.7k](/packages/g4-tasker)[deliciousbrains/wp-image-processing-queue

Resize WordPress images in the background

2061.4k](/packages/deliciousbrains-wp-image-processing-queue)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)