Ordered Form Laravel Package

Getting Started

Minimal Setup in Laravel

To integrate egeloen/ordered-form into a Laravel project, follow these steps:

1. Install the Package

   composer require egeloen/ordered-form
   

2. Extend Laravel’s Form Builder Create a service provider to integrate the ordered form functionality with Laravel’s form builder. Add this to config/app.php under providers:

   Egeloen\OrderedForm\OrderedFormServiceProvider::class,
   

3. Publish Configuration (if needed) Run:

   php artisan vendor:publish --provider="Egeloen\OrderedForm\OrderedFormServiceProvider"
   

4. First Use Case: Basic Field Ordering In a form builder, use the position option to control field order:

   use Egeloen\OrderedForm\OrderedFormBuilder;
   
   $form = OrderedFormBuilder::create()
       ->add('name', 'text', ['position' => 'first'])
       ->add('email', 'email')
       ->add('bio', 'textarea', ['position' => 'last'])
       ->getForm();
   

Implementation Patterns

Workflow: Dynamic Form Ordering

1. Form Definition Define forms with explicit position options:

   $builder->add('priority', 'choice', ['position' => ['before' => 'description']]);
   $builder->add('description', 'textarea');
   

2. Nested Forms The package supports nested forms. Ordering works recursively:

   $builder->add('address', OrderedFormBuilder::create()
       ->add('street', 'text', ['position' => 'first'])
       ->add('city', 'text')
       ->getForm()
   );
   

3. Custom Order Logic Implement FormOrdererInterface for complex rules:

   use Ivory\OrderedForm\Orderer\FormOrdererInterface;
   use Symfony\Component\Form\FormInterface;
   
   class PriorityOrderer implements FormOrdererInterface
   {
       public function order(FormInterface $form)
       {
           $children = $form->all();
           usort($children, function ($a, $b) {
               return $a->getConfig()->getOption('priority', 0) <=> $b->getConfig()->getOption('priority', 0);
           });
           return array_keys($children);
       }
   }
   

   Register it in your service provider:

   $this->app->singleton('ordered_form.orderer', function () {
       return new PriorityOrderer();
   });
   

4. Integration with Laravel Collectives If using laravelcollective/html, extend the HtmlFormBuilder:

   class OrderedHtmlFormBuilder extends OrderedFormBuilder
   {
       // Override methods to integrate with Collective's helpers
   }
   

Gotchas and Tips

Pitfalls

1. Circular Dependencies Avoid before/after references that create loops (e.g., A before B, B before A). The orderer will throw an exception.

2. Dynamic Forms If fields are added dynamically (e.g., via JavaScript), ensure the position option is set before rendering. The package does not reorder forms after initial build.

3. Symfony Form Type Conflicts If using custom form types, ensure they extend AbstractType and are registered with the form factory after the OrderedExtension.

4. Laravel Blade Caching Cached Blade views may not reflect form order changes. Clear the cache after modifying form definitions:

   php artisan view:clear
   

Debugging

• Inspect Ordered Fields Dump the ordered children names for debugging:

  $view = $form->createView();
  $orderedChildren = $form->getConfig()->getOption('ordered_children');
  dd($orderedChildren);
  

• Check for Missing Options Ensure position is a valid option ('first', 'last', or an array with before/after). Invalid options are ignored silently.

Extension Points

1. Custom Orderers Override the default orderer by binding a new instance in Laravel’s container:

   $this->app->bind('ordered_form.orderer', function () {
       return new CustomOrderer();
   });
   

2. Form Events Listen to FORM_POST_SET_DATA or FORM_POST_SUBMIT to adjust ordering dynamically:

   $builder->addEventListener(FormEvents::POST_SET_DATA, function (FormEvent $event) {
       $event->getForm()->getConfig()->setOption('ordered_children', ['custom_order']);
   });
   

3. Validation Rules Combine with Laravel’s validation to enforce ordering rules:

   $request->validate([
       'field_order' => 'required|array',
       'field_order.*' => 'exists:fields,name'
   ]);
   

Performance

• Avoid Overly Complex Ordering The orderer processes fields in O(n log n) time for custom logic. For large forms (>50 fields), prefer simple first/last or before/after rules.

• Cache Ordered Forms If forms are static, cache the ordered view:

   $view = $form->createView();
   Cache::put('form_view', $view, now()->addHours(1));