Background Jobs

Long-running operations — XLIFF data imports and exports, bulk machine translation, WPML / Polylang / TranslatePress migrations, full-site string scans, large glossary CSV imports — can take minutes on a real site. PerfLocale's background-jobs layer moves them off the request path so the admin UI stays responsive and PHP-FPM timeouts on shared hosting never decide whether your import succeeds.

Dedicated state table. Job state lives in a single custom table ({$wpdb->prefix}perflocale_jobs) with typed columns and indexes on uuid, (status, updated_at), (type, status), and created_by. The table is garbage-collected daily and contributes no overhead on frontend requests — visitors never touch it. The table replaces an earlier options-based design; concurrency locks still live in wp_options via atomic INSERT IGNORE (race-free row-level mutex), which is the right shape for short-lived advisory locks.

How it works

Nine user-triggered operations + one cron-driven sweep (AI quality scoring) are wrapped as "tier-2" jobs in v1.0 (the table below enumerates them). When you trigger one:

1. Dispatch — the plugin chooses sync (inline) or async based on settings + payload size. Small inputs still run inline so you see the result immediately; big ones queue and the admin redirects to the Jobs page.
2. Engine — async jobs run on Action Scheduler when WooCommerce or the standalone AS plugin is loaded, or WP-Cron otherwise. The choice is automatic; an operator can force WP-Cron from the settings page (escape hatch when AS misbehaves).
3. Worker — the worker re-checks the dispatching user's capability against the cap stored on the job row (defense-in-depth against role downgrades between dispatch and execution), takes an atomic lock so a job can't run twice, and calls the operation's execute().
4. Retry — unhandled exceptions are caught; the worker reschedules with exponential backoff up to 5 attempts (configurable).

Each job is one row in {$wpdb->prefix}perflocale_jobs with typed columns: uuid (CHAR(36), UNIQUE), type, hook, engine (action_scheduler / wp_cron), status, progress, total, processed, attempts, created_by (indexed, used for cap re-validation), blog_id, version (optimistic-concurrency CAS column), and the timestamps. Larger payloads — args, result (truncated to 64 KB), error, and a log ring buffer (20 entries) — live in LONGTEXT columns on the same row. Status and stuck-job sweeps use the (status, updated_at) index; admin filters use (type, status).

Two short-lived advisory lock options remain in wp_options: perflocale_job_lock_<uuid> (per-job worker mutex) and perflocale_type_lock_<type> (per-type concurrency cap). They use atomic INSERT IGNORE on the UNIQUE option_name key so the DB enforces mutual exclusion at the row-lock layer. Stored expiry timestamps let a daily sweep clean up dead locks left behind by crashed workers.

All of the above is per-blog on multisite — each subsite has its own jobs table view (the table itself is shared via $wpdb->prefix, but every query filters on the current blog), settings, and Jobs page.

Job types

Ten operations are background-capable in v1.0:

What's not on the unified Jobs queue

Some operations have their own scheduler and are not visible on PerfLocale → Jobs. They've been stable in production for prior releases and the cost of moving them onto the unified queue exceeded the operational benefit for v1.0:

• Exchange-rate sync (WooCommerce) — runs on a separate daily perflocale_exchange_rate_sync WP-Cron event.
• Webhook delivery + retry — per-delivery one-shot events routed through BackgroundEvents, not Dispatcher.
• Concurrency-lock cleanup — daily cron for the standalone Lock subsystem.

All three schedule their own events via the same engine selector (Action Scheduler when loaded, WP-Cron otherwise), so the engine setting affects them too — they just aren't tracked on the JobState index.

Settings (Performance tab)

Background Processing

• Auto (default) — small operations run inline; large ones queue. The threshold is per-job, with sensible defaults (e.g. 100 files for string scan, 1000 rows for glossary import).
• Always — every operation queues. Use on large sites where even "small" operations can spike during peak hours.
• Never — everything runs inline. Not recommended on a real site — long imports will hit PHP-FPM timeouts.

Background Engine (only shown when Action Scheduler is loaded)

• Auto — use Action Scheduler when available (recommended). AS has its own admin UI under Tools → Scheduled Actions filtered to the perflocale group, persists actions in its own tables, and handles concurrency / claim semantics natively.
• Force WP-Cron — skip AS and use WordPress's built-in cron. Escape hatch for sites where AS is misbehaving (rare).

Background Thresholds

Per-job override of the default item-count threshold for Auto mode. Leave blank to use the default. Programmatic equivalent: perflocale/jobs/threshold/<type> filter.

Pause Queue

Operator brake. New dispatches are accepted but workers immediately re-queue them every 5 minutes instead of running. Use as an emergency stop when something is mis-dispatching; uncheck to resume. Already-in-flight jobs finish naturally; only future ticks defer.

Recovery and garbage collection

Three automatic recovery paths run on the daily perflocale_jobs_gc cron:

1. Stuck-job sweep. Any job in queued or running whose updated_at hasn't moved in 6 hours (configurable) is marked failed with a clear message. Catches PHP-FPM kills, OOM crashes, host reboots, or broken cron environments where dispatched events never fire.
2. Terminal-state prune. Jobs in complete, failed, or canceled older than 24 hours are removed from both the index and their per-job option.
3. Stale lock sweep. Per-job and per-type lock rows (perflocale_job_lock_* and perflocale_type_lock_*) whose stored expiry timestamp is in the past are deleted. Without this, every dispatched job would leave a dead lock row behind forever.

One additional recovery path runs on plugin activation (not on the daily cron):

• Reactivation resume. The deactivation hook unschedules every worker event so a deactivated plugin doesn't leave cron firing against missing callbacks. The JobState rows survive deactivation, though — the operator's history shouldn't vanish. On the next activate, a one-shot perflocale_resume_jobs event runs the Resumer handler: it scans the index, re-enqueues each queued/running survivor via the configured runner, flips any running rows back to queued (without bumping attempts — the previous run didn't fail on its own merits), and logs "Resumed after plugin reactivation." on each job.

WP-CLI

Full subcommand surface mirroring the REST endpoints. See WP-CLI → Jobs for the complete reference. Quick examples:

# List all active jobs (queued or running)
wp perflocale jobs list

# Filter by status
wp perflocale jobs list --status=failed --format=json

# Inspect, cancel, retry, delete
wp perflocale jobs get    <uuid>
wp perflocale jobs cancel <uuid>
wp perflocale jobs retry  <uuid>
wp perflocale jobs delete <uuid>

# Operator brake
wp perflocale jobs pause
wp perflocale jobs unpause

# Manual maintenance
wp perflocale jobs gc        # Run garbage collection now
wp perflocale jobs resume    # Re-enqueue queued/running jobs (post-reactivation recovery)

REST API

Five endpoints under /wp-json/perflocale/v1/jobs/. See REST API → Jobs for the complete reference with response shapes.

Permissions

The bg-jobs layer integrates with PerfLocale's standard capability system. Two angles:

Who can dispatch a job

Each job type declares the cap it requires (via get_required_capability()). The Dispatcher checks current_user_can() against that cap before doing anything. The worker re-checks the cap at execution time against the originating user — if a user's role was downgraded between dispatch and run, the job fails with "Permission revoked or dispatching user no longer has access."

The mapping is in the job types table above.

Who can cancel / retry / delete a job

The REST and CLI mutation endpoints (cancel, retry, delete) require BOTH:

• perflocale_translate — coarse "you can touch the jobs API at all" gate.
• You must either be the user who originally dispatched the job, OR hold the perflocale_manage_translations supervisor cap.

This prevents a translator who can dispatch their own string-scan from cancelling another translator's in-flight migration. Supervisors and administrators (who naturally have perflocale_manage_translations) can manage any job.

See the Permissions & Roles doc for the full cap matrix.

Hooks

perflocale/jobs/threshold/<type> (filter)

Per-type override of the Auto-mode threshold. The default for each job comes from get_default_threshold() on the job class (e.g. 100 for string_scan, 1000 for data_import / glossary_import, 500 for wpml_migration / polylang_migration, 200 for translatepress_migration, 5000 for data_export, 25 for bulk_translate — counted as source posts × target languages).

// Force string scans to ALWAYS run async, regardless of file count.
add_filter( 'perflocale/jobs/threshold/string_scan', static fn(): int => 0 );

// Per-args dynamic threshold for the data importer: bigger files
// queue, small ones stay inline.
add_filter( 'perflocale/jobs/threshold/data_import', static function ( int $base, array $args ): int {
	$file = $args['file_path'] ?? '';
	return file_exists( $file ) && filesize( $file ) > 5 * MB_IN_BYTES ? 0 : 999999;
}, 10, 2 );

Args: int $base (resolved from settings or default), array $args (the dispatch args).
Returns: int. When 0, every dispatch goes async. When PHP_INT_MAX, every dispatch goes sync.

perflocale/jobs/max_attempts (filter)

Maximum retry count before a failed job stops being rescheduled. Default 5 (initial attempt + 4 retries).

// One-shot only — never retry.
add_filter( 'perflocale/jobs/max_attempts', static fn(): int => 1 );

Args: int $max.
Returns: int.

