[Form] Add `FormFlow` for multistep forms management #60212

yceruto · Apr 13, 2025

Q	A
Branch?	7.4
Bug fix?	no
New feature?	yes
Deprecations?	no
Issues	-
License	MIT

Alternative to #59548, inspired on @silasjoisten's work and @craue's bundle, thank you!

FormFlow

This PR introduces FormFlow, a component built on top of the existing Form architecture. It handles the definition, creation, and handling of multistep forms, including data management, actions (explained below), and validations across steps.

`AbstractFlowType`

Just like AbstractType defines a single form based on the FormType, AbstractFlowType can be used to define a multistep form based on FormFlowType.

class UserSignUpType extends AbstractFlowType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder->addStep('personal', UserSignUpPersonalType::class);
        $builder->addStep('professional', UserSignUpProfessionalType::class);
        $builder->addStep('account', UserSignUpAccountType::class);

        $builder->add('navigator', FormFlowNavigatorType::class);
    }

    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'data_class' => UserSignUp::class,
            'step_property_path' => 'currentStep', // declared in UserSignUp::$currentStep
        ]);
    }
}

The step name comes from the first param of addStep(), which matches the form name, like this:

The personal form of type UserSignUpPersonalType will be the step personal,
The professional form of type UserSignUpProfessionalType will be the step professional,
and so on.

When the form is created, the currentStep value determines which step form to build, only the matching one, from the steps defined above, will be built.

Type Extension

FormFlowType is a regular form type in the Form system, so you can use AbstractTypeExtension to extend one or more of them:

class UserSignUpTypeExtension extends AbstractTypeExtension
{
    /**
     * @param FormFlowBuilderInterface $builder
     */
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder->addStep('role', UserSignUpRoleType::class, priority: 1); // added to the beginning cos higher priority
        $builder->removeStep('account');
        if ($builder->hasStep('professional')) {
            $builder->getStep('professional')->setSkip(fn (UserSignUp $data) => !$data->personal->working);
        }
        $builder->addStep('onboarding', UserSignUpOnboardingType::class); // added at the end
    }

    public static function getExtendedTypes(): iterable
    {
        yield UserSignUpType::class;
    }
}

Controller

Use the existent createForm() in your controller to create a FormFlow instance.

class UserSignUpController extends AbstractController
{
    #[Route('/signup')]
    public function __invoke(Request $request): Response
    {
        $flow = $this->createForm(UserSignUpType::class, new UserSignUp())
            ->handleRequest($request);

        if ($flow->isSubmitted() && $flow->isValid() && $flow->isFinished()) {
            // do something with $form->getData()

            return $this->redirectToRoute('app_signup_success');
        }

        return $this->render('signup/flow.html.twig', [
            'form' => $flow->getStepForm(),
        ]);
    }
}

This follows the classic form creation and handling pattern, with 2 key differences:

The check $flow->isFinished() to know if the finish action button was clicked,
The $flow->getStepForm() call, which creates the a new step form, when necessary, based on the current state.

Don’t be misled by the $flow variable name, it’s just a Form descendant with FormFlow capabilities.

Important

The form data will be stored across steps, meaning the initial data set during the FormFlow creation won't match the one returned by $form->getData() at the end. Therefore, always use $form->getData() when the flow finishes.

`FormFlowActionType`

A FormFlow action is a regular submit button with an action name (optional) and handler (a callable). It mainly handles step transitions but can also run custom logic tied to your form data.

The action name identifies the operation to perform and doesn’t need to match the button name. There are 4 built-in actions:

reset: sends the FormFlow back to the initial state (will depend on the initial data),
next: moves to the next step,
back: goes to a previous step,
finish: same as reset but also marks the FormFlow as finished.

You can combine these actions with other options for different purposes, for example:

A skip button using the next action and clear_submission moves the FormFlow forward while clearing the current step,
A back_to button using the back action and a view value (step name) returns to a specific previous step,

Built-in actions have a default handler in the FormFlow class, but you can define custom action/handler for specific needs. Custom handlers use the following signature:

function (UserSignUp $data, ActionButtonInterface $button, FormFlowInterface $flow) {
    // $data is the current data bound to the form the button belongs to,
    // $button is the action button clicked, $button->getAction(), $button->getViewData(), ...
    // $flow is the FormFlow that the button belongs to, $flow->moveNext(), $flow->moveBack(), ...
}

Important

