Building a visual editor

The package ships no UI. It gives a builder everything it needs to draw, edit, check, compare, preview and monitor a workflow. Wire these behind your own controllers and authorization (the owner’s admins only):

• Two tabs: send the checksum the editor loaded as $expectedChecksum; a stale save throws DraftConflictException (409).
• Half-finished graphs save fine; only publish validates fully.
• Positions and labels go in each node’s ui object — kept verbatim, ignored by the engine, reported as moved by the diff.
• Node ids are the builder’s (^[a-z][a-z0-9_]{0,63}$); imports remap them (ImportResult::$idMap).
• Validation errors point at a node, an edge or a JSON pointer inside the node’s config, so the builder can highlight the exact field. Messages are translated (en, sk) and contain no class names.
• No class names anywhere: subject types are registry keys, references render through the reference resources.

JSON resources

The builder and admin API is yours: use the manager plus these resources (RoundlyConsulting\Workflows\Http\Resources), behind your own authorization:

use RoundlyConsulting\Workflows\Http\Resources\{CatalogueEntryResource, InstanceResource, ValidationReportResource};

// The palette and a step's form
return CatalogueEntryResource::collection(Workflows::catalogue()->export()->types);

// Live validation
return new ValidationReportResource(Workflows::versions()->validate($request->input('graph'), 'purchase_request', $team));

// One run in detail: steps, waits and escalations in a fixed number of queries
$instance = Workflows::instances()->find($ulid) ?? abort(404);
Workflows::instances()->detail($instance);

return new InstanceResource($instance->loadMissing(['subject', 'owner', 'starter']));

• definition, version, subject, owner, started_by and published_by render only from loaded relations or the stored morph pair: a collection never queries per row. Eager-load what you need: ->with(['definition', 'version', 'subject', 'owner', 'starter']).
• Workflows::instances()->detail($instance) loadMissing()s the definition, the version, the step log (in order), the pending waits and the pending escalations (by due time), so InstanceResource renders steps, waits and escalations in a fixed number of queries. Without detail() those three keys are left out.
• Unknown exception messages never go over the wire: for exception or worker_timeout the message is the translated workflows::failures.exception; the raw message stays in the database for operators.
• output.request_id of an approval step is the round to decide within().

Reference resources — no class names over the wire

Host models (owner, subject, user) render through a reference resource — by default only {id, type: class_basename}, never a morph class or a class name. A deleted subject renders from its stored pair, no query:

final class TeamReferenceResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return ['id' => $this->resource->getKey(), 'name' => $this->resource->name];
    }
}

// config/workflows.php
'resources' => ['owner' => TeamReferenceResource::class, ...],

A blank value falls back to the default; anything that isn’t an instantiable JsonResource subclass (the bare base included) throws InvalidWorkflowsConfigurationException naming the key.

Error → HTTP mapping

Every package exception extends WorkflowsException with errorCode(), status() and context(); the full list is under Exceptions:

try {
    $result = $workflows->start($key, $subject, $owner)->input($request->all())->by($request->user())->dispatch();
} catch (WorkflowsException $e) {
    return response()->json(['code' => $e->errorCode(), 'message' => $e->getMessage()], $e->status());
}