Download the PHP package briefley/filament-workflow-builder without Composer

Filament Workflow Builder

A generic Laravel workflow orchestration package with pluggable step executors and an optional Filament admin UI.

Features

• Interval and fixed-time daily workflow scheduling.
• Queue-driven workflow execution with pluggable step executors.
• Stale run protection and overlap control.
• Filament integration with a single Workflows navigation entry:
  • Steps relation manager for workflow step configuration.
  • Runs relation manager for history.
  • Run steps visible in a modal from each run row.

Compatibility Matrix

Release Lines

• ^1.x (Filament v5) is the default and latest release line.
• ^0.4.x is the Filament v4 maintenance line.
• ^0.3.x is the Filament v3 maintenance line.

Latest Tags

• 1.0.3 for Filament v5 projects.
• 0.4.1 for Filament v4 projects.
• 0.3.1 for Filament v3 projects.

Installation

1. Require the package for your Filament major.

2. Publish config and migrations.

Maintenance Policy

• ^1.x (Filament v5) is the primary feature line.
• ^0.4.x (Filament v4) and ^0.3.x (Filament v3) are compatibility maintenance lines.
• New features are developed on ^1.x first, then selectively backported when safe.

Configuration

Define available step types and executors in config/workflow-builder.php:

Build Your Own Workflow Jobs

1. Create a step executor

Each workflow "job" is a step type mapped to an executor class.

1.1 Pass data from previous steps (optional)

If your job needs outputs from earlier jobs in the same workflow run, implement:

• Briefley\WorkflowBuilder\Contracts\ContextAwareWorkflowStepExecutor

You will receive WorkflowStepExecutionContext containing succeeded previous step outputs (meta).

Helpful context methods:

• latestMetaForStepType(string $stepType): ?array
• latestValueForStepType(string $stepType, string $key, mixed $default = null): mixed
• metaForSequence(int $sequence): ?array
• valueForSequence(int $sequence, string $key, mixed $default = null): mixed

2. Return one of the supported step results

Each step executor must implement:

• Briefley\WorkflowBuilder\Contracts\WorkflowStepExecutor

and return Briefley\WorkflowBuilder\DTO\StepExecutionResult from execute():

• StepExecutionResult::succeeded(...) for completed steps.
• StepExecutionResult::failed('reason') to fail the run.
• StepExecutionResult::waiting(...) for async polling-style steps.

2.1 Production reliability tips

When implementing real jobs, these two patterns help avoid common production failures:

• Make retryable steps idempotent. Persist processed item identifiers (for example email addresses, external IDs, or row hashes) in step meta, and skip already-processed items on retry.
• Avoid dev-only runtime dependencies in executors. If your executor uses optional helpers/libraries (for example Faker), provide a fallback path so production installs with --no-dev do not crash.

3. Register your step type in config

Add your label and executor to config/workflow-builder.php:

The step_executors key is the runtime source of truth.
The workflow_jobs key is used for friendly labels in UI selectors.

4. Add the step in Filament

1. Open Workflows.
2. Create or edit a workflow.
3. In the Steps relation manager, add a row with your step type.
4. Order steps by sequence.

5. Run scheduler + queue worker

The package dispatches due workflows from the scheduler, and steps execute in queue jobs.

If you use Horizon, run Horizon instead of queue:work.

Scheduler

Dispatch due workflows every minute from your scheduler:

Filament Plugin

Register the plugin in your panel provider:

The plugin registers only the WorkflowResource and manages steps/runs via relation managers.

Testing

Run the package test suite: