Add instructions on how to use the official Twig extensions repo

templating/twig_extension.rst

@@ -15,8 +15,14 @@ your code faster.
 
 .. tip::
 
-    Before writing your own extensions, have a look at the
-    `Twig official extension repository`_.
+    When writing your own extensions, you might want to learn
+    from having a look at the `Twig Bridge`_  which contains most of
+    the extensions provided by the Symfony framework.
+
+.. seealso::
+
+    Read the :doc:`dedicated article </templating/twig_extension_repository>`
+    on how to use extensions from the `Twig official extension repository`_.
 
 Create the Extension Class
 --------------------------
@@ -131,3 +137,4 @@ For a more in-depth look into Twig Extensions, please take a look at the
 .. _`global variables`: http://twig.sensiolabs.org/doc/advanced.html#id1
 .. _`functions`: http://twig.sensiolabs.org/doc/advanced.html#id2
 .. _`Twig extensions documentation legacy`: http://twig.sensiolabs.org/doc/advanced_legacy.html#creating-an-extension
+.. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig/Extension

templating/twig_extension_repository.rst

@@ -0,0 +1,93 @@
+.. index::
+   single: Using the Twig Extensions Repository
+
+How to Use the Twig Extensions Repository
+=========================================
+
+The `Twig official extensions repository`_ contains some
+helpful Twig extensions that are not part of the Twig core. They add
+useful functions for internationalization, working with arrays and
+dates. To learn more about these extensions, have a look at their
+`documentation`_.
+
+This repository is meant as an extension to Twig in general. So, it
+does *not* provide a direct means to register itself with the
+Symfony framework (it is not a bundle).
+
+It is, however, very easy to get the extensions set up in Symfony.
+This article will show you how to register the ``Intl`` extension from
+that repository so you can use it in your Twig templates.
+
+.. tip::
+
+    Setting up one of the other extensions works just the same way,
+    except you need to choose another service id and have to use
+    the right class name.
+
+First, install the Twig extensions using Composer.
+
+.. code-block:: terminal
+
+    $ composer require twig/extensions
+
+Then, define the extension class as a service and tag it with the
+``twig.extension`` tag.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.twig_extensions.intl:
+                class: Twig_Extensions_Extension_Intl
+                public: false
+                tags:
+                    - { name: twig.extension }
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.twig_extensions.intl" public="false"
+                    class="Twig_Extensions_Extension_Intl">
+                    <tag name="twig.extension" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+
+        $container
+            ->register('app.twig_extensions.intl', \Twig_Extensions_Extension_Intl::class)
+            ->setPublic(false)
+            ->addTag('twig.extension');
+
+And that's it! For example, you should now be able to use the
+``localizeddate`` filter to format a date according to the
+current request's locale:
+
+.. code-block:: twig
+
+    {{ post.published_at|localizeddate('medium', 'none', locale) }}
+
+Learning further
+----------------
+
+In the :doc:`reference section </reference/twig_reference>`, you can
+find all the extra Twig functions, filters, tags and tests that are
+already added by the Symfony Framework.
+
+Also, documentation is available on :doc:`how to write your own Twig
+extension </templating/twig_extension>`.
+
+.. _`Twig official extensions repository`: https://github.com/twigphp/Twig-extensions
+.. _`documentation`: http://twig-extensions.readthedocs.io/