Skip to content

Loading…

Documenting the Console Helpers #1999

Merged
merged 7 commits into from

3 participants

@Sgoettschkes

As suggested in #1811, this PR includes documention on the two Console Helpers:

  • DialogHelper
  • FormatterHelper

The new documents are included in the index and checked for sphinx issues.

@WouterJ
Symfony member

GitHub don't let me create a PR on your repo, but you should change this format issues: WouterJ/symfony-docs@69ce6c9

@Sgoettschkes

@WouterJ Done. I think to be able to make a PR you would need to add my repository as a new remote, pull my branch and make changes. Maybe there is a better way like giving you push access to my repository or you giving me push access.

@WouterJ
Symfony member

@Sgoettschkes well, I added your repo as a remote and have based my commit on your branch. But in order to create a PR on github you should choose a branch in the dropdown list and it looks like Github doesn't refresh it if the main repo is forked by a new user. So your repo was not in the list of repo's to request a PR and I wasn't able to add you in there...

@WouterJ WouterJ referenced this pull request
Closed

Add new Console features #2022

@Sgoettschkes

I would love to see this merged so we can get started documenting the new ProgressHelper and new DialogHelper capabilities.

Any change requests for this PR?

@WouterJ
Symfony member

@Sgoettschkes :+1:, but be aware that the ProgressHelper is already documented (it is included in the introduction chapter right now, it should be copied into a new file inside the helper dir)

@weaverryan weaverryan merged commit b85a526 into symfony:2.0
@weaverryan
Symfony member

Hi Sebastian!

Sorry for the delay on merging this - it's a really great PR! I've now merged it in and made only a few minor changes.

As @WouterJ said, the ProgressHelper is documented already, but I much prefer your approach of placing these helpers in their own documents, instead of inside on big document. Could you move the ProgressHelper docs into the new format? I'll merge everything up to master now so that the new code is available there.

Thanks!

@WouterJ
Symfony member

@Sgoettschkes are you going to document these new helpers/features? (otherwise I will d it)

@Sgoettschkes

As said I'll do it. I'll also take care of adding the new features as menttioned in #2022!

@Sgoettschkes Sgoettschkes deleted the unknown repository branch
@WouterJ
Symfony member

ok, great job! (almost all components are documented right now :bicyclist:)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Nov 10, 2012
  1. @WouterJ
  2. @WouterJ
Commits on Nov 12, 2012
  1. @WouterJ

    [WIP] FormatterHelper docs

    WouterJ committed
Commits on Dec 3, 2012
  1. @Sgoettschkes
Commits on Dec 4, 2012
  1. @Sgoettschkes
  2. @Sgoettschkes
Commits on Dec 5, 2012
  1. @Sgoettschkes
