Formflow Demo Bundle Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies:

   composer require craue/formflow-demo-bundle craue/formflow-bundle
   

   Ensure versions align (e.g., 3.6.x for both).

2. Enable Bundles: Add to config/bundles.php:

   return [
       Craue\FormFlowBundle\CraueFormFlowBundle::class => ['all' => true],
       Craue\FormFlowDemoBundle\CraueFormFlowDemoBundle::class => ['all' => true],
   ];
   

3. Add Routes: Include in config/routes.yaml:

   CraueFormFlowDemoBundle:
     resource: '@CraueFormFlowDemoBundle/Controller/'
     type: annotation
   

4. First Use Case: Access http://your-app/_demo to explore the live demo. Study the src/Craue/FormFlowDemoBundle/Controller/DemoController.php to see how forms are structured with FormFlow.

Implementation Patterns

Core Workflows

1. Form Flow Definition: Define multi-step forms using YAML (e.g., config/formflows/demo.yaml):

   demo_flow:
     type:      Craue\FormFlowBundle\FormFlow\StandardFormFlow
     options:   { ... }
     steps:
       - { type: Craue\FormFlowBundle\FormFlow\Step\Step, form: 'app.form.step1' }
       - { type: Craue\FormFlowBundle\FormFlow\Step\Step, form: 'app.form.step2' }
   

2. Form Type Integration: Extend AbstractType and annotate with @FormFlow:

   use Craue\FormFlowBundle\Annotation\FormFlow;
   
   #[FormFlow('demo_flow')]
   class Step1Type extends AbstractType { ... }
   

3. Controller Integration: Use FormFlowBuilder to instantiate flows:

   use Craue\FormFlowBundle\FormFlow\FormFlowBuilder;
   
   public function demoAction(FormFlowBuilder $builder) {
       $flow = $builder->get('demo_flow');
       $form = $flow->createForm();
       // Handle submission...
   }
   

4. Step Navigation: Leverage FormFlow events (PRE_SUBMIT, POST_SUBMIT) to customize transitions:

   $flow->addEventListener(FormFlowEvents::PRE_SUBMIT, function(FormFlowEvent $event) {
       if ($event->getStep()->getName() === 'step2') {
           $event->setNextStep('step3');
       }
   });
   

5. Data Persistence: Use FormFlowStorage to save progress (e.g., Doctrine):

   # config/packages/craue_form_flow.yaml
   craue_form_flow:
       storage:
           type: doctrine
           entity: App\Entity\FormFlowStorage
   

Integration Tips

• Symfony Forms: Reuse existing FormType classes with @FormFlow.
• Validation: Centralize validation in FormFlow steps or use Symfony’s Validator.
• Twig: Access flow data via formflow Twig extension:

  {{ form_start(formflow.form) }}
  {{ form_row(formflow.form) }}
  {{ form_end(formflow.form) }}
  

Gotchas and Tips

Pitfalls

1. Version Mismatch:

   • Ensure craue/formflow-bundle and craue/formflow-demo-bundle versions match (e.g., 3.6.x).
   • Debug: Check composer.json for conflicting versions.

2. Route Conflicts:

   • The demo routes (/_demo) may clash with existing routes. Prefix or rename in routes.yaml.

3. Storage Configuration:

   • If using Doctrine storage, ensure the FormFlowStorage entity is properly mapped:

     #[ORM\Entity]
     class FormFlowStorage { ... }
     

   • Debug: Clear cache (php bin/console cache:clear) if storage issues persist.

4. Event Listener Overrides:

   • Events like FormFlowEvents::PRE_SUBMIT may not trigger if the step is misconfigured. Verify step names in YAML match controller logic.

Debugging

• Log Flow Execution: Enable debug mode and log events:

  # config/packages/dev/monolog.yaml
  handlers:
      formflow:
          type: stream
          path: "%kernel.logs_dir%/formflow.log"
          level: debug
  

  Check logs for step transitions and errors.

• Dump Flow Data: Use Symfony’s dump() in controllers to inspect flow state:

  dump($flow->getCurrentStep()->getName());
  

Extension Points

1. Custom Steps: Extend AbstractStep to create reusable step types:

   class CustomStep extends AbstractStep {
       public function execute(FormFlowEvent $event) { ... }
   }
   

2. Dynamic Flows: Build flows programmatically:

   $flow = new StandardFormFlow();
   $flow->addStep(new Step('dynamic_step', new DynamicFormType()));
   

3. Twig Extensions: Override Twig templates for custom rendering:

   {# Override default template #}
   {% extends 'CraueFormFlowBundle:FormFlow:step.html.twig' %}
   

4. Validation Groups: Use Symfony’s validation groups per step:

   # config/formflows/demo.yaml
   steps:
       - { form: 'app.form.step1', validation_groups: ['step1'] }