-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
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
Changes from 3 commits
2bf45c2
c7b05f7
120e9be
850ad31
2beb57b
52c2a87
5a4321a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
|
||
.. tip:: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. we could use |
||
|
||
We also have :doc:`a short article </templating/twig_extension_repository>` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
-------------------------- | ||
|
@@ -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 |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
.. index:: | ||
single: Using the Twig Extensions Repository | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can we change the title of this article? The There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Unfortunately, "The official Twig extensions" isn't very helpful either, rather misleading... There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "Using Twig extensions not provided as a bundle"...? Meh. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What about repeating what's below and just add "official":
|
||
======================================== | ||
|
||
The `Twig official extension repository`_ contains (as of writing) some | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The official Twig extensions repository [...] There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. So, it |
||
Symfony Framework (it is not a Bundle). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. framework There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The namespace should not have an "s" IMHO, what do others think? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I guess There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 } | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In Symfony, we usually don't have |
||
|
||
$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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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>`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
framework