diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst index 87c62ca7629..8e8ece66493 100644 --- a/components/console/helpers/index.rst +++ b/components/console/helpers/index.rst @@ -11,6 +11,7 @@ The Console Helpers processhelper progressbar questionhelper + prettywordwrapper table debug_formatter diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc index 68e1e722a87..a66bc57831a 100644 --- a/components/console/helpers/map.rst.inc +++ b/components/console/helpers/map.rst.inc @@ -2,5 +2,6 @@ * :doc:`/components/console/helpers/processhelper` * :doc:`/components/console/helpers/progressbar` * :doc:`/components/console/helpers/questionhelper` +* :doc:`/components/console/helpers/prettywordwrapper` * :doc:`/components/console/helpers/table` * :doc:`/components/console/helpers/debug_formatter` diff --git a/components/console/helpers/prettywordwrapper.rst b/components/console/helpers/prettywordwrapper.rst new file mode 100644 index 00000000000..ef4219fdb5d --- /dev/null +++ b/components/console/helpers/prettywordwrapper.rst @@ -0,0 +1,273 @@ +.. index:: +single: Console Helpers; Word Wrapper Helper + +Word Wrapper Helper +=================== + +The word wrapper provides a :method:`Symfony\\Component\\Console\\Helper\\WordWrapperHelper::wordwrap` +function to create well wrapped text messages. + +The :class:`Symfony\\Component\\Console\\Helper\\WordWrapperHelper` is included +in the default helper set, which you can get by calling +:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`:: + + $wrapper = $this->getHelper('prettywordwrapper'); + +The method returns a string, which you'll usually render to the console by +passing it to the +:method:`OutputInterface::writeln ` method. + +Other using +----------- + +You can use it with the default :class:`OutputFormatter ` or +other formatter that implements +:class:`WrappableOutputFormatterInterface ` + +.. note:: + + See the ``CUT_*`` options below. + +.. code-block:: php + + $text = '...'; + $wrappedText = $output->getFormatter()->format( + $output->getFormatter()->wordwrap($text, 30, WordWrapperHelper::CUT_ALL) + ); + + // OR, you can set the default cutting option + $output->getFormatter()->setDefaultWrapCutOption(WordWrapperHelper::CUT_ALL); + $wrappedText = $output->getFormatter()->formatAndWrap($text, 30); + +You can use it with :class:`Table ` also: + +.. code-block:: php + + $table = $this->getHelper('table'); + $table + ->setDefaultColumnWordWrapCutOption(WordWrapperHelper::CUT_DISABLE) + ->setColumnMaxWidth(1, 40) // Here will use the set default cut option + ->setColumnMaxWidth(2, 20, WordWrapperHelper::CUT_ALL) // Here will use the CUT_ALL option + ; + +.. note:: + + More information about table helper: :doc:`/components/console/helpers/table` + +Cut options +----------- + +You can configure how to behave the wrapper. + +======================== ====== ====================================================================================== +Name Value Description +======================== ====== ====================================================================================== +``CUT_DISABLE`` ``0`` It disables all of options. Always break the text at word boundary. +``CUT_LONG_WORDS`` ``1`` "Long words" means the length of word is longer than one line. If it is set, the + long words will cut. +``CUT_WORDS`` ``3`` Always break at set length, it will cut all words. It would be useful if you have + little space. (Info: It "contains" the ``CUT_LONG_WORDS`` option) +``CUT_URLS`` ``4`` Lots of terminal can recognize URL-s in text and make them clickable (if there isn't + break inside the URL) The URLs can be long, default we keep it in one block even if + it gets ugly response. You can switch this behavior off with this option. The result + will be pretty, but the URL won't be clickable. +``CUT_ALL`` ``7`` Switch every "word cut" options on. +``CUT_FILL_UP_MISSING`` ``8`` End of lines will fill up with spaces in order to every line to be same length. +``CUT_NO_REPLACE_EOL`` ``16`` The program will replace the PHP_EOL in the input string to $break by default. You + switch it off with this. +======================== ====== ====================================================================================== + +Examples +~~~~~~~~ + +.. note:: + + The default option is ``WordWrapperHelper::CUT_LONG_WORDS``. + +Default parameters: + +============== =========================================================================================== +Parameter Value +============== =========================================================================================== +``$width`` ``120`` +``$cutOption`` ``WordWrapperHelper::CUT_LONG_WORDS`` +``$break`` ``\n`` +============== =========================================================================================== + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + // Default parameters + $default = $wrapper->wordwrap($text); + +.. code-block:: text + + Lorem ipsum dolor sit amet. + +Short lines, **disable** cuts ( ``CUT_DISABLE`` ) + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_DISABLE); + +.. code-block:: text + + Lorem + ipsum + dolor + sit + amet. + +Short lines, **enable** word cutting only for long words ( ``CUT_LONG_WORDS`` ) + +.. note:: + + Long words in this example: ``Lorem``, ``ipsum`` and ``dolor``. The ``sit`` won't be cut here. + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_LONG_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r + sit + amet + . + +Short lines, **enable** cut for every word ( ``CUT_WORDS`` ) + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r si + t am + et. + +Short lines, **disable** word cutting ( ``CUT_DISABLE`` ) + **set** custom break + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + // The width is 6 here, not 4 like above. + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_DISABLE, "<\n") . "<"; + +.. code-block:: text + + Lorem< + ipsum< + dolor< + sit< + amet.< + +Short lines, **disable** word cutting ( ``CUT_DISABLE`` ) + **enable** fill up ( ``CUT_FILL_UP_MISSING`` ) + **set** custom break + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + // The width is 6 here, not 4 like above. + $default = $wrapper->wordwrap( + $text, + 6, + WordWrapperHelper::CUT_DISABLE | WordWrapperHelper::CUT_FILL_UP_MISSING, + "<\n" + ) . "<"; + +.. code-block:: text + + Lorem < + ipsum < + dolor < + sit < + amet. < + +Text with URL + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet: http://symfony.com"; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_DISABLE); + +.. code-block:: text + + Lorem + ipsum + dolor + sit + amet: + http://symofny.com + +Text with URL, **enable** word cut ( ``CUT_WORDS`` ) + **disable** URL cut + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet: http://symfony.com"; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r si + t am + et: + http://symofny.com + +Text with URL, **disable** word cut + **enable** URL cut ( ``CUT_URLS`` ) + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet: http://symfony.com"; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_URLS); + +.. code-block:: text + + Lorem + ipsum + dolor + sit + amet: + http + ://s + ymof + ny.c + om + +Text with style tags + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r si + t am + et. + +Line endings +------------ + +There are different line endings on different operating systems. It can cause some problems, so we unify it to ``\n``. +You can switch this behavior off with ``WordWrapperHelper::CUT_NO_REPLACE_EOL``. diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index 20067ba5127..7c248d9c4ba 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -134,7 +134,7 @@ If you prefer to wrap long contents in multiple rows, use the // ... $table->setColumnMaxWidth(0, 5); - $table->setColumnMaxWidth(1, 10); + $table->setColumnMaxWidth(1, 10, WordWrapperHelper::CUT_ALL); $table->render(); The output of this command will be: @@ -150,6 +150,12 @@ The output of this command will be: | (the rest of rows...) | +-------+------------+--------------------------------+ +.. note:: + + More information about + :class:`WordWrapperHelper ` and the available + cut options: :doc:`/components/console/helpers/prettywordwrapper` + The table style can be changed to any built-in styles via :method:`Symfony\\Component\\Console\\Helper\\Table::setStyle`:: pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy