- What is robyconte/filament-flow and what does it do?
- Filament Flow is a Laravel and Filament package that acts as a business process manager: it models workflows as state machines where records sit in a state and named transitions move them between states. It adds a canvas-style, node-based flow builder to the Filament admin panel so you can connect steps and define transition logic visually. Transitions can be gated by access rules, actor checks and guards, and the same definition drives the Filament UI actions your operators use. The package is at v0.5.0, so treat it as pre-1.0 software and review release notes before adopting it.
- How do I install filament-flow in a Laravel Filament application?
- Install it with Composer using composer require robyconte/filament-flow, then register the plugin on your Filament panel following the package setup instructions. Because workflow definitions are persisted to the database, you will also need to run the package migrations before designing your first flow. Minimum Laravel and Filament versions are not stated in the v0.5.0 release notes, so check the composer.json constraints before committing. Verify the panel registration and front-end asset build work in a staging environment first, since the canvas editor ships assets.
- Does filament-flow store workflow definitions in code or in the database?
- Both. You define the workflow in PHP, and the package persists that definition to the database with a diffing layer, DiffsWorkflowDefinition, reconciling code against stored state. That design suits teams that keep iterating on state machines after launch rather than freezing them at version one. Be aware that v0.5.0 includes a metadata fix, so workflows already in the database will now receive metadata changes that were previously dropped. That means your next deploy can mutate live workflow definitions, so review the diff carefully first.
- How do access rules, actor checks and guards work on filament-flow transitions?
- Every transition can be gated by access rules, actor checks and guards, so whether a record can move depends on the current user as well as on the record's current state. Applicability is resolved through getAvailableTransitions(), which returns the transitions available for the current user. As of v0.5.0, a record that is applicable by state but blocked by access rules, actor or guards is reported rather than silently omitted. Check how that reporting surfaces in your panel, because a Filament bulk action cannot be hidden record by record.
- Why did my Filament bulk transition actions change after upgrading to filament-flow v0.5.0?
- v0.5.0 changes bulk transition behaviour in two ways. Duplicate-looking transitions now collapse into one action using a dedup rule of same label and same target state, so UI copy and tests that assumed one action per transition may need updating. Records that are applicable by state but blocked by access rules, actor checks or guards are now reported instead of disappearing from the result. Review operator runbooks, translations and any test assertions on action counts.
- Does the new forDatabaseRecord() signature in filament-flow break backward compatibility?
- The change is additive: the new $only parameter is optional and defaults to null, which preserves existing behaviour, so current call sites should still compile. The real integration surface in v0.5.0 is behavioural rather than the method signature, covering deduplication, getAvailableTransitions() resolution and blocked-record reporting. Whether forDatabaseRecord() is covered by the package's backward compatibility promise, and what the deprecation policy is for the docblock semantics that changed, is worth confirming with the maintainer before you rely on it.
- Is it safe to upgrade to filament-flow v0.5.0 in production?
- Risk is moderate and concentrated in three places. The dedup heuristic can merge two genuinely distinct transitions that share a label and target, and the surviving behaviour depends on the current user's getAvailableTransitions(), which is non-deterministic across your operator population. The metadata fix is the highest-risk item, because workflows already in the database will now receive metadata changes and your next deploy can mutate live definitions. Ask whether the metadata diff is forward-only and whether a dry-run or preview against an existing database is available before shipping.
- Can I use filament-flow if my workflow state lives in an external system?
- Filament Flow is opinionated: state lives on Eloquent models, transitions are row updates rather than event-sourced events, and the admin surface is Filament. It fits admin-panel-heavy Laravel applications where operators work through Filament resources and workflow definitions evolve over time. It is a poorer fit if an external system owns workflow state, if you need event sourcing, or if your admin UI is not Filament. Evaluate those constraints before adopting it rather than assuming it can be adapted.
- How should I test a Laravel application that uses filament-flow?
- Test transition applicability through getAvailableTransitions() rather than assuming one action per transition, since v0.5.0 deduplicates by label and target state. Add coverage for the blocked path too, asserting how records failing access rules, actor checks or guards are reported to the operator. Bulk action tests should reflect that actions are no longer hidden record by record. Pin your workflow definitions in fixtures so metadata diff behaviour against an existing database is exercised deliberately.
- Does filament-flow support localisation, or is English the only language?
- v0.5.0 introduces a filament-flow.bulk_action.not_available string, and the release notes reference both EN and IT strings, but whether that translation set is complete is unclear. Audit which keys your panel actually renders and confirm untranslated keys fall back safely rather than showing raw keys. If you ship multiple locales, plan for ongoing localisation as new bulk-action and reporting messages are added. Publishing the package translation files is the usual way to override or extend them.