Filament Flow Laravel Package

Getting Started

• Install with composer require and publish the package assets: config, migrations, and translations (vendor:publish --tag=filament-flow-config, --tag=filament-flow-migrations, --tag=filament-flow-lang — confirm exact tags in the package README, they vary between releases).
• Look first at three places: the published config (default workflow / persistence driver), the trait or interface you add to an Eloquent model, and the StateBulkActionGroup usage example in the docs for a Filament resource table.
• First use case: attach a workflow to a model, define states and transitions, then drop a bulk action group onto the resource table:

StateBulkActionGroup::forDatabaseRecord(only: ['submit', 'approve'])
    ->label('Change state');

Bulk actions are the highest-leverage feature here — they let an admin move many records through a workflow in one click while still respecting per-record guards and policies. Start with an explicit allow-list rather than null so you see exactly which transitions are exposed.

Implementation Patterns

• Allow-list your bulk transitions. forDatabaseRecord(only: [...]) takes transition names. Use ['publish', 'archive'] style lists in production resources and reserve null (all transitions) for internal/admin-only panels. Pass [] to register the action but expose nothing — handy for feature-flagging a bulk action off without editing the table schema.
• Let the package do per-record resolution. The action now collapses transitions that read identically to the user (same label, same target state) into one action, and each record gets whichever concrete transition getAvailableTransitions() offers that user. This means one bulk button can legitimately perform approve_level_1 on some records and approve_level_2 on others if they display the same. Design your transition labels with that in mind: if two transitions must be visibly distinct in the UI, give them distinct labels.
• Handle the "not available" report. Records that are state-eligible but blocked by access rules, actor checks, or guards are no longer silently swept away — they are reported. Wire the report into a Filament notification so operators learn that 3 of 50 records were skipped and why. The package ships filament-flow.bulk_action.not_available (EN/IT) for this; use it rather than hand-rolling copy.
• Planner-driven metadata. DiffsWorkflowDefinition::stateChanged now detects changes to a state's metadata, so edits to labels, colours, SLA durations, or flags stored in metadata are applied to workflows already in the database. Treat the workflow definition as code: change it, run your planner/sync step (artisan command or deploy hook), and let it reconcile. This is the cleanest way to version workflow metadata without manual SQL.
• Localisation. English and Italian ship in the box. Publish the lang files and add your own locale keys under filament-flow.bulk_action.* instead of overriding the vendor directory, so package updates don't clobber your strings.
• Testing. Write feature tests that assert getAvailableTransitions() for a given user/record pair, then assert the bulk action result. This is where the majority of workflow bugs live — not in the transition definitions themselves but in who is allowed to take them.

Gotchas and Tips

• A bulk action cannot be hidden per record. The docblock now says so explicitly. If you were relying on hidden() to make the button disappear for some rows, that assumption is wrong — the action appears, and non-applicable records are skipped or reported. Move that logic into guards/policies so it surfaces as a report rather than an invisible rule.
• null vs [] are opposites. null = every transition (the old behaviour, backwards compatible); [] = none. A ?? [] in your own code will silently disable the action — be deliberate.
• Deduplication happens after $only filtering but changes what the user sees. Two transitions with identical label + target state become one action, yet $only filters by transition name. If you list only one of a duplicate pair, verify in a test which action actually renders — the merge can surprise you.
• Metadata sync is a behaviour change. Anything that previously "didn't take" when you edited metadata now does. If you have manual DB edits to state metadata in production, a planner run will overwrite them. Audit before deploying and move those edits into the definition.
• Silent vs reported skips. State-mismatched records are skipped quietly; permission-blocked ones are reported. If your notification layer swallows the report, users see a partial success with no explanation and will file bugs. Log or toast it.
• Debugging "why was this record skipped": dump getAvailableTransitions() for the acting user and that record. Nine times out of ten it is the guard, the actor resolution, or a policy — not the bulk action.
• Missing translations show the raw key. If you see filament-flow.bulk_action.not_available in the UI, your locale isn't published or the app locale falls outside EN/IT.
• Extension points: customise labels and ordering on the transition definitions (they drive the merged action's label), wrap the action to add confirmation modals per target state, and subclass/replace the report handler to route skipped records into an audit log.