Merge branch '4.4'

* 4.4:
  Reworded all the docs related to templates and Twig

Author: javiereguiluz

_build/redirection_map

@@ -447,3 +447,13 @@
 /form/action_method /forms
 /reference/requirements /setup
  /bundles/inheritance /bundles/override
+/templating /templates
+/templating/escaping /templates
+/templating/syntax /templates
+/templating/debug /templates
+/templating/render_without_controller /templates
+/templating/app_variable /templates
+/templating/formats /templates
+/templating/namespaced_paths /templates
+/templating/embedding_controllers /templates
+/templating/inheritance /templates

components/http_foundation.rst

@@ -57,6 +57,8 @@ which is almost equivalent to the more verbose, but also more flexible,
         $_SERVER
     );
 
+.. _accessing-request-data:
+
 Accessing Request Data
 ~~~~~~~~~~~~~~~~~~~~~~
 

components/templating.rst

@@ -28,8 +28,8 @@ Usage
 .. seealso::
 
     This article explains how to use the Templating features as an independent
-    component in any PHP application. Read the :doc:`/templating` article to
-    learn about how to work with templates in Symfony applications.
+    component in any PHP application. Read the article about :doc:`templates </templates>`
+    to learn about how to work with templates in Symfony applications.
 
 The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
 of the component. It needs a
