Ordered Form Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require becklyn/ordered-form-bundle
   

   Register the bundle in config/bundles.php (Laravel 5.5+ auto-discovers it).

2. First Use Case: Add a form field with a position option in your FormType:

   $builder->add('priorityField', TextType::class, [
       'position' => 'first' // or 'last', 42, ['before' => 'otherField']
   ]);
   

3. Where to Look First:

   • Check the README for supported position values.
   • Inspect the bundle’s FormTypeExtension (src/DependencyInjection/BecklynOrderedFormExtension.php) for internals.

Implementation Patterns

Common Workflows

1. Dynamic Positioning: Use integer positions for programmatic control (e.g., fetch from DB):

   $builder->add('dynamicField', TextType::class, [
       'position' => $item->sort_order // e.g., 10, 20, 30
   ]);
   

2. Relative Positioning: Anchor fields to others (useful for grouped fields):

   $builder->add('description', TextareaType::class, [
       'position' => ['after' => 'title']
   ]);
   

3. Conditional Positioning: Override positions in runtime (e.g., admin vs. user forms):

   $position = auth()->user()->is_admin ? 'first' : 10;
   $builder->add('adminOnlyField', ..., ['position' => $position]);
   

Integration Tips

• Form Themes: Extend the bundle’s form_div_layout.html.twig to customize rendering.
• Validation: Validate position values in your FormType:

  $builder->add('field', ..., [
      'constraints' => [new Callback([$this, 'validatePosition'])],
  ]);
  

• Laravel-Specific: Use FormBuilder in controllers or services:

  $form = app('form.factory')->createBuilder(YourFormType::class, $data);
  

Gotchas and Tips

Pitfalls

1. Conflicting Positions:

   • Multiple "first" or "last" fields may not render as expected. Use integers for precision.
   • Debug with dump($form->getConfig()->getFormType()->getName()) to inspect the final order.

2. Circular Dependencies: Avoid before/after loops (e.g., A → B → A). The bundle silently ignores them.

3. Non-Integer Positions: Strings like "first" are converted to 0 internally, but may behave unexpectedly in complex forms.

Debugging

• Inspect Order: Override the bundle’s getBlockPrefix() in your theme to log field positions:

  {{ dump(form.vars.block_prefix) }}
  

• Clear Cache: After changes, run:

  php artisan cache:clear
  

Extension Points

1. Custom Sorting: Override the OrderedFormTypeExtension to add logic (e.g., ignore certain fields):

   // config/packages/becklyn_ordered_form.yaml
   becklyn_ordered_form:
       ignored_fields: ['_token', 'submit']
   

2. Event Listeners: Hook into form.pre_set_data to adjust positions dynamically:

   $form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $event->getForm()->get('field')->getConfig()->setOption('position', 'last');
   });
   

3. Performance: For large forms (>50 fields), pre-sort arrays manually to reduce bundle overhead:

   usort($fields, fn($a, $b) => $a['position'] <=> $b['position']);