API Reference

Workflowable Facade

use Workflowable\Workflowable\Facades\Workflowable;

dispatch

Dispatch a workflow event asynchronously (queued).

Workflowable::dispatch(WorkflowEvent $event, ?int $userId = null): Collection

Returns a Collection<WorkflowInstance> of created instances.

dispatchSync

Dispatch a workflow event synchronously (inline execution).

Workflowable::dispatchSync(WorkflowEvent $event, ?int $userId = null): Collection

Blocks until each workflow reaches completion.

---

WorkflowEvent

Abstract base class for workflow event DTOs.

use Workflowable\Workflowable\Abstracts\WorkflowEvent;

class OrderSubmitted extends WorkflowEvent
{
    public function __construct(
        public readonly int $orderId,
        public readonly float $amount,
    ) {}

    // Optional: fields to encrypt at rest
    public static function encrypted(): array
    {
        return ['amount'];
    }
}

Constructor parameters become workflow variables accessible via ExecutionContext::getVariable().

---

Workflow Model

use Workflowable\Workflowable\Models\Workflow;

Attributes

Attribute	Type	Description
name	string	Workflow name
definition	array	JSON definition (cast)
description	string|null	Optional description
event_name	string|null	Event name this workflow responds to
version	int	Version number (default: 1)
is_active	bool	Whether this version accepts new instances
created_by	int|null	Optional user ID

Methods

// Publish a new version
$workflow->publish(WorkflowDefinition $definition): Workflow

// Get all step names from the definition
$workflow->getAllStepNames(): array

// Check if a newer version exists
$workflow->hasNewerVersion(): bool

// Get the latest version model
$workflow->latestVersion(): Workflow

Scopes

Workflow::versionsOf('order_processing')->get();
Workflow::latestVersion('order_processing')->first();
Workflow::active()->get();
Workflow::forEvent('order_submitted')->get();
Workflow::byName('order_processing')->get();

Relationships

$workflow->instances(); // HasMany WorkflowInstance

---

WorkflowInstance Model

use Workflowable\Workflowable\Models\WorkflowInstance;

Attributes

Attribute	Type	Description
uuid	string	Unique identifier for event sourcing aggregate
workflow_id	int	FK to Workflow
current_step	string|null	Current step (null when completed)
status	string	pending, in_progress, completed, failed
workflow_event	WorkflowEvent	Serialized WorkflowEvent DTO
state	array	Mutable runtime variables (event data + step outputs)
error_message	string|null	Error message if failed
created_by	int|null	User who created the instance
completed_at	Carbon|null	When execution finished

Methods

$instance->isCompleted(): bool
$instance->isFailed(): bool
$instance->isPending(): bool
$instance->isInProgress(): bool

// Get a specific variable from state
$instance->getVariable(string $key, mixed $default = null): mixed

// Set a workflow variable (call save() to persist)
$instance->setVariable(string $key, mixed $value): void

// Event sourcing
$instance->storedEvents(int $limit = 50): Collection
$instance->rebuildState(): array
$instance->verifyState(): array  // Returns ['match' => bool, 'persisted' => [], 'replayed' => [], 'diff' => []]

Relationships

$instance->workflow();        // BelongsTo Workflow
$instance->stepExecutions();  // HasMany StepExecution

---

ExecutionContext

use Workflowable\Workflowable\Engine\ExecutionContext;

Passed to action handlers during step execution.

// Variables
$context->getVariable(string $key, mixed $default = null): mixed
$context->getVariables(): array
$context->setVariable(string $key, mixed $value): void
$context->mergeVariables(array $variables): void

// Step definition (config set at design time)
$context->getStepConfig(string $key, mixed $default = null): mixed
$context->getStepDefinition(): array

// Navigation
$context->getCurrentStep(): string
$context->getStepHistory(): array

// Models
$context->getInstance(): WorkflowInstance
$context->getWorkflow(): Workflow

---

ActionRegistry

use Workflowable\Workflowable\Registries\ActionRegistry;

Manages the mapping of friendly action names to handler classes.

$registry = app(ActionRegistry::class);

// Registration
$registry->register(string $name, string $class, string $description = ''): void

// Resolution
$registry->resolve(string $name): callable  // Throws StepExecutionException if not found
$registry->has(string $name): bool

// Discovery
$registry->names(): array                   // All registered names
$registry->all(): array                     // All actions with metadata
$registry->catalog(): array                 // name => description map
$registry->schema(): array                  // Full schema with parameter definitions

// Parameters (for handlers implementing DefinesParameters)
$registry->getParameters(string $name): array  // Returns Parameter[] or []

---

ConditionalRegistry

use Workflowable\Workflowable\Registries\ConditionalRegistry;

Manages the mapping of conditional names to evaluator classes. All classes must implement the Conditional interface.

$registry = app(ConditionalRegistry::class);

// Registration
$registry->register(string $name, string $class, string $description = ''): void

// Resolution
$registry->resolve(string $name): Conditional  // Throws StepExecutionException if not found
$registry->has(string $name): bool

// Discovery
$registry->names(): array                   // All registered names
$registry->all(): array                     // All conditionals with metadata
$registry->catalog(): array                 // name => description map
$registry->schema(): array                  // Full schema with parameter definitions

// Parameters (for handlers implementing DefinesParameters)
$registry->getParameters(string $name): array  // Returns Parameter[] or []

---

StepResult

use Workflowable\Workflowable\Engine\StepResult;

StepResult::success(mixed $output = null, ?string $nextStep = null, ?string $condition = null);
StepResult::failed(string $error);
StepResult::waiting(mixed $output = null, ?string $nextStep = null);