feature #14241 [Form] Add new way of mapping form data using callback functions (yceruto)

This PR was merged into the master branch.

Discussion
----------

[Form] Add new way of mapping form data using callback functions

Documenting new feature symfony/symfony#37968

I don't think we need to cover all possible situations; the current example covers 3 of them, except the second one, but it seems enough for me, wdyt?

> [...] you'll have to write your own data mapper in the following situations:
>* When the property path differs for reading and writing
>* When several form fields are mapped to a single method
>* When you need to read data based on the model's state
>* When the mapping of the model depends on the submitted form data
...

By the way, the second situation "when several form fields are mapped to a single method" can be achieved this way:
```php
$builder
    ->add('foo', TextType::class, [
        'setter' => function (Foobar $foobar, string $value) use (&$foo) {
            $foo = $value;
        },
    ])
    ->add('bar', TextType::class, [
        'setter' => function (Foobar $foobar, string $bar) use (&$foo) {
            $foobar->doSomething($foo, $bar);
        },
    ])
;
```
Since the data mapper will follow the same order in which the fields were defined, we can trust that the foo "setter" will be executed first and so the second "setter" will have the right value at the moment this function `$foobar->doSomething($foo, $bar)` is being executed.

---

ping @alcaeus :)

Commits
-------

53fb3c7 Add new way of mapping form data

Author: wouterj

form/data_mappers.rst

@@ -189,6 +189,45 @@ method::
 Cool! When using the ``ColorType`` form, the custom data mapper methods will
 create a new ``Color`` object now.
 
+Mapping Form Fields Using Callbacks
+-----------------------------------
+
+Conveniently, you can also map data from and into a form field by using the
+``getter`` and ``setter`` options. For example, suppose you have a form with some
+fields and only one of them needs to be mapped in some special way or you only
+need to change how it's written into the underlying object. In that case, register
+a PHP callable that is able to write or read to/from that specific object::
+
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        // ...
+
+        $builder->add('state', ChoiceType::class, [
+            'choices' => [
+                'active' => true,
+                'paused' => false,
+            ],
+            'getter' => function (Task $task, FormInterface $form): bool {
+                return !$task->isCancelled() && !$task->isPaused();
+            },
+            'setter' => function (Task &$task, bool $state, FormInterface $form): void {
+                if ($state) {
+                    $task->activate();
+                } else {
+                    $task->pause();
+                }
+            },
+        ]);
+    }
+
+If available, these options have priority over the property path accessor and
+the default data mapper will still use the :doc:`PropertyAccess component </components/property_access>`
+for the other form fields.
+
+.. versionadded:: 5.2
+
+    The ``getter`` and ``setter`` options were introduced in Symfony 5.2.
+
 .. caution::
 
     When a form has the ``inherit_data`` option set to ``true``, it does not use the data mapper and