Formflow Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require asmitta-01/formflow-bundle
   

   Enable in config/bundles.php:

   Asmitta\FormFlowBundle\AsmittaFormFlowBundle::class => ['all' => true],
   

2. Create a Flow Class Extend FormFlow and define steps in loadStepsConfig():

   // src/Form/UserFlow.php
   class UserFlow extends FormFlow {
       protected function loadStepsConfig(): array {
           return [
               ['label' => 'Step 1', 'form_type' => UserType::class],
               ['label' => 'Step 2', 'form_type' => UserType::class],
           ];
       }
   }
   

3. Register as a Service

   # config/services.yaml
   services:
       App\Form\UserFlow:
           parent: asmitta.form.flow
   

4. Controller Integration Inject the flow and handle steps:

   public function handleFlow(UserFlow $flow) {
       $user = new User();
       $flow->bind($user);
       $form = $flow->createForm();
   
       if ($flow->isValid($form)) {
           $flow->saveCurrentStepData($form);
           if ($flow->nextStep()) {
               $form = $flow->createForm(); // Next step
           } else {
               $flow->reset(); // Done
           }
       }
       return $this->render('template.html.twig', ['form' => $form->createView()]);
   }
   

5. Template Use the provided buttons template:

   {% include '@AsmittaFormFlow/FormFlow/buttons.html.twig' %}
   

Implementation Patterns

Workflow: Single Form Type Approach

1. Conditional Field Loading Use flow_step option in buildForm() to dynamically add fields per step:

   public function buildForm(FormBuilderInterface $builder, array $options) {
       switch ($options['flow_step']) {
           case 1: $builder->add('email'); break;
           case 2: $builder->add('address'); break;
       }
   }
   

2. Data Persistence Save step data to session:

   $flow->saveCurrentStepData($form);
   $stepData = $flow->getStepData(1); // Retrieve later
   

3. Validation & Navigation Validate before proceeding:

   if ($flow->isValid($form)) {
       if ($flow->nextStep()) {
           $form = $flow->createForm(); // Auto-refreshes step
       }
   }
   

Integration Tips

• Symfony UX Turbo: Disable Turbo for the flow view or return HTTP_UNPROCESSABLE_ENTITY:

  return $this->render(..., [], new Response(422));
  

• Unmapped Fields: Manually map data from getStepData():

  $user->setFirstName($flow->getStepData(1)['first_name']);
  

• Custom Buttons: Override labels/classes in Twig:

  {% include '@AsmittaFormFlow/FormFlow/buttons.html.twig' with {
      asmitta_formflow_button_class_next: 'btn btn-primary'
  } %}
  

Gotchas and Tips

Pitfalls

1. Session Dependence

   • Data is stored in the session. Clear it manually with $flow->reset() after completion.
   • Fix: Always call reset() to avoid stale data.

2. Turbo Conflicts

   • Symfony Turbo may cache steps. Disable it or return 422 as shown above.

3. Field Mapping

   • Unmapped fields (e.g., mapped: false) require manual handling via getStepData().

4. Service Registration

   • Forgetting to set parent: asmitta.form.flow in services.yaml will break DI.

Debugging Tips

• Check Step Data: Use $flow->getStepData($step) to inspect saved values.
• Validate Config: Ensure loadStepsConfig() returns an array of steps with label and form_type.
• Clear Session: If stuck, manually clear the session or restart the browser.

Extension Points

1. Custom Flow Logic Override FormFlow methods like nextStep() or isValid() for custom behavior.

2. Event Listeners Dispatch events (e.g., flow.step.change) via Symfony’s event system for cross-cutting concerns.

3. Template Overrides Extend the default buttons template (@AsmittaFormFlow/FormFlow/buttons.html.twig) in your theme.

4. Validation Groups Use validation_groups in UserType to validate only relevant fields per step:

   $builder->add('email', ..., ['validation_groups' => ['step1']]);