Documentation

Most WebProCMS installs run background work inline — deferred closures after the response is sent, plus Lazy Cron for scheduled maintenance — because shared hosts rarely run a persistent queue:work process. But installs that do run a worker (a VPS with Supervisor, an owner-managed server) had no way to see it: is the worker alive, is the queue backing up, did anything fail? The Background Tasks screen (Dashboard → Develop → Background Tasks, admin and up) answers all three, and degrades gracefully on worker-less installs instead of alarming about a setup that's perfectly normal.

What the screen shows

The page live-refreshes every 10 seconds while open.

How worker detection works

There is no reliable "is a process running?" API on shared hosting (exec is usually disabled), so detection is heartbeat-based (QueueWorkerMonitor, registered in AppServiceProvider):

• queue:work's loop event fires every poll cycle — even when idle — and stamps a cache timestamp (throttled to one write per 30 s).
• Every real queued-job execution stamps it too, and records the job's class name.
• The sync connection is deliberately ignored: sync jobs run inline in the dispatching request, and jobs run via defer() never fire queue events — so neither can fake a live worker on an install that has none.

The heartbeat lives in the cache (database-backed by default), so a CLI worker and the FPM dashboard share state, including across servers with a shared cache backend.

The task runner (background_tasks)

BackgroundProgress says how far along a job is; it cannot make the job finish. The task runner is the durable half: one row per unit of long-running work, and a launcher that picks whichever process on this particular host is actually capable of running it.

It exists because the fleet has no queue worker, and because the three things that can run background work are each unavailable on some hosts. A backup, an AI image, a translate pass or a media migration must survive an FPM worker dying at max_execution_time — which is a FATAL, not an exception, so there is no cleanup block to rely on. The only thing that survives is what was written to the database before the process vanished.

The record

Every task is a row in background_tasks (App\Models\BackgroundTask):

The payload / state split is the load-bearing part: the arguments are always intact, and the cursor always describes work that has already been persisted — so re-running a killed step is safe.

Registered task types

Core types register in AppServiceProvider; a module's in its own service provider. php artisan tasks:demo registers a harmless demo type in its own process, for trying the runner by hand.

The driver ladder

TaskLauncher::start($type, $payload, $opts) inserts the row and then picks a runner, in order. Each rung is a fallback for the rung above being unavailable on this host:

1. worker — dispatches RunBackgroundTaskJob, but only on EVIDENCE: a fresh QueueWorkerMonitor heartbeat. Most installs run QUEUE_CONNECTION=database with nothing draining it, so dispatching on the mere presence of an async driver would strand the work forever.
2. detached — nohup php artisan tasks:run --id=N & via DetachedArtisan, outside the request entirely. The fleet's OpenLiteSpeed boxes allow proc_open; many cPanel/FPM hosts do not.
3. inline — one defer()red slice after the response ships, bounded to ~10 s by ExecutionDeadline. Whatever is left is picked up later.

Whichever rung wins, the row is the work. A rung that silently fails to deliver — a worker that dies before pickup, a spawn that gets reaped — just leaves an unclaimed live row, and something else picks it up:

• tasks:drain on its next Lazy Cron tick (every 60 s — but Lazy Cron only ticks on public page views).
• The browser. A page showing <livewire:background-task-progress :task-id="…" /> polls every 3 s, and each poll may run one ~5 s slice (driver = browser) of a task that is live, unclaimed or stale, and was last run in-request. It never steps a task a detached or worker process is holding.
• A page that nudges a deferred slice. When a step cannot fit inside a 3-second poll (see pumpable() below), the page that started the task calls defer(fn () => TaskRunner::runSlice($id)) from its own poll instead — off-request and unbounded, but only for a task that is live, not held by a live claim, and on an in-request driver. The task claim is what makes one nudge per poll safe. AI site generation, theme switching, demo seeding, campaign sends and the media migration all do this, because their pages are dashboard paths a Lazy Cron tick would never reach on a quiet site.

The progress component dispatches a background-task-finished browser event ({id, status, message, state}) on the terminal transition, so the page that started the task can show the result.

The contract a feature implements

A feature ports onto the runner by writing one class that implements TaskRunnable:

class BackupCreateTask implements TaskRunnable
{
    public static function type(): string { return 'backup-create'; }

    public function label(BackgroundTask $task): string { return __('Creating a backup'); }

    public function step(BackgroundTask $task, ?float $deadline): StepResult
    {
        $offset = (int) ($task->state['media_offset'] ?? 0);

        // …copy a bounded number of files, stopping on ExecutionDeadline::passed($deadline)…

        $task->progress([
            'state' => ['media_offset' => $offset + $copied],
            'done' => $offset + $copied,
            'total' => $totalFiles,
            'message' => __('Copying media'),
        ]);

        return $done ? StepResult::done() : StepResult::continue();
    }
}

Four rules make a runnable correct:

• A step owns its cursor. Read $task->state, do a bounded amount of work, write the cursor back with progress() BEFORE returning. progress() is one save and silently ignores runner-owned columns.
• A step must be safe to re-run after being killed at any point after any write. That is the whole design: the runner never rolls a step back, so anything already persisted must not be repeated.
• ExecutionDeadline::passed($deadline) is the in-step stop signal. A null deadline (CLI, detached) never passes, so the same body runs unbounded there.
• Register the type from a service provider — TaskTypes::register('backup-create', BackupCreateTask::class); core types in AppServiceProvider, a module's types in its own provider.

Five optional hooks, each detected with method_exists (they are deliberately not on the interface):

