feature #40690 [Form] Add support for sorting fields (yceruto)

This PR was squashed before being merged into the 5.3-dev branch.

Discussion
----------

[Form] Add support for sorting fields

| Q             | A
| ------------- | ---
| Branch?       | 5.x
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | Fix #5827
| License       | MIT
| Doc PR        | TODO

This PR adds a new `priority` option used later to sort all fields in order of importance instead of simply numerical order, i.e. fields with higher priority will be rendered first, fields with lower priority will be rendered last. The default priority would be "0" for all fields. Fields with equal priority will keep the original order (stable sorting).

History of previous proposals and discussions: #3452, #4254, #5827, #6111, #11241

This kind of feature has been abandoned in the past because complex proposals, and somehow rejected because ideally we should do the sorting at the view level ([customizing form](https://symfony.com/doc/current/form/form_customization.html) themes or layout templates) and it's true for most cases (the simple ones I think) but the fact is that it's often quite complex to accomplish that way, mainly for [dynamic forms](https://symfony.com/doc/current/form/dynamic_form_modification.html).

Let's focus the following analysis on explaining *why* and *when* the `priority` option could save us a lot of time, getting rid of cumbersome workarounds with templates to change the rendering order *only*.

---

A common example could be the building of a multi-steps form with a convenient type hierarchy and including fields dynamically based on the data. Let's take this sample:

![image](https://user-images.githubusercontent.com/2028198/113465635-a5a81180-9403-11eb-839f-3a32d5f84f47.png)

```php
class WorkflowType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        // get current enabled transitions from the workflow definition...

        foreach ($enabledTransitions as $transitionName) {
            $builder->add($transitionName, SubmitType::class, ['attr' => ['value' => $transitionName]]);
        }
    }
}

class PersonRegistrationType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('firstName')
            ->add('lastName');

        $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
            $person = $event->getData();

            if ($person->isLegalType()) {
                $event->getForm()->add('company');
            }
        });
    }

    public function getParent()
    {
        return WorkflowType::class;
    }
}
```
These classes model the required form. However, according to the form building process and taken into account that the underlaying person data was set with "legal" type (from the previous step), this will be the rendering result:
```html
<button type="submit" name="form[register]" value="register">Register</button> {# wrong place #}
<input name="form[first_name]">
<input name="form[last_name]">
<input name="form[company]">  {# wrong place #}
```
Now, taking the view customization path to fix the order, you likely will face some problems regarding to:
 - How do I render the dynamic submit buttons at the bottom?
 - How can the specific form fields be rendered in the correct order if they vary from step to step? (being it a generic template)
 - if you solve the previous questions, you will also need to check if the company field is defined or not before rendering it in the right order.

There could be more and different problems depending on the context and you can find workarounds using the block prefixes system to customize each step block theme, but to me it's enough to think about other alternatives.

On the other side, using the `priority` option, the solution is quite easy. Setting the right priority value will guarantee the right rendering order:
```php
// ...
$builder->add($transitionName, SubmitType::class, ['priority' => -1, // ...]);

// ...
$event->getForm()->add('company', null, ['priority' => 1]);
```
That's ! There is no need to customize templates at all when you only need to change the fields order.

This way, these fields are being pre-defined in the order they will be rendered at view level. This sorting process will take place on `$form->createView()` method, just after `buildView()` and before `finishView()` calls.

Could we reconsider the usefulness of this feature? please.

Cheers!

Commits
-------

62650bbdc7 [Form] Add support for sorting fields

Author: Nyholm

CHANGELOG.md

@@ -15,6 +15,7 @@ CHANGELOG
  * Added a `choice_translation_parameters` option to `ChoiceType`
  * Add `UuidType` and `UlidType`
  * Dependency on `symfony/intl` was removed. Install `symfony/intl` if you are using `LocaleType`, `CountryType`, `CurrencyType`, `LanguageType` or `TimezoneType`.
+ * Add `priority` option to `BaseType` and sorting view fields
 
 5.2.0
 -----

Extension/Core/Type/BaseType.php

@@ -107,6 +107,7 @@ public function buildView(FormView $view, FormInterface $form, array $options)
             'translation_domain' => $translationDomain,
             'label_translation_parameters' => $labelTranslationParameters,
             'attr_translation_parameters' => $attrTranslationParameters,
+            'priority' => $options['priority'],
             // Using the block name here speeds up performance in collection
             // forms, where each entry has the same full block name.
             // Including the type is important too, because if rows of a
@@ -135,11 +136,15 @@ public function configureOptions(OptionsResolver $resolver)
             'attr' => [],
             'translation_domain' => null,
             'auto_initialize' => true,
+            'priority' => 0,
         ]);
 
         $resolver->setAllowedTypes('block_prefix', ['null', 'string']);
         $resolver->setAllowedTypes('attr', 'array');
         $resolver->setAllowedTypes('row_attr', 'array');
         $resolver->setAllowedTypes('label_html', 'bool');
+        $resolver->setAllowedTypes('priority', 'int');
+
+        $resolver->setInfo('priority', 'The form rendering priority (higher priorities will be rendered first)');
     }
 }

