From 5c20204c6aa7417deccb4ec8b901d7a097cd6a81 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Fri, 14 Jun 2019 17:03:21 +0200
Subject: [PATCH] [Form] Documented the setInvalidMessage() method for data
 transformers

---
 form/data_transformers.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/form/data_transformers.rst b/form/data_transformers.rst
index 8775744bdb7..cea8bda1569 100644
--- a/form/data_transformers.rst
+++ b/form/data_transformers.rst
@@ -291,6 +291,44 @@ and type-hint the new class::
         // ...
     }
 
+Instead of defining the same ``invalid_message`` every time the form type is
+used, you can set the end-user error message in the data transformer using the
+``setInvalidMessage()`` method::
+
+    // src/Form/DataTransformer/IssueToNumberTransformer.php
+    namespace App\Form\DataTransformer;
+
+    use Symfony\Component\Form\DataTransformerInterface;
+    use Symfony\Component\Form\Exception\TransformationFailedException;
+
+    class IssueToNumberTransformer implements DataTransformerInterface
+    {
+        // ...
+
+        public function reverseTransform($issueNumber)
+        {
+            // ...
+
+            if (null === $issue) {
+                $privateErrorMessage = sprintf('An issue with number "%s" does not exist!', $issueNumber);
+                $publicErrorMessage = 'The given "{{ value }}" value is not a valid issue number.';
+
+                $failure = new TransformationFailedException($privateErrorMessage);
+                $failure->setInvalidMessage($publicErrorMessage, [
+                    '{{ value }}' => $issueNumber,
+                ]);
+
+                throw $failure;
+            }
+
+            return $issue;
+        }
+    }
+
+.. versionadded:: 4.3
+
+    The ``setInvalidMessage()`` method was introduced in Symfony 4.3.
+
 That's it! As long as you're using :ref:`autowire <services-autowire>` and
 :ref:`autoconfigure <services-autoconfigure>`, Symfony will automatically
 know to pass your ``TaskType`` an instance of the ``IssueToNumberTransformer``.