Merge pull request #1893 from romainneutron/ConsoleDialog

weaverryan · weaverryan · commit 4a1185256794 · 2012-11-09T17:11:18.000-08:00
[2.0] Add paragraph about ask a validated response in the console component
diff --git a/components/console/introduction.rst b/components/console/introduction.rst
@@ -287,6 +287,37 @@ if you needed to know the name of something, you might do the following::
         'foo'
     );
 
+Ask and validate response
+-------------------------
+
+You can easily ask question and validate response with built-in methods::
+
+    $dialog = $this->getHelperSet()->get('dialog');
+
+    $validator = function ($value) {
+        if ('' === trim($value)) {
+            throw new \Exception('The value can not be empty');
+        }
+
+        return $value;
+    }
+
+    $password = $dialog->askAndValidate(
+        $output,
+        'Please enter the name of the widget',
+        $validator,
+        20,
+        'foo'
+    );
+
+The validation callback can be any callable PHP function, the fourth argument is
+the maximum number of attempts, set it to ``false`` for unlimited attempts. The
+fifth argument is the default value.
+
+The callback must throw an exception in case the value is not acceptable. Please
+note that the callback **must** return the value. The value can be modified by
+the callback (it will be returned modified by the helper).
+
 Testing Commands
 ----------------
 
