diff --git a/CHANGELOG b/CHANGELOG index a7a9f760c..cbc4a6339 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,6 +1,6 @@ * 2.12.1 (2019-XX-XX) - * n/a + * added the String extension in the "extra" repositories: "u" filter * 2.12.0 (2019-10-05) @@ -8,7 +8,7 @@ * added support for an "arrow" function on the "sort" filter * added the CssInliner extension in the "extra" repositories: "inline_css" filter - * added the Inky extension in the "extra" repositories: "inky_to_html" filter + * added the Inky extension in the "extra" repositories: "inky_to_html" filter * added Intl extension in the "extra" repositories: "country_name", "currency_name", "currency_symbol", "language_name", "locale_name", "timezone_name", "format_currency", "format_number", diff --git a/doc/filters/u.rst b/doc/filters/u.rst new file mode 100644 index 000000000..7b55b118f --- /dev/null +++ b/doc/filters/u.rst @@ -0,0 +1,78 @@ +``u`` +===== + +.. versionadded:: 2.12.1 + The ``u`` filter was added in Twig 2.12.1. + +The ``u`` filter wraps a text in a Unicode object (a `Symfony UnicodeString +instance `_) that +exposes methods to "manipulate" the string. + +Let's see some common use cases. + +Wrapping a text to a given number of characters: + +.. code-block:: twig + + {{ 'Symfony String + Twig = <3'|u.wordwrap(5) }} + Symfony + String + + + Twig + = <3 + +Truncating a string: + +.. code-block:: twig + + {{ 'Lorem ipsum'|u.truncate(8) }} + Lorem ip + + {{ 'Lorem ipsum'|u.truncate(8, '...') }} + Lorem... + +Converting a string to *snake* case or *camelCase*: + +.. code-block:: twig + + {{ 'SymfonyStringWithTwig'|u.snake }} + symfony_string_with_twig + + {{ 'symfony_string with twig'|u.camel.title }} + SymfonyStringWithTwig + +You can also chain methods: + +.. code-block:: twig + + {{ 'Symfony String + Twig = <3'|u.wordwrap(5).upper }} + SYMFONY + STRING + + + TWIG + = <3 + +For large strings manipulation, use the ``apply`` tag: + +.. code-block:: twig + + {% apply u.wordwrap(5) %} + Some large amount of text... + {% endapply %} + +.. note:: + + The ``u`` filter is part of the ``StringExtension`` which is not installed + by default. Install it first: + + .. code-block:: bash + + $ composer req twig/string-extra + + Then, use the ``twig/extra-bundle`` on Symfony projects or add the extension + explictly on the Twig environment:: + + use Twig\Extra\String\StringExtension; + + $twig = new \Twig\Environment(...); + $twig->addExtension(new StringExtension()); diff --git a/extra/string-extra/README.md b/extra/string-extra/README.md index cef5799d5..91627d2ae 100644 --- a/extra/string-extra/README.md +++ b/extra/string-extra/README.md @@ -1,10 +1,11 @@ String Extension ================ -This package is a Twig extension that provides integration with the Symfony String component. +This package is a Twig extension that provides integration with the Symfony +String component. -It provides a single [`u`][1] filter that wraps a text in a `UnicodeString` object to give access to [methods of the class](https://symfony.com/doc/current/components/string.html). - -`{{ 'Symfony String + Twig = <3'|u.wordwrap(5) }}` +It provides a single [`u`][1] filter that wraps a text in a `UnicodeString` +object to give access to [methods of the class][2]. [1]: https://twig.symfony.com/u +[2]: https://symfony.com/doc/current/components/string.html diff --git a/extra/string-extra/phpunit.xml.dist b/extra/string-extra/phpunit.xml.dist index 4b84ca9c2..29f08c8fd 100644 --- a/extra/string-extra/phpunit.xml.dist +++ b/extra/string-extra/phpunit.xml.dist @@ -13,7 +13,7 @@ - + ./tests/ diff --git a/extra/string-extra/tests/Fixtures/string.test b/extra/string-extra/tests/Fixtures/string.test index 945af3355..e2ba62896 100644 --- a/extra/string-extra/tests/Fixtures/string.test +++ b/extra/string-extra/tests/Fixtures/string.test @@ -3,15 +3,25 @@ --TEMPLATE-- {{ 'Symfony String + Twig = <3'|u|raw }} -{{ 'Symfony String + Twig = <3'|u.wordwrap(5)|raw }} +{{ 'Symfony String + Twig = <3'|u.wordwrap(5).upper|raw }} + +{{ 'SymfonyStringWithTwig'|u.snake }} +{{ 'symfony_string with twig'|u.camel.title }} + +{{ 'Lorem ipsum'|u.truncate(8, '...') }} --DATA-- return [] --EXPECT-- Symfony String + Twig = <3 -Symfony -String +SYMFONY +STRING + -Twig +TWIG = <3 + +symfony_string_with_twig +SymfonyStringWithTwig + +Lorem... diff --git a/extra/string-extra/tests/IntegrationTest.php b/extra/string-extra/tests/IntegrationTest.php index 1c0aea419..032c9a9d9 100644 --- a/extra/string-extra/tests/IntegrationTest.php +++ b/extra/string-extra/tests/IntegrationTest.php @@ -9,7 +9,7 @@ * file that was distributed with this source code. */ -namespace Twig\Extra\Markdown\Tests; +namespace Twig\Extra\String\Tests; use Twig\Extra\String\StringExtension; use Twig\Test\IntegrationTestCase;