perflocale/jobs/retry_delay (filter)

Seconds to wait before the next retry attempt. Default: exponential backoff capped at 1 hour — min( 3600, 60 * 2^(attempts-1) ).

// Linear backoff: 60, 120, 180, ...
add_filter( 'perflocale/jobs/retry_delay', static function ( int $delay, int $attempts ): int {
	return 60 * max( 1, $attempts );
}, 10, 2 );

Args: int $delay (default), int $attempts (current attempt count).
Returns: int (seconds).

perflocale/jobs/max_concurrent/<type> (filter)

Per-type concurrency cap. Default 1 — only one worker of each type runs at a time. Set to a higher number or PHP_INT_MAX to allow parallel workers (e.g. multiple string scans for different directories at once).

// Allow up to 4 parallel string scans.
add_filter( 'perflocale/jobs/max_concurrent/string_scan', static fn(): int => 4 );

// Disable the cap for data_export (effectively unlimited concurrency).
add_filter( 'perflocale/jobs/max_concurrent/data_export', static fn(): int => PHP_INT_MAX );

Args: int $max (default 1).
Returns: int. Values ≤ 1 enable the cap; > 1 disables it.

perflocale/jobs/max_args_bytes (filter)

Maximum JSON-encoded size of the args payload accepted by Dispatcher::enqueue(). Default 100 KB. Caller-side hardening against bloating the args LONGTEXT column.

// Bump to 500 KB for custom jobs that legitimately carry larger payloads.
add_filter( 'perflocale/jobs/max_args_bytes', static fn(): int => 500 * 1024 );

Args: int $bytes.
Returns: int. Clamped to a minimum of 1024 bytes.

perflocale/jobs/active_index_max (filter)

Cap on how many rows appear on PerfLocale → Jobs at once. Default 50. The cap drives a LIMIT on the listing query plus a daily-GC eviction pass: oldest terminal rows (complete/failed/canceled) are evicted first; queued and running rows are never evicted. Each row is ~1 KB on disk (mostly the LONGTEXT log + result columns) so even a cap of 250 stays well under typical InnoDB row-overhead noise.

// High-throughput site that dispatches hundreds of jobs/day.
add_filter( 'perflocale/jobs/active_index_max', static fn(): int => 250 );

Args: int $max.
Returns: int (floor-clamped to 10).

Per-job throughput filters

The unified dispatch decision (sync vs async, retry count, threshold) is the same for every job, but each job has its own internal batch size that controls throughput once it's running. These are independent of the bg-jobs threshold filters and live with the job's underlying class. All clamped to safe ranges so a filter typo can't break the operation.

perflocale/jobs/stuck_timeout_seconds (filter)

How long a job may sit in queued or running without its updated_at being bumped before the daily GC declares it stuck and marks it failed. Default 6 hours.

// More aggressive sweep — 1 hour.
add_filter( 'perflocale/jobs/stuck_timeout_seconds', static fn(): int => HOUR_IN_SECONDS );

Args: int $seconds.
Returns: int.

perflocale/jobs/pause_recheck_seconds (filter)

When the queue is paused, a worker that picks up a job immediately re-schedules it for this many seconds later instead of running. Default 300 (5 minutes). Lower values poll the pause flag more often at the cost of more cron / AS churn.

add_filter( 'perflocale/jobs/pause_recheck_seconds', static fn(): int => 60 );

Args: int $seconds.
Returns: int.

perflocale/jobs/type_busy_retry_seconds (filter)

When the per-type concurrency lock is held by another worker, the new attempt re-queues this many seconds later. Default 60.

add_filter( 'perflocale/jobs/type_busy_retry_seconds', static fn(): int => 10 );

Args: int $seconds.
Returns: int.

perflocale/jobs/runner (filter)

Globally override the runner instance. Mostly for tests and custom deployments backed by an external queue (Sidekiq, SQS, etc.). Returning a JobRunnerInterface instance from this filter bypasses the engine setting and Action Scheduler detection.

add_filter( 'perflocale/jobs/runner', static function ( $default ) {
	return new MyCustomQueueRunner();
}, 99 );

Args: JobRunnerInterface|null $override.
Returns: JobRunnerInterface|null.

perflocale/glossary/max_csv_bytes (filter)

Maximum size of a glossary CSV upload accepted by the admin importer. Default 100 MB. Operators with bigger glossaries can bump this filter; values too low risk legitimate imports being rejected.

add_filter( 'perflocale/glossary/max_csv_bytes', static fn(): int => 500 * MB_IN_BYTES );

Args: int $bytes.
Returns: int.

perflocale/jobs/enqueued (action)

