From e98545b603dda7f131fec4a39ac7f01e4f39e5f0 Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Fri, 11 Aug 2023 16:46:44 +0200 Subject: [PATCH] [Console] Mention `SymfonyStyle` in helpers doc --- .../console/helpers/formatterhelper.rst | 8 +++- components/console/helpers/progressbar.rst | 5 ++ components/console/helpers/questionhelper.rst | 47 ++++++++++--------- components/console/helpers/table.rst | 9 +++- console/style.rst | 8 ++++ 5 files changed, 53 insertions(+), 24 deletions(-) diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index 4e3f11940fd..135a5898778 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -13,7 +13,13 @@ in the default helper set and you can get it by calling The methods return a string, which you'll usually render to the console by passing it to the -:method:`OutputInterface::writeln ` method. +:method:`OutputInterface::writeln ` +method. + +.. note:: + + As an alternative, consider using the + :ref:`SymfonyStyle ` to display stylized blocks. Print Messages in a Section --------------------------- diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index 3e43452a737..dd4e5ec7f78 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -6,6 +6,11 @@ information, which updates as your command runs: .. image:: /_images/components/console/progressbar.gif +.. note:: + + As an alternative, consider using the + :ref:`SymfonyStyle ` to display a progress bar. + To display progress details, use the :class:`Symfony\\Component\\Console\\Helper\\ProgressBar`, pass it a total number of units, and advance the progress as the command executes:: diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst index 01c7174e723..07cc75877b5 100644 --- a/components/console/helpers/questionhelper.rst +++ b/components/console/helpers/questionhelper.rst @@ -15,6 +15,11 @@ first argument, an :class:`Symfony\\Component\\Console\\Output\\OutputInterface` instance as the second argument and a :class:`Symfony\\Component\\Console\\Question\\Question` as last argument. +.. note:: + + As an alternative, consider using the + :ref:`SymfonyStyle ` to ask questions. + Asking the User for Confirmation -------------------------------- @@ -82,9 +87,9 @@ if you want to know a bundle name, you can add this to your command:: $question = new Question('Please enter the name of the bundle', 'AcmeDemoBundle'); $bundleName = $helper->ask($input, $output, $question); - + // ... do something with the bundleName - + return Command::SUCCESS; } @@ -120,7 +125,7 @@ from a predefined list:: $output->writeln('You have just selected: '.$color); // ... do something with the color - + return Command::SUCCESS; } @@ -162,7 +167,7 @@ this use :method:`Symfony\\Component\\Console\\Question\\ChoiceQuestion::setMult $colors = $helper->ask($input, $output, $question); $output->writeln('You have just selected: ' . implode(', ', $colors)); - + return Command::SUCCESS; } @@ -191,9 +196,9 @@ will be autocompleted as the user types:: $question->setAutocompleterValues($bundles); $bundleName = $helper->ask($input, $output, $question); - + // ... do something with the bundleName - + return Command::SUCCESS; } @@ -230,9 +235,9 @@ provide a callback function to dynamically generate suggestions:: $question->setAutocompleterCallback($callback); $filePath = $helper->ask($input, $output, $question); - + // ... do something with the filePath - + return Command::SUCCESS; } @@ -254,9 +259,9 @@ You can also specify if you want to not trim the answer by setting it directly w $question->setTrimmable(false); // if the users inputs 'elsa ' it will not be trimmed and you will get 'elsa ' as value $name = $helper->ask($input, $output, $question); - + // ... do something with the name - + return Command::SUCCESS; } @@ -285,9 +290,9 @@ the response to a question should allow multiline answers by passing ``true`` to $question->setMultiline(true); $answer = $helper->ask($input, $output, $question); - + // ... do something with the answer - + return Command::SUCCESS; } @@ -313,9 +318,9 @@ convenient for passwords:: $question->setHiddenFallback(false); $password = $helper->ask($input, $output, $question); - + // ... do something with the password - + return Command::SUCCESS; } @@ -347,7 +352,7 @@ convenient for passwords:: QuestionHelper::disableStty(); // ... - + return Command::SUCCESS; } @@ -376,9 +381,9 @@ method:: }); $bundleName = $helper->ask($input, $output, $question); - + // ... do something with the bundleName - + return Command::SUCCESS; } @@ -420,9 +425,9 @@ method:: $question->setMaxAttempts(2); $bundleName = $helper->ask($input, $output, $question); - + // ... do something with the bundleName - + return Command::SUCCESS; } @@ -482,9 +487,9 @@ You can also use a validator with a hidden question:: $question->setMaxAttempts(20); $password = $helper->ask($input, $output, $question); - + // ... do something with the password - + return Command::SUCCESS; } diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index e3bb282ed7e..e83ed352a3e 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -14,6 +14,11 @@ When building a console application it may be useful to display tabular data: | 80-902734-1-6 | And Then There Were None | Agatha Christie | +---------------+--------------------------+------------------+ +.. note:: + + As an alternative, consider using the + :ref:`SymfonyStyle ` to display a table. + To display a table, use :class:`Symfony\\Component\\Console\\Helper\\Table`, set the headers, set the rows and then render the table:: @@ -38,7 +43,7 @@ set the headers, set the rows and then render the table:: ]) ; $table->render(); - + return Command::SUCCESS; } } @@ -414,7 +419,7 @@ The only requirement to append rows is that the table must be rendered inside a $table->render(); $table->appendRow(['Symfony']); - + return Command::SUCCESS; } } diff --git a/console/style.rst b/console/style.rst index 59ad22ba3fa..98ab5d66b38 100644 --- a/console/style.rst +++ b/console/style.rst @@ -96,6 +96,8 @@ Titling Methods // ... +.. _symfony-style-content: + Content Methods ~~~~~~~~~~~~~~~ @@ -219,6 +221,8 @@ Admonition Methods 'Aenean sit amet arcu vitae sem faucibus porta', ]); +.. _symfony-style-progressbar: + Progress Bar Methods ~~~~~~~~~~~~~~~~~~~~ @@ -267,6 +271,8 @@ Progress Bar Methods Creates an instance of :class:`Symfony\\Component\\Console\\Helper\\ProgressBar` styled according to the Symfony Style Guide. +.. _symfony-style-questions: + User Input Methods ~~~~~~~~~~~~~~~~~~ @@ -329,6 +335,8 @@ User Input Methods $io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3'], 'queue1'); +.. _symfony-style-blocks: + Result Methods ~~~~~~~~~~~~~~