Form.php

@@ -1044,11 +1044,38 @@ public function createView(FormView $parent = null)
             $view->children[$name] = $child->createView($view);
         }
 
+        $this->sort($view->children);
+
         $type->finishView($view, $this, $options);
 
         return $view;
     }
 
+    /**
+     * Sorts view fields based on their priority value.
+     */
+    private function sort(array &$children): void
+    {
+        $c = [];
+        $i = 0;
+        $needsSorting = false;
+        foreach ($children as $name => $child) {
+            $c[$name] = ['p' => $child->vars['priority'] ?? 0, 'i' => $i++];
+
+            if (0 !== $c[$name]['p']) {
+                $needsSorting = true;
+            }
+        }
+
+        if (!$needsSorting) {
+            return;
+        }
+
+        uksort($children, static function ($a, $b) use ($c): int {
+            return [$c[$b]['p'], $c[$a]['i']] <=> [$c[$a]['p'], $c[$b]['i']];
+        });
+    }
+
     /**
      * Normalizes the underlying data if a model transformer is set.
      *

Tests/Extension/Core/Type/FormTypeTest.php

@@ -836,6 +836,29 @@ public function testFormAttrAsStringWithNoId()
         $this->assertSame($view->vars['id'], $view['child1']->vars['attr']['form']);
         $this->assertSame($view->vars['id'], $view['child2']->vars['attr']['form']);
     }
+
+    public function testSortingViewChildrenBasedOnPriorityOption()
+    {
+        $view = $this->factory->createNamedBuilder('parent', self::TESTED_TYPE)
+            ->add('child1', null, ['priority' => -1])
+            ->add('child2')
+            ->add('child3', null, ['priority' => -1])
+            ->add('child4')
+            ->add('child5', null, ['priority' => 1])
+            ->add('child6')
+            ->getForm()
+            ->createView();
+
+        $expected = [
+            'child5',
+            'child2',
+            'child4',
+            'child6',
+            'child1',
+            'child3',
+        ];
+        $this->assertSame($expected, array_keys($view->children));
+    }
 }
 
 class Money

Tests/Fixtures/Descriptor/resolved_form_type_1.json

@@ -57,6 +57,7 @@
                 "mapped",
                 "method",
                 "post_max_size_message",
+                "priority",
                 "property_path",
                 "required",
                 "row_attr",

Tests/Fixtures/Descriptor/resolved_form_type_1.txt

@@ -34,6 +34,7 @@ Symfony\Component\Form\Extension\Core\Type\ChoiceType (Block prefix: "choice")
                                                        mapped                                                
                                                        method                                                
                                                        post_max_size_message                                 
+                                                       priority                                              
                                                        property_path                                         
                                                        required                                              
                                                        row_attr                                              

Tests/Fixtures/Descriptor/resolved_form_type_2.json

@@ -35,6 +35,7 @@
             "mapped",
             "method",
             "post_max_size_message",
+            "priority",
             "property_path",
             "required",
             "row_attr",

Tests/Fixtures/Descriptor/resolved_form_type_2.txt

@@ -37,6 +37,7 @@ Symfony\Component\Form\Extension\Core\Type\FormType (Block prefix: "form")
   mapped                        
   method                        
   post_max_size_message         
+  priority                      
   property_path                 
   required                      
   row_attr