wp-background-processing

Name: wp-background-processing
Author: mralaminahamed

25stars3forks

How to install wp-background-processing?

mralaminahamed/wp-dev-skills/wp-background-processing

$npx -y skills add mralaminahamed/wp-dev-skills --skill wp-background-processing

Installs into the current project.

Summary

Use when a WordPress plugin needs to run work outside the HTTP request cycle — scheduling async or recurring jobs with Action Scheduler (as_enqueue_async_action, as_schedule_single_action, as_schedule_recurring_action, as_unschedule_action), implementing WP_Background_Process (pu

Files · 1

View on GitHub

SKILL.md

1	# WordPress Background Processing
2
3	> 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`.
4
5	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).
6
7	## When to use
8
9	- "Process a large batch of items in the background", "queue a long-running task".
10	- "Set up Action Scheduler", "use WooCommerce queue".
11	- "Implement WP_Background_Process", "chunked batch import".
12	- "Background email sending", "async API calls".
13	- "Fix a WP Cron job not firing", "make scheduled tasks reliable".
14	- "The scheduled action completes but nothing happens", "the handler only runs in the admin".
15
16	Not for: One-off scheduled events (use `wp_schedule_single_event`). REST API async patterns — use `wp-rest-api`.
17
18	## Method
19
20	### 1. Choose the right tool
21
22	\| Tool \| Persistent \| Retry \| Progress \| Requires \| Best for \|
23	\|---\|---\|---\|---\|---\|---\|
24	\| Action Scheduler \| ✅ DB table \| ✅ Configurable \| Via hooks \| AS or WC \| Reliable multi-step queues \|
25	\| WP_Background_Process \| ✅ Options API \| ❌ Manual \| Via option \| ~5KB class \| Simple batches, no WC dep \|
26	\| WP Cron \| ❌ (transient) \| ❌ \| ❌ \| Nothing \| Maintenance, low-priority tasks \|
27
28	Rule of thumb: WooCommerce already installed → Action Scheduler. Simple background batch → `WP_Background_Process`. Periodic cleanup task → WP Cron.
29
30	### 2. Action Scheduler
31
32	Bundled with WooCommerce. Can also be installed as a standalone library.
33
34	Standalone install:
35	```bash
36	composer require woocommerce/action-scheduler
37	```
38	```php
39	require_once plugin_dir_path( __FILE__ ) . 'vendor/woocommerce/action-scheduler/action-scheduler.php';
40	```
41
42	Schedule and handle actions:
43	```php
44	// Schedule a single action (fires once ASAP)
45	as_enqueue_async_action( 'my_plugin_process_item', [ 'item_id' => 123 ], 'my-plugin' );
46
47	// Schedule a recurring action
48	as_schedule_recurring_action( time(), HOUR_IN_SECONDS, 'my_plugin_hourly_sync', [], 'my-plugin' );
49
50	// Schedule a single action in the future
51	as_schedule_single_action( time() + 300, 'my_plugin_delayed_job', [ 'batch' => 1 ], 'my-plugin' );
52
53	// Handle the action
54	add_action( 'my_plugin_process_item', function( $item_id ) {
55	$result = my_plugin_do_work( $item_id );
56	if ( is_wp_error( $result ) ) {
57	// AS will retry on exception; throw to trigger retry
58	throw new \Exception( $result->get_error_message() );
59	}
60	} );
61	```
62
63	Batch queue (fan-out pattern):
64	```php
65	function my_plugin_queue_all_items() {
66	$items = get_posts( [ 'post_type' => 'my_type', 'posts_per_page' => -1, 'fields' => 'ids' ] );
67	foreach ( $items as $id ) {
68	// Skip if already scheduled
69	if ( ! as_has_scheduled_action( 'my_plugin_process_item', [ 'item_id' => $id ], 'my-plugin' ) ) {
70	as_enqueue_async_action( 'my_plugin_process_item', [ 'item_id' => $id ], 'my-plugin' );
71	}
72	}
73	}
74	```
75
76	Cancel scheduled actions:
77	```php
78	as_unschedule_action( 'my_plugin_hourly_sync', [], 'my-plugin' );
79	as_unschedule_all_actions( 'my_plugin_process_item', [], 'my-plugin' );
80	```
81
82	Monitor via WP-CLI:
83	```bash
84	wp ac

People who liked this also viewed

6 picks

Type

wp-background-processing

25stars3forks

View on GitHub

How to install wp-background-processing?

mralaminahamed/wp-dev-skills/wp-background-processing

$npx -y skills add mralaminahamed/wp-dev-skills --skill wp-background-processing

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# WordPress Background Processing
2
3	> 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`.
4
5	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).
6
7	## When to use
8
9	- "Process a large batch of items in the background", "queue a long-running task".
10	- "Set up Action Scheduler", "use WooCommerce queue".
11	- "Implement WP_Background_Process", "chunked batch import".
12	- "Background email sending", "async API calls".
13	- "Fix a WP Cron job not firing", "make scheduled tasks reliable".
14	- "The scheduled action completes but nothing happens", "the handler only runs in the admin".
15
16	Not for: One-off scheduled events (use `wp_schedule_single_event`). REST API async patterns — use `wp-rest-api`.
17
18	## Method
19
20	### 1. Choose the right tool
21
22	\| Tool \| Persistent \| Retry \| Progress \| Requires \| Best for \|
23	\|---\|---\|---\|---\|---\|---\|
24	\| Action Scheduler \| ✅ DB table \| ✅ Configurable \| Via hooks \| AS or WC \| Reliable multi-step queues \|
25	\| WP_Background_Process \| ✅ Options API \| ❌ Manual \| Via option \| ~5KB class \| Simple batches, no WC dep \|
26	\| WP Cron \| ❌ (transient) \| ❌ \| ❌ \| Nothing \| Maintenance, low-priority tasks \|
27
28	Rule of thumb: WooCommerce already installed → Action Scheduler. Simple background batch → `WP_Background_Process`. Periodic cleanup task → WP Cron.
29
30	### 2. Action Scheduler
31
32	Bundled with WooCommerce. Can also be installed as a standalone library.
33
34	Standalone install:
35	```bash
36	composer require woocommerce/action-scheduler
37	```
38	```php
39	require_once plugin_dir_path( __FILE__ ) . 'vendor/woocommerce/action-scheduler/action-scheduler.php';
40	```
41
42	Schedule and handle actions:
43	```php
44	// Schedule a single action (fires once ASAP)
45	as_enqueue_async_action( 'my_plugin_process_item', [ 'item_id' => 123 ], 'my-plugin' );
46
47	// Schedule a recurring action
48	as_schedule_recurring_action( time(), HOUR_IN_SECONDS, 'my_plugin_hourly_sync', [], 'my-plugin' );
49
50	// Schedule a single action in the future
51	as_schedule_single_action( time() + 300, 'my_plugin_delayed_job', [ 'batch' => 1 ], 'my-plugin' );
52
53	// Handle the action
54	add_action( 'my_plugin_process_item', function( $item_id ) {
55	$result = my_plugin_do_work( $item_id );
56	if ( is_wp_error( $result ) ) {
57	// AS will retry on exception; throw to trigger retry
58	throw new \Exception( $result->get_error_message() );
59	}
60	} );
61	```
62
63	Batch queue (fan-out pattern):
64	```php
65	function my_plugin_queue_all_items() {
66	$items = get_posts( [ 'post_type' => 'my_type', 'posts_per_page' => -1, 'fields' => 'ids' ] );
67	foreach ( $items as $id ) {
68	// Skip if already scheduled
69	if ( ! as_has_scheduled_action( 'my_plugin_process_item', [ 'item_id' => $id ], 'my-plugin' ) ) {
70	as_enqueue_async_action( 'my_plugin_process_item', [ 'item_id' => $id ], 'my-plugin' );
71	}
72	}
73	}
74	```
75
76	Cancel scheduled actions:
77	```php
78	as_unschedule_action( 'my_plugin_hourly_sync', [], 'my-plugin' );
79	as_unschedule_all_actions( 'my_plugin_process_item', [], 'my-plugin' );
80	```
81
82	Monitor via WP-CLI:
83	```bash
84	wp ac

People who liked this also viewed

6 picks

Type