Add missing docs

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",

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 <https://symfony.com/doc/current/components/string.html>`_) 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());

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

extra/string-extra/phpunit.xml.dist

@@ -13,7 +13,7 @@
     </php>
 
     <testsuites>
-        <testsuite name="Twig Markdown Extension Test Suite">
+        <testsuite name="Twig String Extension Test Suite">
             <directory>./tests/</directory>
         </testsuite>
     </testsuites>

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...

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;