Fires after a job has been successfully enqueued for async execution. Useful for hooking external monitoring / observability.

add_action( 'perflocale/jobs/enqueued', static function ( string $job_id, string $type, string $engine, array $args ): void {
	error_log( "PerfLocale enqueued $type job $job_id on $engine" );
}, 10, 4 );

Args:

• string $job_id — UUID v4 of the new job.
• string $type — job type slug (e.g. string_scan).
• string $engine — runner engine: action_scheduler or wp_cron.
• array $args — the dispatch args.

perflocale/jobs/completed (action)

Fires after a worker finishes a job successfully.

add_action( 'perflocale/jobs/completed', static function ( string $job_id, string $type, array $result ): void {
	// Push to your metrics pipeline...
}, 10, 3 );

Args: string $job_id, string $type, array $result (worker's return value, already stored on the job row, truncated to MAX_RESULT_BYTES = 64 KB).

perflocale/jobs/failed (action)

Fires when a worker throws an exception and the retry-with-backoff is about to be scheduled (or skipped because the attempt cap has been hit).

add_action( 'perflocale/jobs/failed', static function ( string $job_id, string $type, \Throwable $e ): void {
	// Send to Sentry / Bugsnag / etc.
	sentry_capture_exception( $e, [
		'tags' => [ 'perflocale_job_id' => $job_id, 'perflocale_job_type' => $type ],
	] );
}, 10, 3 );

Args: string $job_id, string $type, \Throwable $e (the original exception, untruncated — useful for monitoring; the version stored on the job row is path-redacted and truncated).

perflocale/jobs/canceled (action)

Fires when a long-running worker cooperatively aborts itself in response to an operator cancel mid-flight (distinct from failed because it isn't an error). Useful for distinguishing operator-canceled from worker-errored in monitoring dashboards.

add_action( 'perflocale/jobs/canceled', static function ( string $job_id, string $type ): void {
	// Record cancellation without alerting...
}, 10, 2 );

Args: string $job_id, string $type.

perflocale/strings/after_scan (action)

Fires after the all-mode string scan finishes iterating every theme + plugin directory. Addons hook here to register their non-gettext strings (e.g. attribute labels, email subjects).

add_action( 'perflocale/strings/after_scan', static function (): void {
	// Register any strings your code generates dynamically...
} );

Multisite

The bg-jobs system is fully per-blog. On both subdir and subdomain installs, each subsite:

• Filters every {$wpdb->prefix}perflocale_jobs query through the current blog_id (stored as a column on every row), so the Jobs page and the GC sweep see only that subsite's rows.
• Sees and manages only its own queue via the Jobs admin page and CLI (wp perflocale jobs list --url=<blog>).
• Has its own settings (processing mode, engine, thresholds, paused flag) stored as per-subsite options.
• Runs its own GC + Resumer (per-blog daily cron + per-blog activation handler).

Network activation iterates all sites in chunks of 100 (filterable via perflocale/activation/chunk_size) and runs Activator::activate() per blog. The wp_initialize_site hook auto-creates table state on new subsites added to the network. The wp_uninitialize_site hook runs the same per-blog cleanup as uninstall.php when a subsite is permanently deleted.

Performance

The dedicated jobs table is touched only by the admin Jobs page, the daily GC + stuck-job watchdog crons, and the worker code paths. No code path on a public pageview ever queries it. Loading the homepage, a single post, or a category archive runs zero queries against perflocale_jobs regardless of how many jobs are queued.

The two short-lived lock options (perflocale_job_lock_* and perflocale_type_lock_*) live in wp_options with autoload=no, so even on the small subset of admin requests that exercise the locking path, the rows are not pulled into the alloptions blob.

Row size on the jobs table is dominated by the args, result, and log LONGTEXT columns; the typed scalar columns (status, attempts, timestamps, indexes) are ~150 bytes. A typical 50-row backlog occupies well under 1 MB on disk.

Action Scheduler integration

When Action Scheduler ≥ 3.4 is loaded (WooCommerce ships it; the standalone Action Scheduler plugin works too), PerfLocale enqueues async jobs via as_enqueue_async_action() / as_schedule_single_action() in the perflocale group. The Jobs admin page shows a link to Tools → Scheduled Actions (filtered to that group) so you can use the full AS history UI alongside the PerfLocale-native view.

On sites without AS, the runner falls back to wp_schedule_single_event(). Same code path, same retry semantics, same UI; just a different scheduler.

See also

• WP-CLI: wp perflocale jobs reference
• REST API: Jobs endpoints
• Hooks reference: Background Jobs section
• Permissions & Roles
• Features: Performance → Background Processing