Installation

composer require roundly-consulting/workflows-for-laravel roundly-consulting/approvals-for-laravel
php artisan workflows:install                              # publishes config/workflows.php and the eight migrations
php artisan vendor:publish --tag="approvals-migrations"    # approvals powers the approval step in the example below
php artisan migrate

# Before php artisan migrate — bigint, uuid or ulid
WORKFLOWS_KEY_TYPE=bigint           # user morphs: started_by, published_by, requested_by
WORKFLOWS_OWNER_KEY_TYPE=           # owner morphs; blank = WORKFLOWS_KEY_TYPE
WORKFLOWS_SUBJECT_KEY_TYPE=         # subject morphs; blank = WORKFLOWS_KEY_TYPE
WORKFLOWS_PRIMARY_KEY_TYPE=bigint   # the package's own ids

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('workflows:wake')->everyMinute()->withoutOverlapping(10)->onOneServer();
Schedule::command('workflows:prune')->daily();

# A step job may run for up to 570 s (engine.lease − 30 s): retry_after must be longer.
DB_QUEUE_RETRY_AFTER=600        # Laravel's default database queue (90 s otherwise)
REDIS_QUEUE_RETRY_AFTER=600     # the redis queue
php artisan workflows:doctor    # fails on a too-short retry_after

// AppServiceProvider::boot()
use RoundlyConsulting\Workflows\Facades\Workflows;

Workflows::subjects()->register(
    Workflows::subject('purchase_request', PurchaseRequest::class)
        ->label('Purchase request')
        ->ownedBy('team')
        ->field('amount', 'decimal', 'Amount')
        ->field('requester', 'party', 'Requester'),
);

use RoundlyConsulting\Workflows\Traits\HasWorkflows;

class PurchaseRequest extends Model
{
    use HasWorkflows;   // $request->workflows(), touch on update, cancel on delete
}

use RoundlyConsulting\Workflows\Facades\Workflows;
use RoundlyConsulting\Workflows\Graph\Build\{Party, Trigger, When};

// Once, in a service provider: what a purchase request looks like to the engine.
Workflows::subjects()->register(
    Workflows::subject('purchase_request', PurchaseRequest::class)
        ->label('Purchase request')
        ->ownedBy('team')
        ->field('amount', 'decimal', 'Amount')
        ->field('requester', 'party', 'Requester')
        ->field('approver', 'party', 'Approver'),
);

// The workflow itself is data: a JSON graph your users edit in a builder — or written in PHP.
$definition = Workflows::definitions()->create(key: 'purchase-approval', name: 'Purchase approval',
    subjectType: 'purchase_request', owner: $team);

Workflows::definition('purchase-approval', $team)->edit(Workflows::graph()   // or ->edit(json_decode($json, true))
    ->trigger('start', Trigger::manual())
    ->condition('check', When::field('subject.amount')->gt('500'))
    ->approval('approve', approvers: [Party::field('subject.approver')])
    ->end('done')
    ->connect('start', 'check')
    ->connect('check', 'approve', on: 'true')
    ->connect('check', 'done', on: 'false')
    ->connect('approve', 'done', on: ['approved', 'rejected', 'expired']));
Workflows::definition('purchase-approval', $team)->publish(by: $admin);

// Start it (this graph's trigger is `manual`) — with an `event` trigger the app event starts it instead.
$result = Workflows::start('purchase-approval', subject: $request, owner: $team)
    ->by($request->requester)
    ->idempotencyKey("submit:{$request->id}")
    ->dispatch();

$result->instance->status;   // InstanceStatus::Running — a queue worker runs it on to the approval step, where it waits

php artisan vendor:publish --tag="workflows-config"         # config/workflows.php
php artisan vendor:publish --tag="workflows-migrations"     # the eight migrations, timestamped on publish
php artisan vendor:publish --tag="workflows-translations"   # lang/vendor/workflows/{en,sk}
php artisan vendor:publish --tag="workflows-routes"         # the opt-in inbound webhook route file

php artisan workflows:doctor            # --json for CI and health checks, --strict to fail on warnings
php artisan about --only=workflows        # step types, bridges, queue mode, key types, limits, webhooks