View
97 components/console/helpers/dialoghelper.rst
@@ -0,0 +1,97 @@
+.. index::
+ single: Console Helpers; Dialog Helper
+
+Dialog Helper
+=============
+
+The Dialog Helper provides functions to ask the user for more information.
+It is included in the default helper set, which you can get
+by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
+
+ $dialog = $this->getHelperSet()->get('dialog');
+
+All the methods inside the Dialog Helper have an
+:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as first argument,
+the question as second argument and the default value as last argument.
+
+Asking the User for confirmation
+--------------------------------
+
+Suppose you want to confirm an action before actually executing it. Add
+the following to your command::
+
+ // ...
+ if (!$dialog->askConfirmation(
+ $output,
+ '<question>Continue with this action?</question>',
+ false
+ )) {
+ return;
+ }
+
+In this case, the user will be asked "Continue with this action", and will return
+``true`` if the user answers with ``y`` or false in any other case. The third
+argument to ``askConfirmation`` is the default value to return if the user doesn't
+enter any input.
+
+Asking the User for information
+-------------------------------
+
+You can also ask question with more than a simple yes/no answer. For instance,
+if you want to know a bundle name, you can add this to your command::
+
+ // ...
+ $bundle = $dialog->ask(
+ $output,
+ 'Please enter the name of the bundle',
+ 'AcmeDemoBundle'
+ );
+
+The user will be asked "Please enter the name of the bundle". They can type
+some name which will be returned by the ``ask`` method. If they leave it empty
+the default value (``AcmeDemoBundle`` here) is returned.
+
+Validating the answer
+---------------------
+
+You can even validate the answer. For instance, in our last example we asked
+for the bundle name. Following the Symfony2 naming conventions, it should
+be suffixed with ``Bundle``. We can validate that by using the
+:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::askAndValidate`
+method::
+
+ // ...
+ $bundle = $dialog->askAndValidate(
+ $output,
+ 'Please enter the name of the bundle',
+ function ($answer) {
+ if ('Bundle' !== substr($answer, -6)) {
+ throw new \RunTimeException(
+ 'The name of the bundle should be suffixed with \'Bundle\''
+ );
+ }
+ },
+ false,
+ 'AcmeDemoBundle'
+ );
+
+This methods has 2 new arguments, the full signature is::
+
+ askAndValidate(
+ OutputInterface $output,
+ string|array $question,
+ callback $validator,
+ integer $attempts = false,
+ string $default = null
+ )
+
+The ``$validator`` is a callback which handles the validation. It should
+throw an exception if there is something wrong. The exception message is displayed
+in the console, so it is a good practice to put some usefull information
+in it.
+
+You can set the max number of times to ask in the ``$attempts`` argument.
+If we reach this max number it will use the default value, which is given
+in the last argument. Using ``false`` means the amount of attempts is infinite.
+The user will be asked as long as he provides an invalid answer and will only
+be able to proceed if his input is valid.
View
52 components/console/helpers/formatterhelper.rst
@@ -0,0 +1,52 @@
+.. index::
+ single: Console Helpers; Formatter Helper
+
+Formatter Helper
+================
+
+The Formatter helpers provides functions to format the output with colors.
+You can do more advanced things with this helper than the things in
+:ref:`components-console-coloring`.
+
+The Formatter Helper is included in the default helper set, which you can
+get by calling
+:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
+
+ $formatter = $this->getHelperSet()->get('formatter');
+
+The methods return a string which in most cases you want to write
+that data to the console with
+:method:`Symfony\\Component\\Console\\Output\\Output::writeln`.
+
+Print messages in a section
+---------------------------
+
+Symfony uses a defined style when printing to the command line.
+It prints the section in color and with brackets around and the
+actual message behind this section indication.
+
+To reproduce this style, you can use the
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`::
+
+ $formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
+ $output->writeln($formattedLine);
+
+Print messages in a block
+-------------------------
+
+Sometimes you want to be able to print a whole block of text with a background
+color. Symfony uses this when printing error messages.
+
+If you print your error message on more than one line manually, you will
+notice that the background is only as long as each individual line. Use the
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
+togenerate a block output::
+
+ $errorMessages = array('Error!', 'Something went wrong');
+ $formattedBlock = $formatter->formatBlock($errorMessages, 'error');
+
+As you can see, passing an array of messages to the
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
+method creates the desired output. If you pass ``true`` as third parameter, the
+block will be formatted with more padding (one blank line above and below the
+messages and 2 spaces on the left and right).
View
16 components/console/helpers/index.rst
@@ -0,0 +1,16 @@
+.. index::
+ single: Console; Console Helpers
+
+The Console Helpers
+===================
+
+.. toctree::
+ :hidden:
+
+ dialoghelper
+ formatterhelper
+
+The Console Components comes with some usefull helpers. These helpers contain
+function to ease some common tasks.
+
+.. include:: map.rst.inc
View
2 components/console/helpers/map.rst.inc
@@ -0,0 +1,2 @@
+* :doc:`/components/console/helpers/dialoghelper`
+* :doc:`/components/console/helpers/formatterhelper`
View
2 components/console/index.rst
@@ -7,3 +7,5 @@ Console
introduction
usage
single_command_tool
+
+ helpers/index
View
36 components/console/introduction.rst
@@ -108,6 +108,8 @@ This prints::
HELLO FABIEN
+.. _components-console-coloring:
+
Coloring the Output
~~~~~~~~~~~~~~~~~~~
@@ -255,38 +257,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
1
);
-Asking the User for Information
--------------------------------
-
-When creating commands, you have the ability to collect more information
-from the user by asking him/her questions. For example, suppose you want
-to confirm an action before actually executing it. Add the following to your
-command::
-
- $dialog = $this->getHelperSet()->get('dialog');
- if (!$dialog->askConfirmation(
- $output,
- '<question>Continue with this action?</question>',
- false
- )) {
- return;
- }
-
-In this case, the user will be asked "Continue with this action", and unless
-they answer with ``y``, the task will stop running. The third argument to
-``askConfirmation`` is the default value to return if the user doesn't enter
-any input.
-
-You can also ask questions with more than a simple yes/no answer. For example,
-if you needed to know the name of something, you might do the following::
-
- $dialog = $this->getHelperSet()->get('dialog');
- $name = $dialog->ask(
- $output,
- 'Please enter the name of the widget',
- 'foo'
- );
-
Testing Commands
----------------
@@ -407,4 +377,4 @@ Learn More!
* :doc:`/components/console/usage`
* :doc:`/components/console/single_command_tool`
-.. _Packagist: https://packagist.org/packages/symfony/console
+.. _Packagist: https://packagist.org/packages/symfony/console
View
1 components/map.rst.inc
@@ -14,6 +14,7 @@
* :doc:`/components/console/introduction`
* :doc:`/components/console/usage`
* :doc:`/components/console/single_command_tool`
+ * :doc:`/components/console/helpers/index`
* **CSS Selector**
Something went wrong with that request. Please try again.