@@ -211,5 +211,5 @@ Learn More
     :glob:
 
     /components/templating/*
-    /templating
+    /templates
     /templating/*

configuration/front_controllers_and_kernel.rst

@@ -123,6 +123,8 @@ new kernel.
 .. index::
    single: Configuration; Debug mode
 
+.. _debug-mode:
+
 Debug Mode
 ~~~~~~~~~~
 

controller.rst

@@ -179,7 +179,7 @@ object for you::
     return $this->render('lucky/number.html.twig', ['number' => $number]);
 
 Templating and Twig are explained more in the
-:doc:`Creating and Using Templates article </templating>`.
+:doc:`Creating and Using Templates article </templates>`.
 
 .. index::
    single: Controller; Accessing services
@@ -461,7 +461,8 @@ and then redirects. The message key (``notice`` in this example) can be anything
 you'll use this key to retrieve the message.
 
 In the template of the next page (or even better, in your base layout template),
-read any flash messages from the session using ``app.flashes()``:
+read any flash messages from the session using the ``flashes()`` method provided
+by the :ref:`Twig global app variable <twig-app-variable>`:
 
 .. code-block:: html+twig
 
@@ -650,15 +651,15 @@ handle caching and more.
 Keep Going!
 -----------
 
-Next, learn all about :doc:`rendering templates with Twig </templating>`.
+Next, learn all about :doc:`rendering templates with Twig </templates>`.
 
 Learn more about Controllers
 ----------------------------
 
 .. toctree::
     :hidden:
 
-    templating
+    templates
 
 .. toctree::
     :maxdepth: 1

event_dispatcher.rst

@@ -200,9 +200,9 @@ Request Events, Checking Types
 ------------------------------
 
 A single page can make several requests (one master request, and then multiple
-sub-requests - typically by :doc:`/templating/embedding_controllers`). For the core
-Symfony events, you might need to check to see if the event is for a "master" request
-or a "sub request"::
+sub-requests - typically when :ref:`embedding controllers in templates <templates-embed-controllers>`).
+For the core Symfony events, you might need to check to see if the event is for
+a "master" request or a "sub request"::
 
     // src/EventListener/RequestListener.php
     namespace App\EventListener;

getting_started/index.rst

@@ -8,5 +8,5 @@ Getting Started
     /page_creation
     /routing
     /controller
-    /templating
+    /templates
     /configuration

http_cache/esi.rst

@@ -114,8 +114,8 @@ independently of the rest of the page::
 
 In this example, the full-page cache has a lifetime of ten minutes.
 Next, include the news ticker in the template by embedding an action.
-This is done via the ``render`` helper (see :doc:`/templating/embedding_controllers`
-for more details).
+This is done via the ``render()`` helper (for more details, see how to
+:ref:`embed controllers in templates <templates-embed-controllers>`).
 
 As the embedded content comes from another page (or controller for that
 matter), Symfony uses the standard ``render`` helper to configure ESI tags:

introduction/from_flat_php_to_symfony.rst

@@ -532,7 +532,7 @@ a simple application. Along the way, you've made a simple routing
 system and a method using ``ob_start()`` and ``ob_get_clean()`` to render
 templates. If, for some reason, you needed to continue building this "framework"
 from scratch, you could at least use Symfony's standalone
-:doc:`Routing </components/routing>` component and :doc:`Twig </templating>`,
+:doc:`Routing </components/routing>` component and :doc:`Twig </templates>`,
 which already solve these problems.
 
 Instead of re-solving common problems, you can let Symfony take care of

mailer.rst

@@ -284,7 +284,7 @@ create an event subscriber to set it automatically::
 Twig: HTML & CSS
 ----------------
 
-The Mime component integrates with the :doc:`Twig template engine </templating>`
+The Mime component integrates with the :ref:`Twig template engine <twig-language>`
 to provide advanced features such as CSS style inlining and support for HTML/CSS
 frameworks to create complex HTML email messages. First, make sure Twig is installed:
 

page_creation.rst

@@ -251,8 +251,8 @@ Now you may wonder where the Web Debug Toolbar has gone: that's because there is
 no ``</body>`` tag in the current template. You can add the body element yourself,
 or extend ``base.html.twig``, which contains all default HTML elements.
 
-In the :doc:`/templating` article, you'll learn all about Twig: how to loop, render
-other templates and leverage its powerful layout inheritance system.
+In the :doc:`templates </templates>` article, you'll learn all about Twig: how
+to loop, render other templates and leverage its powerful layout inheritance system.
 
 Checking out the Project Structure
 ----------------------------------
@@ -304,7 +304,7 @@ Ok, time to finish mastering the fundamentals by reading these articles:
 
 * :doc:`/routing`
 * :doc:`/controller`
-* :doc:`/templating`
+* :doc:`/templates`
 * :doc:`/configuration`
 
 Then, learn about other important topics like the

reference/configuration/twig.rst

@@ -5,8 +5,8 @@ Twig Configuration Reference (TwigBundle)
 =========================================
 
 The TwigBundle integrates the Twig library in Symfony applications to
-:doc:`render templates </templating>`. All these options are configured under
-the ``twig`` key in your application configuration.
+:ref:`render templates <templates-rendering>`. All these options are configured
+under the ``twig`` key in your application configuration.
 
 .. code-block:: terminal
 
@@ -41,8 +41,10 @@ Configuration
   * `timezone`_
 
 * `debug`_
+* `default_path`_
 * `exception_controller`_
 * `form_themes`_
+* `globals`_
 * `number_format`_
 
   * `decimals`_
@@ -62,6 +64,8 @@ If ``true``, whenever a template is rendered, Symfony checks first if its source
 code has changed since it was compiled. If it has changed, the template is
 compiled again automatically.
 
+.. _config-twig-autoescape:
+
 autoescape
 ~~~~~~~~~~
 
@@ -73,7 +77,7 @@ individually in the templates).
 .. caution::
 
     Setting this option to ``false`` is dangerous and it will make your
-    application vulnerable to XSS exploits because most third-party bundles
+    application vulnerable to `XSS attacks`_ because most third-party bundles
     assume that auto-escaping is enabled and they don't escape contents
     themselves.
 
@@ -139,8 +143,8 @@ charset
 **type**: ``string`` **default**: ``'%kernel.charset%'``
 
 The charset used by the template files. By default it's the same as the value of
-the ``kernel.charset`` container parameter, which is ``UTF-8`` by default in
-Symfony applications.
+the :ref:`kernel.charset container parameter <configuration-kernel-charset>`,
+which is ``UTF-8`` by default in Symfony applications.
 
 date
 ~~~~
@@ -181,6 +185,17 @@ debug
 If ``true``, the compiled templates include a ``__toString()`` method that can
 be used to display their nodes.
 
+.. _config-twig-default-path:
+
+default_path
+~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``'%kernel.project_dir%/templates'``
+
+The path to the directory where Symfony will look for the application Twig
+templates by default. If you store the templates in more than one directory, use
+the :ref:`paths <config-twig-paths>`  option too.
+
 .. _config-twig-exception-controller:
 
 exception_controller
@@ -195,7 +210,8 @@ is what's responsible for rendering specific templates under different error
 conditions (see :doc:`/controller/error_pages`). Modifying this
 option is advanced. If you need to customize an error page you should use
 the previous link. If you need to perform some behavior on an exception,
-you should add a listener to the ``kernel.exception`` event (see :ref:`dic-tags-kernel-event-listener`).
+you should add an :doc:`event listener </event_dispatcher>` to the
+:ref:`kernel.exception event <kernel-kernel.exception>`.
 
 .. _config-twig-form-themes:
 
@@ -253,6 +269,14 @@ These global themes are applied to all forms, even those which use the
 :ref:`form_theme Twig tag <reference-twig-tag-form-theme>`, but you can
 :ref:`disable global themes for specific forms <disabling-global-themes-for-single-forms>`.
 
+globals
+~~~~~~~
+
+**type**: ``array`` **default**: ``[]``
+
+It defines the global variables injected automatically into all Twig templates.
+Learn more about :doc:`Twig global variables </templating/global_variables>`.
+
 number_format
 ~~~~~~~~~~~~~
 
@@ -301,32 +325,15 @@ on. Set it to ``0`` to disable all the optimizations. You can even enable or
 disable these optimizations selectively, as explained in the Twig documentation
 about `the optimizer extension`_.
 
-.. _config-twig-default-path:
-
-default_path
-~~~~~~~~~~~~
-
-**type**: ``string`` **default**: ``'%kernel.project_dir%/templates'``
-
-The default directory where Symfony will look for Twig templates.
-
 .. _config-twig-paths:
 
 paths
 ~~~~~
 
 **type**: ``array`` **default**: ``null``
 
-This option defines the directories where Symfony will look for Twig templates
-in addition to the default locations. Symfony looks for the templates in the
-following order:
-
-#. The directories defined in this option;
-#. The ``Resources/views/`` directories of the bundles used in the application;
-#. The directory defined in the ``default_path`` option.
-
-The values of the ``paths`` option are defined as ``key: value`` pairs where the
-``value`` part can be ``null``. For example:
+Defines the directories where application templates are stored in addition to
+the directory defined in the :ref:`default_path option <config-twig-default-path>`:
 
 .. configuration-block::
 
@@ -336,7 +343,8 @@ The values of the ``paths`` option are defined as ``key: value`` pairs where the
         twig:
             # ...
             paths:
-                '%kernel.project_dir%/vendor/acme/foo-bar/templates': ~
+                'email/default/templates': ~
+                'backend/templates': 'admin'
 
     .. code-block:: xml
 
@@ -350,7 +358,8 @@ The values of the ``paths`` option are defined as ``key: value`` pairs where the
 
             <twig:config>
                 <!-- ... -->
-                <twig:path>%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
+                <twig:path>email/default/templates</twig:path>
+                <twig:path namespace="admin">backend/templates</twig:path>
             </twig:config>
         </container>
 
@@ -360,60 +369,12 @@ The values of the ``paths`` option are defined as ``key: value`` pairs where the
         $container->loadFromExtension('twig', [
             // ...
             'paths' => [
-                '%kernel.project_dir%/vendor/acme/foo-bar/templates' => null,
+                'email/default/templates' => null,
+                'backend/templates' => 'admin',
             ],
         ]);
 
-The directories defined in the ``paths`` option have more priority than the
-default directories defined by Symfony. In the above example, if the template
-exists in the ``acme/foo-bar/templates/`` directory inside your application's
-``vendor/``, it will be used by Symfony.
-
-If you provide a value for any path, Symfony will consider it the Twig namespace
-for that directory:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/twig.yaml
-        twig:
-            # ...
-            paths:
-                '%kernel.project_dir%/vendor/acme/foo-bar/templates': 'foo_bar'
-
-    .. code-block:: xml
-
-        <!-- config/packages/twig.xml -->
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:twig="http://symfony.com/schema/dic/twig"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                https://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
-
-            <twig:config>
-                <!-- ... -->
-                <twig:path namespace="foo_bar">%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
-            </twig:config>
-        </container>
-
-    .. code-block:: php
-
-        # config/packages/twig.php
-        $container->loadFromExtension('twig', [
-            // ...
-            'paths' => [
-                '%kernel.project_dir%/vendor/acme/foo-bar/templates' => 'foo_bar',
-            ],
-        ]);
-
-This option is useful to not mess with the default template directories defined
-by Symfony. Besides, it simplifies how you refer to those templates:
-
-.. code-block:: text
-
-    @foo_bar/template_name.html.twig
+Read more about :ref:`template directories and namespaces <templates-namespaces>`.
 
 strict_variables
 ~~~~~~~~~~~~~~~~
@@ -425,3 +386,4 @@ attribute or method doesn't exist. If set to ``false`` these errors are ignored
 and the non-existing values are replaced by ``null``.
 
 .. _`the optimizer extension`: https://twig.symfony.com/doc/2.x/api.html#optimizer-extension
+.. _`XSS attacks`: https://en.wikipedia.org/wiki/Cross-site_scripting