[Form] Documented the setInvalidMessage() method for data mappers

Author: javiereguiluz

form/data_mappers.rst

@@ -88,6 +88,7 @@ in your form type::
     use App\Painting\Color;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\DataMapperInterface;
+    use Symfony\Component\Form\Exception\TransformationFailedException;
     use Symfony\Component\Form\Exception\UnexpectedTypeException;
     use Symfony\Component\Form\FormInterface;
 
@@ -124,6 +125,17 @@ in your form type::
             /** @var FormInterface[] $forms */
             $forms = iterator_to_array($forms);
 
+            // optionally you can validate the data to throw more precise exception errors
+            $redComponent = $forms['red']->getData();
+            if (!\is_numeric($redComponent) || $redComponent < 0 || $redComponent > 255) {
+                $failure = new TransformationFailedException('Expected a RGB color component.');
+                $failure->setInvalidMessage('Color components should be numeric values in the [0-255] range. {{ value }} is invalid.', [
+                    '{{ value }}' => $redComponent,
+                ]);
+
+                throw $failure;
+            }
+
             // as data is passed by reference, overriding it will change it in
             // the form object as well
             // beware of type inconsistency, see caution below
@@ -135,6 +147,10 @@ in your form type::
         }
     }
 
+.. versionadded:: 4.3
+
+    The ``setInvalidMessage()`` method was introduced in Symfony 4.3.
+
 .. caution::
 
     The data passed to the mapper is *not yet validated*. This means that your