Filament Workflows Laravel Package

Getting Started

• Requirements first: PHP 8.2+, Laravel 12/13, Filament 5, and tomatophp/filament-icons ^5. Do not attempt this on a Laravel 11 / Filament 3 app — that code path lives on the v3 branch.
• Install and migrate: composer require the package, then php artisan migrate. You get tables for workflows, triggers, actions and workflow logs. If you skip this, nothing errors (the trait is deliberately migration-safe) — it just silently does nothing.
• See it before you build it: open the Workflows resource in your Filament panel and use the rebuilt Builder page to assemble a workflow visually. It is the fastest way to understand the Workflow → Trigger → Action → Workflow Log data model.
• Wire a model: add the InteractsWithWorkflow trait to the model whose created / updated / deleted events should start a workflow.
• Register actions: in a service provider boot(), call FilamentWorkflows::action([SendWelcomeMail::class, AssignOwner::class]). Classes must extend Services\Abstracts\Action — anything else is ignored.
• First use case: Order created → trigger condition status is pending → action sends a notification → open the Workflow Log list and confirm one row per run. That loop (model event → condition → action → log) is 90% of day-to-day usage.

Implementation Patterns

• Action class shape. One action, one side effect, extending Services\Abstracts\Action. Keep them idempotent: they can be re-run from a Workflow Log investigation, and multiple workflows may call the same one.
• Central registration. Put FilamentWorkflows::action([...]) in a dedicated WorkflowServiceProvider (or a clearly commented block in AppServiceProvider) so reviewers can see every runnable action in one place. The array form registers all entries at once — use it rather than repeated single calls.
• Conditions as cheap gates. The trigger filter is a single-record where / is / value comparison. Use it to short-circuit obviously irrelevant events, and move anything richer (multi-field checks, related-model lookups, "only if not already processed") into the first action of the workflow.
• Three trigger families. Model events via the trait for internal changes; dispatched events for domain signals that don't map to a save; webhooks for inbound traffic from third parties. Point the provider at the webhook endpoint, send GET for pings and POST for payloads.
• Webhook setup as an ops task. Generate a strong FILAMENT_WORKFLOWS_WEBHOOK_TOKEN per environment, store it in your secret manager, and only then enable the endpoint — it is closed until the token is set. Because the token is kept out of logs, instrument the sender with a request ID if you need to trace calls.
• Testing. Use the shipped factories (Workflow, Trigger, Action, WorkflowLog) inside RefreshDatabase tests: build a workflow, dispatch the model event, assert the side effect and the Workflow Log row. This is also the cheapest way to verify a condition filter behaves as you expect.
• Observability. The log table is your audit trail — one row per workflow run. Surface it in a dashboard widget or a "recent runs" table on the resource before you have a production incident.
• Integration tip: because only Abstract\Action subclasses execute, treat the base class as an architectural contract. Code review should reject any class registered in FilamentWorkflows::action() that doesn't extend it.

Gotchas and Tips

• Silent non-execution. A registered class that doesn't extend Services\Abstracts\Action simply doesn't run. There is no exception at registration time — you'll only notice via a Workflow Log run with no effect.
• Every active workflow fires. Model/event/webhook triggers run the attached actions of every active workflow. Two active workflows with overlapping actions means duplicate side effects. Deactivate the old workflow rather than layering a new one on top.
• Partial failure is normal. A failing action is logged and the remaining actions still run. Design for it: idempotent actions, defensive external calls, and a habit of scanning logs for failure entries rather than assuming "no exception = success".
• Silent no-op before migration. InteractsWithWorkflow is safe on an unmigrated database — which is great for rolling deploys, but means "workflows aren't firing" is very often "the tables aren't there yet". Check php artisan migrate:status first.
• Webhook debugging is deliberately opaque. Closed-by-default, constant-time token comparison, token stripped from logs. You won't get "bad token" vs "missing token" detail in the logs — verify config and sender headers manually.
• Throttling will bite busy senders. If a third party calls frequently, expect 429s; make the sender retry with backoff and confirm the throttle limit is appropriate for your volume.
• Don't over-read the condition filter. where / is / value against a single record is not a query builder — no orWhere chains, no relation-based conditions. Complex branching belongs in actions.
• Execution is not queued (per the release notes). Actions run in the lifecycle of the triggering request. Long-running or network-heavy actions will slow every save of the model — wrap the work in your own job dispatch inside the action.
• Log table growth. One row per run per event on a busy model adds up quickly. Plan pruning/retention from day one.
• Upgrading from v3. There's no documented in-place upgrade path and the Builder page was rebuilt for Filament 5. If you customised builder views or assets, re-publish and re-check them; pin filament-icons to ^5 alongside Filament 5 to avoid panel boot failures.
• Extension points worth knowing: model factories (for your own test suites), the Abstract\Action base class, event triggers for custom domain signals, and the Filament resource/page layer for admin-facing customisation.