Download the PHP package wptechnix/wp-background-jobs without Composer

WP Background Jobs

A simple, reliable background job queue for WordPress plugins. Define a job, dispatch it, and let it run outside the current request. It has zero runtime dependencies, its own indexed database tables, atomic job reservation that is safe under concurrency, and automatic retries with backoff.

It is built for plugins that need background work without pulling in a heavy queue stack, and it scales from a small site running on WP-Cron to a large one draining the queue with WP-CLI.

Key Features

• 🧱 Object jobs - extend one class, implement handle(), dispatch it.
• 🗂️ Dedicated, indexed tables - no wp_options bloat, no LIKE scans.
• 🔒 Atomic reservation - a compare-and-swap claim prevents double processing on every MySQL and MariaDB version, with no SKIP LOCKED requirement.
• 🔁 Retries with backoff - configurable per job, with a failed-jobs table you can retry, list, or clear from PHP or WP-CLI.
• ⏱️ Delayed and named queues - schedule work for later and route it to named queues.
• 🚀 Three ways to run - an instant async kick, a WP-Cron watchdog safety net, and a WP-CLI worker for scale.
• 🧩 No runtime dependencies - observability comes from action hooks, so nothing can conflict with the host environment.
• 🛡️ Job class allowlist - restrict which classes can be unserialized for defense-in-depth against payload injection.
• 🛡️ Conflict-free by design - table names and hook names are derived from a per-plugin key, so two plugins never collide.
• 🌐 Multisite ready - all state is per-blog (tables, options, lock, cron), so every site runs an independent queue. See Getting Started.

Installation

Requirements: PHP 8.0+, WordPress 5.0+, Composer.

Quick Start

1. Create the manager and install its tables

2. Define a job

3. Dispatch it

That is the whole loop: dispatch adds a row and fires one non-blocking request that starts a worker in a separate process. If that request cannot run on your host, the WP-Cron watchdog picks the work up within a minute instead.

How Processing Works

Every dispatch inserts a row and, once per request, fires a single non-blocking loopback request to admin-ajax.php that starts a worker. The worker drains jobs until the queue is empty or it reaches its time or memory budget, then it hands off to a fresh process so work spans many short requests safely.

A WP-Cron event runs on a schedule as an always-on safety net, so the queue still drains on hosts where loopback requests are blocked. For large backlogs, a long running WP-CLI worker is available. See How Processing Works for the details.

Full Documentation

• Getting Started
• Defining Jobs
• Dispatching Jobs
• How Processing Works
• Retries and Failures
• WP-CLI
• Configuration and Hooks

Development

The toolchain runs entirely in Docker, so no local PHP or Composer is required.

Using Docker Compose

Running the checks

License

MIT. See LICENSE.