Filament Flow Laravel Package

Product Decisions This Supports

• Bulk operations for stateful records in admin panels. Ops/support/admin users can move many Eloquent records through a workflow in one action instead of opening each record. This supports the roadmap item "make back-office teams self-sufficient," and it underpins any feature where a human triages a queue: order fulfillment, refunds and disputes, KYC/onboarding review, content moderation, ticket escalation, subscription lifecycle.
• Scoping which transitions are bulk-eligible. The new optional $only argument lets a PM decide, per surface, which transitions deserve a bulk button (e.g. "Approve" and "Reject" in bulk, but "Cancel" only one-at-a-time because it needs a reason). [] disables bulk entirely for a surface, null keeps the previous "everything" behavior. This is a product-policy lever, not just an API detail: it is how you avoid shipping a bulk action for a destructive or irreversible transition.
• Access rules as first-class product behavior. Because each record resolves its own available transitions for the current user, a bulk action no longer assumes one size fits all. A PM can promise "bulk actions respect the same permissions, actors and guards as single-record actions" — and can now report the difference to the user rather than silently skipping.
• Build vs buy. The alternative is building bulk transition UI, per-record authorization, deduplication, and a workflow-definition diff/migration planner in-house. This package makes that a buy decision: a Filament-native workflow layer rather than weeks of custom bulk-action plumbing plus a homegrown migration tool for workflow definitions. The metadata fix is the strongest argument here — it's exactly the class of bug a team would ship and not notice for months.
• Workflow definition evolution as a supported workflow. The planner now detects changes to a state's metadata and applies them to workflows already persisted in the database. That turns "we want to change a state's config without a data migration" into a decision you can actually make, and it de-risks iterative rollout of workflow tweaks.

When to Consider This Package

Consider adoption when most of the following hold:

• The product runs on Laravel + Filament, and operators already work in a Filament admin panel.
• Domain entities have a genuine lifecycle (order → paid → shipped → delivered → refunded), not a boolean flag. State machines with guards, actors and roles are the natural model.
• Bulk triage is a real workflow, not a nice-to-have: queues where a human clears 20–200 records a day. If every record is handled individually, the value drops sharply.
• You need per-record authorization on those bulk operations, and you need the UI to distinguish "this transition doesn't apply to this record" from "it applies, but you're not allowed."
• You expect workflow definitions to change over time and want those changes reflected in existing data without hand-written migrations.
• You want localized operator-facing messaging out of the box (English and Italian shipped; the abstraction is there for more).

Look elsewhere when:

• The stack is not Laravel/Filament — this is tightly coupled to Filament admin surfaces.
• You need cross-service orchestration, sagas, retries or long-running processes. This is a state machine for human-driven transitions in an admin UI, not a workflow engine.
• The lifecycle is trivially linear and permanent (e.g. draft → published with no branching and no ops intervention). A column and a button will do.
• You require stable, versioned APIs. At v0.5.0 the surface is still moving; the deduplication change in this very release is a behavioral change to what operators see.
• You need per-record hiding of a bulk action. The docblock now correctly states this isn't possible: a bulk action is either offered or not, and unavailable records are reported rather than removed.

How to Pitch It (Stakeholders)

For executives: This is an operational-efficiency and correctness release for the admin tooling our back-office teams use. It lets staff move many records through their lifecycle in a single action, while guaranteeing each record still respects the same permission and approval rules as acting on it individually. That directly reduces the manual click-per-record cost of clearing queues, and it removes a class of silent-failure bug: changes to a workflow's state configuration were previously never applied to records already in the database, meaning configuration drifted from reality without anyone noticing. The package is pre-1.0, so we should expect API churn and plan for upgrade work; but the alternative is maintaining our own bulk-transition and workflow-migration plumbing, which is a larger and more permanent cost.

For engineering: v0.5.0 makes StateBulkActionGroup::forDatabaseRecord() production-usable. Highlights: (1) an $only filter to restrict which transitions are offered in bulk — null means all, [] means none, preserving backwards compatibility; (2) deduplication of transitions that are identical from the user's perspective (same label, same target state), with each record resolving the one transition getAvailableTransitions() actually offers to the current user; (3) per-record outcomes are now honest — skipped when the state doesn't apply, reported (not silently dropped) when it applies but access rules, actor or guards block it, backed by a new filament-flow.bulk_action.not_available string in EN/IT. (4) The planner's DiffsWorkflowDefinition::stateChanged now detects metadata changes, so metadata edits are applied to already-persisted workflows instead of being silently discarded.

Two things worth flagging in review: the deduplication is a behavioral change — panels that previously rendered two visually identical actions will now render one, and the surviving action is resolved per record, so snapshot existing admin screens before upgrading. And the metadata fix means diffs that were previously ignored will now be applied the next time definitions are planned against a database; test the plan output against staging before running it on production, because it may surface drift that was invisible until now. The docblock correction — that a bulk action cannot be hidden per record — is documentation catching up to reality rather than a functional change, but it should be reflected in our UX copy: unavailable records are reported, not hidden.