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

mpdude · 2017-03-13T09:11:35Z

There are several references to the official Twig extensions repository, but we don't mention how easy it actually is to use that.

When #7613 is merged we also should update the notes added there to include a reference to this new section.

xabbuh · 2017-03-13T09:19:33Z

templating/twig_extension.rst

+    from having a look at the `Twig Bridge`_  which contains most of
+    the extensions provided by the Symfony Framework.
+
+    We also have :doc:`a short article </reference/using_twig_extension_repository>`


/templating/using_twig_extension_repository

maybe we should also rename the new file to something shorter like /templating/twig_extension_repository

HeahDude · 2017-03-13T16:31:57Z

templating/twig_extension_repository.rst

@@ -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:


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

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?

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

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.

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.

xabbuh · 2017-03-14T08:11:15Z

templating/twig_extension.rst

+    from having a look at the `Twig Bridge`_  which contains most of
+    the extensions provided by the Symfony Framework.
+
+.. tip::


we could use .. seealso:: instead here

xabbuh · 2017-03-14T08:11:27Z

templating/twig_extension.rst

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


xabbuh · 2017-03-14T08:12:01Z

templating/twig_extension.rst

+
+.. tip::
+
+    We also have :doc:`a short article </templating/twig_extension_repository>`


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

xabbuh · 2017-03-14T08:12:47Z

templating/twig_extension_repository.rst

+How to Use the Twig Extensions Repository
+=========================================
+
+The `Twig official extension repository`_ contains (as of writing) some


The official Twig extensions repository [...]

I think we can drop the "as of writing" part

xabbuh · 2017-03-14T08:13:34Z

templating/twig_extension_repository.rst

+`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


So, it is does not [...]

xabbuh · 2017-03-14T08:13:42Z

templating/twig_extension_repository.rst

+
+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
+Symfony Framework (it is not a Bundle).


xabbuh · 2017-03-14T08:13:54Z

templating/twig_extension_repository.rst

+is 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.


xabbuh · 2017-03-14T08:15:17Z

templating/twig_extension_repository.rst

+    the right class name.
+
+First, add the Twig Extensions repository as a dependency in your
+project. Assuming you are using Composer, run


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".

xabbuh · 2017-03-14T08:16:11Z

templating/twig_extension_repository.rst

+    .. code-block:: php
+
+        // app/config/services.php
+        use \Twig_Extensions_Extension_Intl;


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

xabbuh · 2017-03-14T08:16:34Z

templating/twig_extension_repository.rst

+
+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:


[...] to the current request's locale

xabbuh · 2017-03-14T08:17:11Z

templating/twig_extension_repository.rst

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


first person :)

xabbuh · 2017-03-14T08:17:26Z

templating/twig_extension_repository.rst

+            app.twig_extensions.intl:
+                class: Twig_Extensions_Extension_Intl
+                tags:
+                    - { name: twig.extension }


maybe also mark the service as private

mpdude · 2017-03-14T09:29:49Z

@xabbuh Thanks for the thorough review, all fixed!

mpdude · 2017-03-18T20:32:57Z

@HeahDude / @xabbuh any other wishes/remarks?

xabbuh · 2017-03-19T20:30:17Z

templating/twig_extension_repository.rst

+How to Use the Twig Extensions Repository
+=========================================
+
+The `Twig official extensions repository`_ contains some


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

Fixed link below

xabbuh · 2017-03-19T20:48:10Z

👍 the build is passing now :)

Status: Reviewed

javiereguiluz · 2017-03-19T20:50:44Z

templating/twig_extension_repository.rst

+.. index::
+   single: Using the Twig Extensions Repository
+
+How to Use the Twig Extensions Repository


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.

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

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

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

How to Use the Twig Official Extensions

javiereguiluz · 2017-03-19T20:52:16Z

templating/twig_extension_repository.rst

@@ -0,0 +1,93 @@
+.. index::
+   single: Using the Twig Extensions Repository


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.

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 :-).

mpdude · 2017-06-03T22:10:05Z

So guys, please decide if you'd merge this or not... If you want to, then I will have a look at the conflicts.

robfrawley · 2017-06-03T22:25:48Z

👍 for adding this documentation of the "Official Twig Extension" usage.

weaverryan · 2017-10-29T02:40:27Z

Sorry for the delay on this @mpdude - it's a good PR as usual from you. Because things have changed (I'm talking about the introduction to Flex), my vote would be to not merge this. Well, actually, I do think we should mention (somewhere) that this library exists with details on how to install it. But in Flex, it's as simple as running composer require and then un-commenting the extension you want.

So, should we merge this PR to older branches, or just update it with the simpler instructions and merge to master?

mpdude · 2017-10-29T14:33:45Z

Let's look ahead and not merge into old branches.

However, I haven't yet worked with Flex myself, so I am unsure if I can be of any help here?

weaverryan · 2017-10-29T17:03:20Z

@mpdude I tend to agree :). When you install the twig extensions repo in flex, you're given this file: https://github.com/symfony/recipes/blob/master/twig/extensions/1.0/config/packages/twig_extensions.yaml. So basically, the user only needs to go to this file and uncomment the extensions they want :). I think updating this PR (and just removing the stuff that's not needed anymore) is the easiest way forward.

javiereguiluz · 2018-01-11T15:53:43Z

To move things forward, I propose to close this in favor of #9035. Thanks!

This PR was merged into the 4.0 branch. Discussion ---------- Mention the official Twig extensions This finishes #7616 in a more concise way now that we can assume that the app is using Flex. Commits ------- 0084f14 Mention the official Twig extensions

Add instructions on how to use the official Twig extensions repo

2bf45c2

carsonbot added the Status: Needs Review label Mar 13, 2017

xabbuh reviewed Mar 13, 2017

View reviewed changes

Rename article and fix link

c7b05f7

mpdude force-pushed the cookbook_twig_extensions branch from aabaced to 120e9be Compare March 13, 2017 12:43

mpdude added 2 commits March 13, 2017 13:43

Minor tweaks

120e9be

Fix markup/build warning

850ad31

HeahDude reviewed Mar 13, 2017

View reviewed changes

Use a service id that is more unlikely to cause collisions

2beb57b

xabbuh reviewed Mar 14, 2017

View reviewed changes

Various GH feedback

52c2a87

roman-1983 approved these changes Mar 15, 2017

View reviewed changes

xabbuh reviewed Mar 19, 2017

View reviewed changes

Fix link

5a4321a

carsonbot added Status: Reviewed and removed Status: Needs Review labels Mar 19, 2017

javiereguiluz reviewed Mar 19, 2017

View reviewed changes

javiereguiluz added this to the 4.0 milestone Jan 11, 2018

javiereguiluz mentioned this pull request Jan 11, 2018

Mention the official Twig extensions #9035

Merged

javiereguiluz closed this Jan 11, 2018

mpdude deleted the cookbook_twig_extensions branch January 11, 2018 17:31


		.. tip::

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

		@@ -0,0 +1,93 @@
		.. index::
		single: Using the Twig Extensions Repository

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

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

Conversation

mpdude commented Mar 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xabbuh Mar 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xabbuh Mar 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mpdude commented Mar 14, 2017

mpdude commented Mar 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xabbuh commented Mar 19, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mpdude commented Jun 3, 2017

robfrawley commented Jun 3, 2017

weaverryan commented Oct 29, 2017

mpdude commented Oct 29, 2017

weaverryan commented Oct 29, 2017

javiereguiluz commented Jan 11, 2018

xabbuh Mar 14, 2017 •

edited

Loading

xabbuh Mar 14, 2017 •

edited

Loading