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.

Sign up for GitHub

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

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2bf45c2
Add instructions on how to use the official Twig extensions repo
mpdude Mar 13, 2017
c7b05f7
Rename article and fix link
mpdude Mar 13, 2017
120e9be
Minor tweaks
mpdude Mar 13, 2017
850ad31
Fix markup/build warning
mpdude Mar 13, 2017
2beb57b
Use a service id that is more unlikely to cause collisions
mpdude Mar 13, 2017
52c2a87
Various GH feedback
mpdude Mar 14, 2017
5a4321a
Fix link
mpdude Mar 19, 2017
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
2 changes: 2 additions & 0 deletions templating/twig_extension.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ your code faster.
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 •
edited
Loading

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

Expand Down
15 changes: 7 additions & 8 deletions templating/twig_extension_repository.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
.. 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 Extension Repository
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
useful functions for internationalization, working with arrays and
dates. To learn more about these extensions, have a look at their
`documentation`_.

Expand Down Expand Up @@ -40,7 +40,7 @@ Then, define the extension class as a service and tag it with the

# app/config/services.yml
services:
twig_extension.intl:
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

Expand All @@ -55,7 +55,7 @@ Then, define the extension class as a service and tag it with the
http://symfony.com/schema/dic/services/services-1.0.xsd">

<services>
<service id="twig_extension.intl"
<service id="twig_extensions.intl"
class="Twig_Extensions_Extension_Intl">
<tag name="twig.extension" />
</service>
Expand All @@ -68,7 +68,7 @@ Then, define the extension class as a service and tag it with the
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_extension.intl', Twig_Extensions_Extension_Intl::class)
->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
Expand All @@ -84,10 +84,9 @@ Learning further

In the :doc:`reference section </reference/twig_reference>`, you can
find all the extra Twig functions, filters, tags and tests that are
added by the Symfony Framework.
already added by the Symfony Framework.

When that does not meet your particular needs, we also have
documentation on :doc:`how to write your own Twig extension </templating/twig_extension>`.
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/