Formflow Bundle Laravel Package

Getting Started

This release is a patch-level sync of upstream FormFlow fixes from Symfony (PR #10); there are no new APIs, breaking changes, or deprecations. The package is a Symfony bundle (yceruto/formflow-bundle), not a native Laravel package, so day-to-day leverage in Laravel is limited unless you intentionally bridge Symfony Form/FormFlow into your app.

First steps:

• Read the underlying yceruto/formflow component docs before the bundle docs. The bundle mainly provides Symfony DI wiring, tags, and config; most of that is irrelevant in Laravel.
• Decide whether you need multi-step form flows with explicit transitions. If yes, evaluate using the framework-agnostic FormFlow component directly rather than the bundle.
• Minimal first use case: define a flow class with ordered steps and transitions, store the current step in session or a database column, and process each step in a Laravel controller/service.
• Treat v0.4.2 as a safe patch on top of v0.4.1; start from existing v0.4.x documentation and examples.

Implementation Patterns

• Define flows as classes extending AbstractFormFlow or implementing the flow interface, configuring steps via addStep() and transitions via addTransition(). Keep step names stable because they are persisted state keys.
• In Symfony the flow is registered as a tagged service. In Laravel, bind flow classes in a service provider and resolve them through a small factory or dedicated manager class.
• Persist workflow state per user/entity: current step, completed steps, and any transition history. Wrap applyTransition() and isFinished() calls in a transaction when state changes affect domain data.
• If you do not want Symfony Form in your dependency tree, use Laravel validation and Blade rendering, and treat FormFlow purely as a transition/state engine. If you do bridge Symfony Form, isolate the form factory adapter behind an interface.
• Use transition guards and flow event/listener hooks for authorization, validation gates, and side effects. In Laravel these can be implemented as callables or dedicated listener classes registered in your adapter.
• Pin to ^0.4 and re-run flow transition tests after patch upgrades, since upstream Symfony fixes can subtly affect edge-case behavior.

Gotchas and Tips

• The bundle is Symfony-specific: autowiring, service tags, and form_flow configuration do not exist in Laravel. Do not expect Artisan commands, Laravel facades, or native config publishing.
• v0.4.2 contains no breaking changes, but it syncs Symfony fixes. If you have a custom bridge, review your adapter tests for changed edge-case behavior in form handling or transition resolution.
• Debugging is easier if you log every transition attempt and the current step. FormFlow exceptions around invalid transitions are usually caused by stale persisted step names or mismatched transition definitions.
• Avoid mixing Laravel FormRequest validation with Symfony Form data mappers without a clear boundary; choose one validation and rendering path per step.
• Extension points worth knowing: custom step types, transition guards, and flow listeners. Implement them in your Laravel adapter rather than editing vendor code.
• Before adding Symfony dependencies, compare with native Laravel options such as Livewire multi-step wizards or a dedicated state machine package; for many Laravel apps those will be simpler than bridging this bundle.