wp-background-processing

WordPress Background Processing

Model note: Scaffolding a new Action Scheduler or WP_Background_Process implementation is pattern-matching — haiku handles it well. Debugging a stuck queue or race condition across async jobs requires reasoning; use sonnet.

Implement background jobs and queued tasks in WordPress plugins. Three primary tools with distinct trade-offs: Action Scheduler (persistent, battle-tested), WP_Background_Process (lightweight, no DB table), WP Cron (built-in, unreliable timing).

When to use

• "Process a large batch of items in the background", "queue a long-running task".
• "Set up Action Scheduler", "use WooCommerce queue".
• "Implement WP_Background_Process", "chunked batch import".
• "Background email sending", "async API calls".
• "Fix a WP Cron job not firing", "make scheduled tasks reliable".
• "The scheduled action completes but nothing happens", "the handler only runs in the admin".

Not for: One-off scheduled events (use wp_schedule_single_event). REST API async patterns — use wp-rest-api.

Method

1. Choose the right tool

Tool	Persistent	Retry	Progress	Requires	Best for
Action Scheduler	✅ DB table	✅ Configurable	Via hooks	AS or WC	Reliable multi-step queues
WP_Background_Process	✅ Options API	❌ Manual	Via option	~5KB class	Simple batches, no WC dep
WP Cron	❌ (transient)	❌	❌	Nothing	Maintenance, low-priority tasks

Rule of thumb: WooCommerce already installed → Action Scheduler. Simple background batch → WP_Background_Process. Periodic cleanup task → WP Cron.

2. Action Scheduler

Bundled with WooCommerce. Can also be installed as a standalone library.

Standalone install:

composer require woocommerce/action-scheduler

require_once plugin_dir_path( __FILE__ ) . 'vendor/woocommerce/action-scheduler/action-scheduler.php';

Schedule and handle actions:

// Schedule a single action (fires once ASAP)
as_enqueue_async_action( 'my_plugin_process_item', [ 'item_id' => 123 ], 'my-plugin' );

// Schedule a recurring action
as_schedule_recurring_action( time(), HOUR_IN_SECONDS, 'my_plugin_hourly_sync', [], 'my-plugin' );

// Schedule a single action in the future
as_schedule_single_action( time() + 300, 'my_plugin_delayed_job', [ 'batch' => 1 ], 'my-plugin' );

// Handle the action
add_action( 'my_plugin_process_item', function( $item_id ) {
    $result = my_plugin_do_work( $item_id );
    if ( is_wp_error( $result ) ) {
        // AS will retry on exception; throw to trigger retry
        throw new \Exception( $result->get_error_message() );
    }
} );