Inside a long step, call $task->heartbeat() at natural boundaries (per file, per chunk, per phase) to prove the runner is still alive. It is one conditional UPDATE on this runner's claim, throttled to one write every 5 s so a tight loop is fine, and it returns false once the task is no longer this step's to run (cancelled, or reclaimed) — a long step may stop early on it. It only works on the instance the runner handed to step(); a model loaded any other way has no claim to vouch for. staleAfterSeconds() covers a step that cannot heartbeat (one blocking call); heartbeat() covers one that can, and is the better answer where it is possible.

Four rules came out of porting the existing features, each from a real bug:

• A fixed idempotency key is fine. 'backup-create' for every backup, not one per click. The launcher releases a key held by a terminal row before inserting, so a finished or failed task never blocks the next start. The released row remembers the key ({key}#released-{id}), so a later Retry of it re-claims the key — or is refused while a newer run holds it — rather than coming back as a keyless twin.
• No process statics across a step or process boundary. A step can run in a different process from the one before it (a spawn, then a poll, then a drain), so a static memo set in one step is simply absent in the next. Keep cross-step state in state.
• Write terminal compatibility state AFTER the last helper call. A helper that marks its own work "running" will overwrite a done written before it.
• Never stamp a status Setting without restore-on-throw. A step that sets …_status = running and then throws leaves the Setting lying until someone notices; restore it in a finally/catch, or let the failed() hook correct it.

Anything metered (managed AI images) sends X-Idempotency-Key: task-{id}-{nonce}-{attempt}[-{shot}], so a re-run of the same attempt replays the broker's cached response instead of being billed again. The {nonce} is random per task and persisted in state before the first provider call (ImageRunContext::NONCE_STATE_KEY): the id alone collides, because every install numbers tasks from 1, a fleet's installs share one license key at the broker, and a backup Restore hands ids out again. The broker also scopes each stored response to the calling install's X-WebProCMS-Install host.

Starting one is then a single call, and the request the browser waits on does no provider work at all:

$task = TaskLauncher::start('backup-create', ['scope' => 'full'], [
    'user' => auth()->user(),
    'originUrl' => url()->current(),
    'idempotencyKey' => 'backup-create',   // a repeat start returns the LIVE task, not a twin
    'total' => $totalFiles,
]);

Running, draining, pruning

TaskRunner is the single entry point all of them use. It claims with one conditional UPDATE — never read-then-write, or two processes would both conclude the row was free — stamps a heartbeat before every step, and releases the claim on any ordinary exit, leaving status = running for the next driver to continue. A claim whose heartbeat stops for 120 seconds (or the type's own staleAfterSeconds() window) is assumed dead and may be taken by anything, which is what makes a killed process recoverable with no daemon involved. Every write after the claim — the between-steps heartbeat, done, failed, a backoff, a release — is conditional on the row still being this runner's and still running, so a Cancel that lands while a step runs is final, and a runner whose row was reclaimed never clears the new owner's claim.

TaskRunner::pump($id) is the browser-polling entry point: it runs one very short slice when a task is live and genuinely unattended, and always returns {status, done, total, percent, message, last_error, stale}. It deliberately never fights a detached or worker claim — those processes are already making progress, and a poll that also stepped them would double-run work whose only protection is the claim it would be ignoring.

Self-reported progress (BackgroundProgress)

Queue tables only know pending/reserved/failed — a "63% done" bar requires the work to report its own progress. BackgroundProgress is the one-line-per-milestone registry for that:

BackgroundProgress::start('media-cloud-migration', 'Migrating media to cloud', total: $count);
BackgroundProgress::increment('media-cloud-migration');   // per item
BackgroundProgress::complete('media-cloud-migration');    // or ::fail($key, $error)

Entries live in cache and age out on their own (6 h after the last update), so a crashed job's bar disappears instead of sticking forever. Any job, deferred closure, or artisan command can adopt it incrementally.

It is deliberately advisory-only: last-write-wins, no locking, and nothing about it can resume a job that died. New long-running work should use the task runner above — BackgroundProgress remains for lightweight reporting from work that is already guaranteed to complete in one pass.

Setup

Nothing to configure. Installs without a worker see an informational note (that's the supported default — Lazy Cron and deferred execution handle background work). To run a real worker, start php artisan queue:work under a process monitor such as Supervisor and set QUEUE_CONNECTION=database (or redis) in .env; the screen will show it as Active within seconds of its first poll.

What the heartbeat unlocks

Worker detection isn't just informational — it gates real dispatch decisions:

• Lazy Cron queue offload (opt-in, Settings → Advanced → Lazy Cron): due scheduled tasks are handed to the worker instead of running inline, with automatic rescheduling if a dispatch is lost. See Lazy Cron → Queue worker offload.
• The task runner's top rung (TaskLauncher): a fresh heartbeat is what makes RunBackgroundTaskJob the chosen driver rather than a detached spawn or an inline slice. No heartbeat, no dispatch — the ladder steps down instead of stranding the row.

Limitations

• Per-queue row listing covers the database driver; other drivers get aggregate counts for their default queue only.
• The legacy progress list only shows work that calls BackgroundProgress; everything that runs as a task shows in the Tasks table instead.
• Lazy Cron only ticks on public page views, so on a quiet site with no worker and no proc_open a task whose steps are not pumpable advances only while its page is open (the nudge) or when a visitor arrives.
• Scheduled maintenance tasks are intentionally not duplicated here — they live on the Lazy Cron panel (Dashboard → Settings → Advanced), which the screen links to.