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 3 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.
Copy link
Member

Choose a reason for hiding this comment

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

framework


.. tip::
Copy link
Member

Choose a reason for hiding this comment

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

we could use .. seealso:: instead here


We also have :doc:`a short article </templating/twig_extension_repository>`
Copy link
Member

@xabbuh xabbuh Mar 14, 2017

Choose a reason for hiding this comment

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

We always avoid the first person perspective in the docs. This could be rewritten to something like "Read ... on how to use [...]".

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
92 changes: 92 additions & 0 deletions templating/twig_extension_repository.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
.. 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 extension repository`_ contains (as of writing) some
Copy link
Member

Choose a reason for hiding this comment

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

The official 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 think we can drop the "as of writing" part

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
is does *not* provide a direct means to register itself with the
Copy link
Member

Choose a reason for hiding this comment

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

So, it is does not [...]

Symfony Framework (it is not a Bundle).
Copy link
Member

Choose a reason for hiding this comment

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

framework

Copy link
Member

Choose a reason for hiding this comment

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

bundle


It is, however, very easy to get the extensions set-up in Symfony.
Copy link
Member

Choose a reason for hiding this comment

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

set up

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, add the Twig Extensions repository as a dependency in your
project. Assuming you are using Composer, run
Copy link
Member

@xabbuh xabbuh Mar 14, 2017

Choose a reason for hiding this comment

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

IMO we should ignore that in theory there are other ways to install the extensions and reword this to "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:
twig_extensions.intl:
Copy link
Contributor

Choose a reason for hiding this comment

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

The namespace should not have an "s" IMHO, what do others think?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I chose that because the repo is called "Twig Extensions". Thus I'd call a corresponding bundle "TwigExtensionsBundle", which would give this name.

Or should we better recommend prefixing it with app?

Copy link
Member

Choose a reason for hiding this comment

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

I guess app. is better since there may be other bundles who try the same that we do here.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Now that you mention it... For example, I've come across this one.

Would you guys recommend using a 3rd party bundle instead of providing instructions?

Note I am not affiliated with that bundle in any way and cannot endorse it.

Copy link
Member

Choose a reason for hiding this comment

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

I would always strive to keep the number of external dependencies as low as possible. Given that registering services is not hard and does not require much work I would only require that bundle if you need one of the extensions shipped with it.

class: Twig_Extensions_Extension_Intl
tags:
- { name: twig.extension }
Copy link
Member

Choose a reason for hiding this comment

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

maybe also mark the service as private


.. 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="twig_extensions.intl"
class="Twig_Extensions_Extension_Intl">
<tag name="twig.extension" />
</service>
</services>
</container>

.. code-block:: php

// app/config/services.php
use \Twig_Extensions_Extension_Intl;
Copy link
Member

Choose a reason for hiding this comment

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

In Symfony, we usually don't have use statements for classes from the global namespace.


$container
->register('twig_extensions.intl', Twig_Extensions_Extension_Intl::class)
->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 request's
current locale:
Copy link
Member

Choose a reason for hiding this comment

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

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

We also have documentation on :doc:`how to write your own Twig extension </templating/twig_extension>`.
Copy link
Member

Choose a reason for hiding this comment

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

first person :)


.. _`Twig official extension repository`: https://github.com/twigphp/Twig-extensions
.. _`documentation`: http://twig-extensions.readthedocs.io/