By default, the action runs when the form is submitted, passes validation, and just before the next step form is created during $flow->getStepForm(). To control it manually, call $flow->handleAction() after $flow->handleRequest($request) where needed.

FormFlowActionType also comes with other 2 options:

clear_submission: If true, it clears the submitted data. This is especially handy for skip and back actions, or anytime you want to empty the current step form submission.
include_if: null if you want to include the button in all steps (default), an array of steps, or a callable that’s triggered during form creation to decide whether the action button should be included in the current step form. This callable will receive the FormFlowCursor instance as argument.

`FormFlowCursor`

This immutable value object holds all defined steps and the current one. You can access it via $flow->getCursor() or as a FormView variable in Twig to build a nice step progress UI.

`FormFlowNavigatorType`

The built-in FormFlowNavigatorType provides 3 default action buttons: back, next, and finish. You can customize or add more if needed. Here’s an example of adding a “skip” button to the professional step we defined earlier:

class UserSignUpNavigatorType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder->add('skip', FormFlowActionType::class, [
            'action' => 'next',
            'clear_submission' => true,
            'include_if' => ['professional'], // the step names where the button will appear
        ]);
    }

    public function getParent(): string
    {
        return FormFlowNavigatorType::class;
    }
}

Then use UserSignUpNavigatorType instead.

Data Storage

FormFlow handles state across steps, so the final data includes everything collected throughout the flow. By default, it uses SessionDataStorage (unless you’ve configured a custom one). For testing, InMemoryDataStorage is also available.

You can also create custom data storage by implementing DataStorageInterface and passing it through the data_storage option in FormFlowType.

Step Accessor

The step_accessor option lets you control how the current step is read from or written to your data. By default, PropertyPathStepAccessor handles this using the form’s bound data and PropertyAccess component. If the step name is managed externally (e.g., by a workflow), you can create a custom StepAccessorInterface adapter and pass it through this option in FormFlowType.

Validation

FormFlow relies on the standard validation system but introduces a useful convention: it sets the current step as an active validation group. This allows step-specific validation rules without extra setup:

final class FormFlowType extends AbstractFlowType  
{
    public function configureOptions(OptionsResolver $resolver): void  
    {
        // ...

        $resolver->setDefault('validation_groups', function (FormFlowInterface $flow) {  
            return ['Default', $flow->getCursor()->getCurrentStep()];  
        });
    }
}

Allowing you to configure the validation groups in your constraints, like this:

class UserSignUp
{
    public function __construct(
        #[Valid(groups: ['personal'])]
        public Personal $personal  = new Personal(),

        #[Valid(groups: ['professional'])]
        public Professional $professional = new Professional(),

        #[Valid(groups: ['account'])]
        public Account $account = new Account(),

        public string $currentStep = 'personal',
    ) {
    }
}

There’s a lot more to share about this feature, so feel free to ask if anything isn’t clear.

Cheers!

Demo preview:

94noni

early raw reviews :)

94noni · Apr 14, 2025

src/Symfony/Component/Form/Extension/Core/Type/FormFlowNavigatorType.php

