acorn-background
Use when work must run outside the request, on a schedule, or be logged in an Acorn project - WP-Cron vs Action Scheduler vs Laravel queues (make:job, ShouldQueue, queue:work, failed_jobs), console co
SKILL.mdskills/acorn-background/SKILL.md
GitHubBackground work, cache and logs under Acorn
Acorn brings Laravel's queue, cache, Redis, console, scheduler and log components into WordPress. WordPress already has its own scheduler (WP-Cron), object cache and debug log. Pick the native piece first and add the Laravel piece only for a real gap.
Runner placeholders ({{runner.wp}}, {{runner.acorn}}, {{runner.composer}}, {{runner.test}}, {{runner.cache}}) come from the session context; on Lando they default to lando wp, lando wp acorn, lando composer, the project's test tooling and its cache-clear tooling. Redis tooling and service names come from .lando.yml (read them, do not assume cache or redis).
When to use
- Something slow or unreliable runs inside a request (external API call, email, image work, CRM sync).
- A recurring task (nightly cleanup, hourly sync), or a CLI command for maintenance and imports.
- Configuring Redis or the Laravel cache, or untangling it from the WordPress object cache.
- Adding a log channel, finding where logs go, or shipping logs from containers.
Inputs required
- Active profile, Acorn base path and namespace (session context).
- Installed pieces:
illuminate/redisand the PHPredisextension (orpredis/predis), Action Scheduler (a plugin orwoocommerce/action-scheduler), the WordPress Redis drop-in (wp-content/object-cache.php). - Config actually in effect:
config/queue.php,config/cache.php,config/database.php(redis),config/logging.phpin the base path, merged over Acorn's defaults. - Hosting: can the project run a long-lived worker (container, supervisor, systemd)? Is there a system cron? How many web instances?
Decide the mechanism
| Need | Native first | Laravel piece when |
|---|---|---|
| Run a hook at an interval, low volume, retry not critical | WP-Cron: wp_schedule_event() (wp-includes/cron.php), triggered by traffic unless DISABLE_WP_CRON is set and a system cron calls {{runner.wp}} cron event run --due-now |
— |
| Many deferred actions with per-action logs and admin UI, no worker process | Action Scheduler (as_enqueue_async_action, as_schedule_single_action, as_schedule_recurring_action; runs on WP-Cron) when it is already installed |
— |
| Retries with backoff, timeouts, unique jobs, batches, chaining, high volume | — | Laravel queue + worker (queue:work) |
| Recurring Laravel commands with overlap control | WP-Cron calling a service | Scheduler (schedule:run every minute from system cron) |
| Cache a computed value | Transients / wp_cache_* (persistent when an object-cache drop-in is installed) |
Laravel Cache for tags, locks, remember, or a store separate from WordPress |
| Operator command | WP_CLI::add_command() |
Acorn command for DI, Laravel console IO, scheduling |
| Debug output | WP_DEBUG_LOG → debug.log |
Laravel Log channels, structured context, stderr in containers |
Details and trade-offs: references/decision-matrix.md.
Profile differences
| Item | sage-theme |
acorn-mu-plugin |
radicle-app |
|---|---|---|---|
| Jobs, commands | app/Jobs, app/Console/Commands in the theme |
same folders in the plugin, plugin namespace | same folders at the root |
routes/console.php |
theme base path | plugin base path | project root |
| Config overrides | config/*.php in the theme |
config/*.php in the plugin |
config/*.php at the root |
| Storage (logs, file cache) | storage/ in the theme if present, else wp-content/cache/acorn |
storage/ in the plugin if present, else the same fallback |
storage/ at the root |
| Worker command runs from | the site root through WP-CLI, theme active | the site root through WP-CLI (mu-plugins always load) | the project root through WP-CLI |
Procedure
Commands: write every command with the runner value from the session context filled in (for example lando wp acorn optimize:clear), never a bare wp/composer/php/npm, never the placeholder, never "prefix with lando if you use it". Commands that run in CI or a deploy script go in a separate block labelled with where they run.
- Name the need and pick the mechanism with the table. Write the reason when you choose a Laravel piece over a native one.
- Laravel queue (references/queues.md):
QUEUE_CONNECTIONdefaults tosync(runs inline, nothing is deferred). Choosedatabaseorredisper environment.- Database driver:
{{runner.acorn}} make:queue-table,make:queue-failed-table(andmake:queue-batches-tablefor batches), then{{runner.acorn}} migrate. Tables get the WordPress prefix. {{runner.acorn}} make:job SyncLead; pass IDs, not objects; set$tries,$backoff,$timeout; makehandle()idempotent; callwp_set_current_user()when capability checks run inside the job.- Dispatch from the WordPress hook or controller:
SyncLead::dispatch($leadId). - Run a worker:
{{runner.acorn}} queue:work --tries=3 --max-time=3600. In production keep it alive with the platform's process manager and run{{runner.acorn}} queue:restartafter every deploy.
- Commands and schedule (references/commands-scheduling.md):
{{runner.acorn}} make:command ImportLeads→app/Console/Commands, loaded automatically; run as{{runner.acorn}} leads:import.- Schedule in
routes/console.php(Schedule::command('leads:import')->hourly()->withoutOverlapping()) or with->withSchedule(fn (Schedule $s) => …)on the builder. - Trigger it every minute from a system cron:
{{runner.acorn}} schedule:run(on a server without the local runner, the same command through that environment's WP-CLI, from the WordPress root), or keep{{runner.acorn}} schedule:workrunning.
- Redis and cache (references/redis-cache.md):
{{runner.composer}} require illuminate/redisin the base path (Acorn does not require it; its provider is skipped while the class is missing) plus theredisPHP extension orpredis/predis.- Give Laravel its own Redis databases or key prefix. The Redis Object Cache drop-in defaults to database 0 and
{{runner.wp}} cache flushrunsFLUSHDBon it; Acorn's Redisdefaultconnection is also database 0 (REDIS_DB), cache database 1 (REDIS_CACHE_DB). Put queues and sessions elsewhere, for exampleREDIS_DB=2,REDIS_CACHE_DB=3. {{runner.acorn}} cache:clearempties the Laravel cache store only;{{runner.wp}} cache flushempties the WordPress object cache only.
- Logging (references/logging.md):
- Default: channel
stack→single→storage/logs/laravel.logunder the app's storage path. - Containers:
LOG_CHANNEL=stderr(or addstderrtoLOG_STACK) so the platform collects logs. - A project
config/logging.phponly needs the channels it adds; Laravel mergeschannelswith Acorn's defaults. - Always log with a context array, never secrets or full personal data.
- Default: channel
- Clear caches after PHP changes:
{{runner.cache}}.
Verification
- Queue: dispatch one job, then
{{runner.acorn}} queue:work --onceprocesses it;{{runner.acorn}} queue:failedis empty; with the database driver, thejobstable drains. - Schedule:
{{runner.acorn}} schedule:listshows each task with its next run;{{runner.acorn}} schedule:testruns one on demand. - Commands:
{{runner.acorn}} listshows the command;{{runner.acorn}} help <name>matches the signature. - Redis:
{{runner.wp}} eval 'var_dump(app("redis")->connection()->ping());'succeeds;{{runner.wp}} eval 'var_dump(config("database.redis.default.database"), config("database.redis.cache.database"));'shows databases that differ from the object cache's. - Logs:
{{runner.wp}} eval 'logger("kivo-check", ["ok" => true]);'writes to the expected file or stream. - WP-Cron:
{{runner.wp}} cron event listshows the hook and next run.
Failure modes
| Symptom | Cause | Fix |
|---|---|---|
| Jobs "dispatch" but run during the request | QUEUE_CONNECTION is sync (default) |
Set database or redis and run a worker |
| Jobs pile up, never processed | No worker running, or the worker listens to another queue/connection | Start queue:work with matching --queue; supervise it |
| Worker runs old code after a deploy | Long-running process keeps the old classes | {{runner.acorn}} queue:restart (needs a cache store shared by worker and deploy) |
| Jobs behave as logged out or use stale WordPress state | Workers run in one long WP-CLI process; no request user, globals persist between jobs | wp_set_current_user() in handle(); avoid globals; --max-jobs / --max-time |
Class "Redis" not found / redis binding missing |
No redis extension, or illuminate/redis not installed so its provider was skipped |
Install the extension or predis/predis (REDIS_CLIENT=predis); require illuminate/redis |
| Sessions, locks or queued jobs vanish after a deploy | {{runner.wp}} cache flush ran FLUSHDB on the database Laravel also uses |
Separate databases (REDIS_DB, REDIS_CACHE_DB) or WP_REDIS_SELECTIVE_FLUSH with a prefix |
| Scheduled tasks never run | No system cron calling schedule:run, or it runs outside the site root |
Add the cron entry; run through WP-CLI from the WordPress root |
onOneServer() / withoutOverlapping() still overlap across servers |
Cache store is per server (file) | Use Redis or database as the cache and lock store |
| WP-Cron events late or never | Low traffic, or DISABLE_WP_CRON without a system cron |
System cron with {{runner.wp}} cron event run --due-now |
| No log file appears | Storage folder missing or not writable, or LOG_CHANNEL points to a stream |
Check the storage path per profile; stderr output is in the container log |
Command missing from list |
Not under app/Console/Commands of the base path, or namespace mismatch with composer.json PSR-4 |
Move it, fix the namespace, or register with ->withCommands([...]) |
Escalation
- Adding a worker process, a cron entry, or Redis to an environment is infrastructure work: describe what is needed and ask.
- Purging queues (
queue:clear,queue:flush), flushing shared caches, or changing Redis databases on a shared environment: ask first. - Tables behind jobs or schedules:
acorn-data. HTTP entry points that dispatch jobs:acorn-routes-api.