minor symfony#7125 Add docs about console question answer normalizing. (SpacePossum, javiereguiluz)

xabbuh · xabbuh · commit b5587f03241c · 2016-11-28T22:30:32.000+01:00
This PR was submitted for the 2.8 branch but it was merged into the 2.7 branch instead (closes symfony#7125). Discussion ---------- Add docs about console question answer normalizing. Add description about how to use normalizing on an answer given on a question in a console application. Commits ------- 5e39973 Minor rewords in the text and the code example 2cae22f Update questionhelper.rst 5f81796 Add docs about console question answer normalizing.
diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst
@@ -209,6 +209,38 @@ convenient for passwords::
     like in the example above. In this case, a ``RuntimeException``
     would be thrown.
 
+Normalizing the Answer
+----------------------
+
+Before validating the answer, you can "normalize" it to fix minor errors or
+tweak it as needed. For instance, in a previous example you asked for the bundle
+name. In case the user adds white spaces around the name by mistake, you can
+trim the name before validating it. To do so, configure a normalizer using the
+:method:`Symfony\\Component\\Console\\Question\\Question::setNormalizer`
+method::
+
+    use Symfony\Component\Console\Question\Question;
+
+    // ...
+    public function execute(InputInterface $input, OutputInterface $output)
+    {
+        // ...
+        $question = new Question('Please enter the name of the bundle', 'AppBundle');
+        $question->setNormalizer(function ($value) {
+            // $value can be null here
+            return $value ? trim($value) : '';
+        });
+
+        $name = $helper->ask($input, $output, $question);
+    }
+
+
+.. caution::
+
+    The normalizer is called first and the returned value is used as the input
+    of the validator. If the answer is invalid, don't throw exceptions in the
+    normalizer and let the validator handle those errors.
+
 Validating the Answer
 ---------------------
 
@@ -226,11 +258,12 @@ method::
         // ...
         $question = new Question('Please enter the name of the bundle', 'AcmeDemoBundle');
         $question->setValidator(function ($answer) {
-            if ('Bundle' !== substr($answer, -6)) {
+            if (!is_string($answer) || 'Bundle' !== substr($answer, -6)) {
                 throw new \RuntimeException(
                     'The name of the bundle should be suffixed with \'Bundle\''
                 );
             }
+
             return $answer;
         });
         $question->setMaxAttempts(2);
