Cbox Operations

Track long-running background work — deploys, provisioning, imports — as a first-class operation record: a strict state machine, ordered steps with their own status and timing, idempotent retries, live progress events, and a deadline so stalled work self-heals.

Mental model

An operation moves through pending → running → completed | failed and never leaves a terminal state. It owns an ordered list of steps; advancing one step completes it and promotes the next. Every real change dispatches OperationUpdated, so a client can watch progress without polling. A running operation past its expires_at is swept to failed.

You interact with exactly one thing — the Operations contract:

$operations->start(...);        // open (running), first step running
$operations->advanceStep(...);  // complete a step, start the next
$operations->complete(...);     // finish
$operations->fail(...);         // record a failure
$operations->sweepStalled();    // fail past-deadline operations

Sections

• Getting started — install, migrate, test.
• Core concepts — architecture, the state machine, events.
• Cookbook — task-oriented recipes.
• Extension points — swap the model, decorate the contract.
• Configuration — every config key.
• Security — scope and honest limitations.