Skip to content

Add instructions on how to use the official Twig extensions repo #7616

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 7 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions templating/twig_extension.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------------
Expand Down Expand Up @@ -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
93 changes: 93 additions & 0 deletions templating/twig_extension_repository.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
.. index::
single: Using the Twig Extensions Repository
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we really need this article. We don't explain those extensions (because they are documented in their own repo) and they are not special regarding the Symfony+Twig config: they are enabled just like any other Twig extensions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right in that there is nothing special with these extensions.

However, all Twig Extensions I normally use are either part of a bundle or there is a bundle to set them up in Symfony.

I felt there was kind of a gap for the "official" Twig Extensions. They're mentioned in the Symfony docs, but every time I need them it takes me moment to remind myself that I have to set them up that way - which is why I wrote this article to help the future me :-).


How to Use the Twig Extensions Repository
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we change the title of this article? The Repository word is confusing here. What we want is to enable/use the official Twig extensions in Symfony apps.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, "The official Twig extensions" isn't very helpful either, rather misleading...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Using Twig extensions not provided as a bundle"...? Meh.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about repeating what's below and just add "official":

How to Use the Twig Official Extensions

=========================================

The `Twig official extensions repository`_ contains some
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Twig official extensions repository (or change the target at the end of the document)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed link below

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/