+{
+    public function buildForm(FormBuilderInterface $builder, array $options): void
+    {
+        $builder->add('back', FormFlowActionType::class, [


what bout "previous" ? generally it goes with "next"
or rename other "forward" ?

I don’t have a strong opinion on that. I personally prefer the shorter version, and users can change it using the label option anyway. Let’s see what others think.

src/Symfony/Bundle/FrameworkBundle/Resources/config/form.php

94noni · Apr 14, 2025

src/Symfony/Component/Form/Extension/Core/Type/FormFlowType.php

+use Symfony\Component\PropertyAccess\PropertyPathInterface;
+
+/**
+ * A multistep form.


a question about naming:

you describe this as a form multistep
but the class is named form flow

its feels weird at first read

They mean the same to me... I’m just phrasing it differently to make the idea clearer. What is the weird part?

...ony/Component/Form/Extension/HttpFoundation/Type/FormFlowTypeSessionDataStorageExtension.php

94noni · Apr 14, 2025

src/Symfony/Component/Form/Extension/Core/Type/FormFlowActionType.php

+            ->default(null)
+            ->allowedTypes('null', 'callable');
+
+        $resolver->define('include_if')


I've improved it a bit more for better DX, so now we have three allowed values:

null if you want to include the button in all defined steps,

an array with the names of the steps where the button will be included, (most used)

a callable for more advanced inclusion logic.

src/Symfony/Component/Form/Extension/Core/Type/FormFlowNavigatorType.php

connorhu · Apr 14, 2025

Great idea! I've looked at the previous PR and could use it! One question came up: how can I jump back to a specific step without having to press the back button many times?
May the answer is can't by default. I solved this issue by keeping track of which valid step we are at and the url contains the step number (1..n), so I can generate a url for the previous steps, but I dont allow to go to not-yet-valid next steps.
I think I can see the points where I need to customize to achieve this.

yceruto · Apr 14, 2025

how can I jump back to a specific step without having to press the back button many times?

Hey! take a look at the testMoveBackToStep() test, it covers this case. It's possible via submit operation or manually using $flow->moveBack('step') directly.

RafaelKr · Apr 15, 2025

Hey @yceruto, awesome to see this may become a native part of Symfony Forms!

I just had a quick look at the implementation and didn't find anything about UploadedFile (yet).
This was one of the big challenges we had to solve with CraueFormFlowBundle in combination with https://rekalogika.dev/file-bundle/file-upload-filepond, especially to make restore work (when going back to show the previously submitted files) and then to handle those if the step is submitted again.

It would be very helpful to have a default way the FormFlow can handle file uploads, but also to have some interface to interact with the full lifecycle of uploaded files, e.g. to decide where and how to store them, how to reference them inside form data, etc.

I think the lifecycle consists of the following steps:

Initial upload. I think it would be best to already store the file(s) to a temporary location on the filesystem and just work with references to them.
In our case we use the Rekalogika file bundle to directly reference Files with our Doctrine Media Entity (see https://rekalogika.dev/file-bundle/doctrine-entity and https://rekalogika.dev/file-bundle/working-with-entities) and then store the Media entity inside our Form Data.
"Restore" already uploaded file(s) when the user goes back to a step with a file upload field.
Handle resubmit, especially for file inputs with multiple attribute. If the same step is submitted more then once, the following cases need to be handled:

keep unchanged files
delete files which were removed
create newly uploaded files

Final submission. Maybe we want to move files from a temporary location to persistent storage.

Maybe file uploads are not as important for an initial implementation, but it's definitely a use case which should be thought about.

Feel free to ping me if you have any questions. Maybe I could even build a minimal demo of the current implementation we use in our project and share it with you.

stof · Apr 15, 2025

I think it would be best to already store the file(s) to a temporary location on the filesystem and just work with references to them.

this would be incompatible with apps using a load balancer with several servers, as there is no guarantee that the next request goes to the same server behind the load balancer. Such case require storing uploads in a shared storage (for instance using a S3 bucket or similar storage)

RafaelKr · Apr 15, 2025

I think it would be best to already store the file(s) to a temporary location on the filesystem and just work with references to them.

this would be incompatible with apps using a load balancer with several servers, as there is no guarantee that the next request goes to the same server behind the load balancer. Such case require storing uploads in a shared storage (for instance using a S3 bucket or similar storage)

You're very right, thanks for pointing this out. So it's especially important to have the possibility of handling those different cases. Maybe a FileUploadHandlerInterface could be introduced. I don't really like the default handling of CraueFormFlowBundle (storing files as base64 to the session), but also can't come up with a better approach which would be compatible with horizontal scaling.

yceruto · Apr 15, 2025

I haven’t checked the file upload yet because I knew it would be a complicated topic, but I think using a custom action button (as explained above) will give you the flexibility to do custom things on your own.

One option is to create your own next action button with a dedicated handler where file uploads can be managed. Then, you can keep track of the uploaded files by saving the references in the DTO, which is preserved between steps.

Imagine you have a documents step defined for files uploading. In your navigator form, you can define this new action:

$builder->add('upload', FormFlowActionType::class, [
    'include_if' => ['documents'], // the steps where this button will appear
    'handler' => function (MyDto $data, ActionButtonInterface $button, FormFlowInterface $flow) {
        // handle files uploading here ... store them somewhere ... create references ...

        // $data->uploadedFiles = ... save references if we go back ...

        $flow->moveNext();
    },
]);

So, it’s up to you where to store the files, how to reference them in the DTO, and how to render them again if the user goes back to this step, just by looking into $data->uploadedFiles.

yceruto · Apr 15, 2025

Think of FormFlow action buttons like mini-controllers with a focused job. The main controller handles the shared logic across all steps, while each action handler takes care of custom operations.

You can even use them for inter-step operations (like in the demo preview, where I showed how to add or remove skill items from a CollectionType). In those cases, the step stays the same, but the bound data gets updated, and the form is rebuilt when $flow->getStepForm() is called again, now with new data and form updated.

This part feels a bit like magic, but it’s a helpful one given how complex multistep forms can be.

yceruto added the Form label Apr 13, 2025

yceruto requested a review from xabbuh as a code owner April 13, 2025 23:19

carsonbot added Status: Needs Review Feature labels Apr 13, 2025

carsonbot added this to the 7.3 milestone Apr 13, 2025

symfony deleted a comment from carsonbot Apr 13, 2025

yceruto force-pushed the formflow branch from 8d9bc59 to b6b909c Compare April 13, 2025 23:23

yceruto marked this pull request as draft April 13, 2025 23:25

yceruto force-pushed the formflow branch from b6b909c to 7da47cf Compare April 13, 2025 23:26

yceruto mentioned this pull request Apr 13, 2025

[Form] Add MultiStepType #59548

Closed

94noni reviewed Apr 14, 2025

View reviewed changes

yceruto force-pushed the formflow branch 2 times, most recently from 2f81d34 to cdac9e2 Compare April 15, 2025 00:16

kbond mentioned this pull request Apr 15, 2025

[LiveComponent] Adds MultiStep Form Feature symfony/ux#2433

Draft

3 tasks

yceruto force-pushed the formflow branch 9 times, most recently from 1ef730f to 4df48d8 Compare April 24, 2025 14:20

yceruto force-pushed the formflow branch 3 times, most recently from 7996e61 to d8cbb5b Compare April 29, 2025 22:33

yceruto force-pushed the formflow branch 6 times, most recently from 689f674 to 734a122 Compare May 9, 2025 04:49

Add FormFlow component

0e181d8

yceruto force-pushed the formflow branch from 734a122 to 0e181d8 Compare May 13, 2025 15:33

yceruto changed the title ~~[Form] Add FormFlow component for multistep forms management~~ [Form] Add FormFlow for multistep forms management May 21, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Form] Add `FormFlow` for multistep forms management #60212

[Form] Add `FormFlow` for multistep forms management #60212

yceruto commented Apr 13, 2025 •

edited

Loading

94noni left a comment

94noni Apr 14, 2025

yceruto Apr 15, 2025

94noni Apr 14, 2025

yceruto Apr 15, 2025

94noni Apr 14, 2025

yceruto Apr 24, 2025 •

edited

Loading

connorhu commented Apr 14, 2025

yceruto commented Apr 14, 2025

RafaelKr commented Apr 15, 2025

stof commented Apr 15, 2025

RafaelKr commented Apr 15, 2025

yceruto commented Apr 15, 2025 •

edited

Loading

yceruto commented Apr 15, 2025

Search code, repositories, users, issues, pull requests...

[Form] Add FormFlow for multistep forms management #60212

Are you sure you want to change the base?

[Form] Add FormFlow for multistep forms management #60212

Conversation

yceruto commented Apr 13, 2025 • edited Loading

FormFlow

AbstractFlowType

Type Extension

Controller

FormFlowActionType

FormFlowCursor

FormFlowNavigatorType

Data Storage

Step Accessor

Validation

94noni left a comment

Choose a reason for hiding this comment

94noni Apr 14, 2025

Choose a reason for hiding this comment

yceruto Apr 15, 2025

Choose a reason for hiding this comment

94noni Apr 14, 2025

Choose a reason for hiding this comment

yceruto Apr 15, 2025

Choose a reason for hiding this comment

94noni Apr 14, 2025

Choose a reason for hiding this comment

yceruto Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

connorhu commented Apr 14, 2025

yceruto commented Apr 14, 2025

RafaelKr commented Apr 15, 2025

stof commented Apr 15, 2025

RafaelKr commented Apr 15, 2025

yceruto commented Apr 15, 2025 • edited Loading

yceruto commented Apr 15, 2025

[Form] Add `FormFlow` for multistep forms management #60212

[Form] Add `FormFlow` for multistep forms management #60212

yceruto commented Apr 13, 2025 •

edited

Loading

`AbstractFlowType`

`FormFlowActionType`

`FormFlowCursor`

`FormFlowNavigatorType`

yceruto Apr 24, 2025 •

edited

Loading

yceruto commented Apr 15, 2025 •

edited

Loading