Filament Flow Builder Laravel Package

Getting Started

• Check the floor first. The package requires PHP 8.3+, Laravel 13 and Filament v5. That combination is very new — it will not install on Laravel 11/12 or Filament v3/v4. Confirm your app is actually on that stack before running composer require banyancms/filament-flow-builder, or you'll spend an hour on a dependency resolution problem that isn't the package's fault.
• Read docs/guide.md before the README. The README is a feature summary; the guide is where the actual wiring lives.
• Then read the purchase-request example. It's the single most useful artefact in the release: approvers, history, reminders and a stuck-flow retry, end to end. Copy its shape rather than inventing your own.
• Expect to write schema yourself. The package owns no tables. You add columns to your model: one JSON column for the flow definition, and columns for the runner's position/state. There is no install migration to run and therefore no install error if you forget — you'll get a runtime failure later instead.
• Define your vocabulary in code. StepType and ConditionType subclasses are where your app decides what a step means and what a condition can test. Do this before touching the UI; the builder is only as useful as the types you register.
• First use case: pick a linear approval chain — purchase request, leave request, content sign-off — not something with branching. On a v0.1.0 you want a small blast radius while you learn the JSON contract.

Implementation Patterns

• Two integration surfaces, pick deliberately. FlowBuilderField when the flow is an attribute of a record edited inside a resource form; the InteractsWithFlowBuilder trait on your own page when the flow is the page. The trait is also the multi-panel path — advertised as working in more than one panel, so verify it in each panel you ship.
• Treat the flow JSON as a versioned contract. It lives in your column, but its shape is defined by your StepType/ConditionType classes. When you rename a type or change its config shape, in-flight flows break silently. Snapshot the JSON on each publish, or version the schema, before you go live.
• Put all side effects in event listeners. StepReached, StepSkipped, OutcomeChosen, FlowReturned, FlowFinished are the intended seam: notifications, audit log rows, status column updates. Keep the runner call itself thin so you can re-run it without re-notifying.
• Resolve approvers at step-reach, not at design time. Any/all/count-of approvers is built in, but who the approvers are is your query against your own users/roles. Resolving at design time gives you stale approver sets the moment someone changes team.
• Model request changes and parallel approvals as your own state, driven by the events, in your own status column. The package deliberately doesn't own state — that's a feature, but it means the state machine is yours to keep consistent.
• Use the purchase-request example as an architecture reference, specifically its reminder + stuck-flow retry path. That's the operational half of a workflow feature that most implementations skip.

Gotchas and Tips

• v0.1.0 is pre-1.0. Pin the exact version in composer.json and keep a smoke test that round-trips a stored flow through the runner. Class names and the JSON schema can move under you.
• No tables means no guardrails. Missing columns surface as confusing runtime errors, not install failures. Add the columns and a test that asserts a flow can be saved and loaded before writing any UI.
• One owner of "where am I". The runner position is on your model, and your listeners will also want to write a status column. Pick one as truth and derive the other, or the two will diverge after the first failed transition.
• Stuck flows are the real production risk — a runner with no active step and no FlowFinished. Build the retry/reminder path from the example before shipping, not after the first incident.
• Log skipped as well as reached. StepSkipped carries the audit information your compliance reviewers will ask for ("why did this never go to finance?"); a log built only on StepReached can't answer that.
• Conditions skip, they don't branch. A condition bypasses a step; it does not route to an alternate parallel path. If you need real branching, model it as separate flows or as extra conditional steps — don't fight the model.
• Publish views before customising card UI. Forking vendor views is the fastest way to make a 0.x upgrade painful.
• Verify multi-panel behaviour explicitly. Panels differ in resource discovery and navigation registration; test the builder in each panel rather than assuming the trait makes it portable.
• Translation coverage is en / zh-TW / zh-CN. Anything else means publishing and maintaining the lang files yourself — factor that into estimates.
• The extension surface is deliberately small: StepType, ConditionType, the five events, published views and translations. Stay inside it; reaching into internals of a 0.x package is how you end up pinned to a version forever.