README

Durable, multi-step operations for Laravel — the operations engine behind long-running background work. Track a deploy, a provisioning run, or an import as a first-class record with a strict state machine, per-step progress, idempotent retries, and a stall sweep — instead of a black-box job.

use Cbox\Operations\Contracts\Operations;
use Cbox\Operations\DataObjects\{StartOperation, AdvanceStep, CompleteOperation};

$operations = app(Operations::class);

$op = $operations->start(new StartOperation(
    kind: 'deploy',
    targetType: 'workload',
    targetId: 'wl_123',
    steps: ['build', 'release', 'route'],
    expiresAt: now()->addMinutes(15),   // stalls after this → swept to failed
));

$operations->advanceStep(new AdvanceStep($op->id, 'build'));   // build done, release starts
$operations->advanceStep(new AdvanceStep($op->id, 'release'));
$operations->advanceStep(new AdvanceStep($op->id, 'route'));
$operations->complete(new CompleteOperation($op->id));

Every change dispatches an OperationUpdated event, so a client can watch progress live without polling. Re-running a step or a completion is a safe no-op (at-least-once workers never double-apply).

Why

Background work that spans several steps usually collapses to a single job with no visible progress and no way to tell "stuck" from "slow". Cbox Operations gives that work an auditable status (pending → running → completed | failed), per-step timing, and a deadline so a crashed worker self-heals into a terminal failed rather than a stuck running forever.

Install

composer require cboxdk/laravel-operations
php artisan migrate

Schedule the stall sweep so past-deadline operations self-heal:

Schedule::command('operations:sweep-stalled')->everyMinute();

Design

• Contracts-first. Depend on Cbox\Operations\Contracts\Operations, never the concrete manager — so you can decorate it and tests can swap the bundled fake.

• Deny-by-default state machine. Illegal transitions throw; terminal states never move.

• Tenancy-agnostic. tenant_id is an optional column the package simply persists — bring your own scoping.

• Broadcast-agnostic. OperationUpdated is a plain event; wire it to your own transport if you want live UI.

• Dogfooded testing. Ship InteractsWithOperations + FakeOperations and use them in your own suite:

  $ops = $this->fakeOperations();
  $this->deploy('wl_123');
  $ops->assertStarted('deploy');

Documentation

Full docs live in /docs: quickstart, architecture, the state machine, cookbook recipes, extension points, and the security/scope notes.

License

MIT © Cbox