Twig
====

The *TwigServiceProvider* provides integration with the `Twig
<http://twig.sensiolabs.org/>`_ template engine.

Parameters
----------

* **twig.path** (optional): Path to the directory containing twig template
  files (it can also be an array of paths).

* **twig.templates** (optional): An associative array of template names to
  template contents. Use this if you want to define your templates inline.

* **twig.options** (optional): An associative array of twig
  options. Check out the `twig documentation <http://twig.sensiolabs.org/doc/api.html#environment-options>`_
  for more information.

* **twig.form.templates** (optional): An array of templates used to render
  forms (only available when the ``FormServiceProvider`` is enabled). The
  default theme is ``form_div_layout.html.twig``, but you can use the other
  built-in themes: ``form_table_layout.html.twig``,
  ``bootstrap_3_layout.html.twig``, and
  ``bootstrap_3_horizontal_layout.html.twig``.

* **twig.date.format** (optional): Default format used by the ``date``
  filter. The format string must conform to the format accepted by
  `date() <http://www.php.net/date>`_.

* **twig.date.interval_format** (optional): Default format used by the
  ``date`` filter when the filtered data is of type `DateInterval <http://www.php.net/DateInterval>`_.
  The format string must conform to the format accepted by
  `DateInterval::format() <http://www.php.net/DateInterval.format>`_.

* **twig.date.timezone** (optional): Default timezone used when formatting
  dates. If set to ``null`` the timezone returned by `date_default_timezone_get() <http://www.php.net/date_default_timezone_get>`_
  is used.

* **twig.number_format.decimals** (optional): Default number of decimals
  displayed by the ``number_format`` filter.

* **twig.number_format.decimal_point** (optional): Default separator for
  the decimal point used by the ``number_format`` filter.

* **twig.number_format.thousands_separator** (optional): Default thousands
  separator used by the ``number_format`` filter.

Services
--------

* **twig**: The ``\Twig\Environment`` instance. The main way of
  interacting with Twig.

* **twig.loader**: The loader for Twig templates which uses the ``twig.path``
  and the ``twig.templates`` options. You can also replace the loader
  completely.

Registering
-----------

.. code-block:: php

    $app->register(new Silex\Provider\TwigServiceProvider(), array(
        'twig.path' => __DIR__.'/views',
    ));

.. note::

    Add Twig as a dependency:

    .. code-block:: bash

        composer require twig/twig

Usage
-----

The Twig provider provides a ``twig`` service that can render templates::

    $app->get('/hello/{name}', function ($name) use ($app) {
        return $app['twig']->render('hello.twig', array(
            'name' => $name,
        ));
    });

Symfony Components Integration
------------------------------

Symfony provides a Twig bridge that provides additional integration between
some Symfony components and Twig. Add it as a dependency:

.. code-block:: bash

    composer require symfony/twig-bridge

When present, the ``TwigServiceProvider`` will provide you with the following
additional capabilities.

* Access to the ``path()`` and ``url()`` functions. You can find more
  information in the `Symfony Routing documentation
  <http://symfony.com/doc/current/book/routing.html#generating-urls-from-a-template>`_:

  .. code-block:: jinja

      {{ path('homepage') }}
      {{ url('homepage') }} {# generates the absolute url http://example.org/ #}
      {{ path('hello', {name: 'Fabien'}) }}
      {{ url('hello', {name: 'Fabien'}) }} {# generates the absolute url http://example.org/hello/Fabien #}

* Access to the ``absolute_url()`` and ``relative_path()`` Twig functions.

Translations Support
~~~~~~~~~~~~~~~~~~~~

If you are using the ``TranslationServiceProvider``, you will get the
``trans()`` and ``transchoice()`` functions for translation in Twig templates.
You can find more information in the `Symfony Translation documentation
<http://symfony.com/doc/current/book/translation.html#twig-templates>`_.

Form Support
~~~~~~~~~~~~

If you are using the ``FormServiceProvider``, you will get a set of helpers for
working with forms in templates. You can find more information in the `Symfony
Forms reference
<http://symfony.com/doc/current/reference/forms/twig_reference.html>`_.

Security Support
~~~~~~~~~~~~~~~~

If you are using the ``SecurityServiceProvider``, you will have access to the
``is_granted()`` function in templates. You can find more information in the
`Symfony Security documentation
<http://symfony.com/doc/current/book/security.html#access-control-in-templates>`_.

Web Link Support
~~~~~~~~~~~~~~~~

If you are using the ``symfony/web-link`` component, you will have access to the
``preload()``, ``prefetch()``, ``prerender()``, ``dns_prefetch()``,
``preconnect()`` and ``link()`` functions in templates. You can find more
information in the `Symfony WebLink documentation
<https://symfony.com/doc/current/components/weblink/introduction.html>`_.

Global Variable
~~~~~~~~~~~~~~~

When the Twig bridge is available, the ``global`` variable refers to an
instance of `AppVariable <http://api.symfony.com/master/Symfony/Bridge/Twig/AppVariable.html>`_.
It gives access to the following methods:

.. code-block:: jinja

    {# The current Request #}
    {{ global.request }}

    {# The current User (when security is enabled) #}
    {{ global.user }}

    {# The current Session #}
    {{ global.session }}

    {# The debug flag #}
    {{ global.debug }}

    {# The flash messages (Symfony 3.3 or later) #}
    {{ global.flashes }}

Rendering a Controller
~~~~~~~~~~~~~~~~~~~~~~

A ``render`` function is also registered to help you render another controller
from a template (available when the :doc:`HttpFragment Service Provider
</providers/http_fragment>` is registered):

.. code-block:: jinja

    {{ render(url('sidebar')) }}

    {# or you can reference a controller directly without defining a route for it #}
    {{ render(controller(controller)) }}

.. note::

    You must prepend the ``app.request.baseUrl`` to render calls to ensure
    that the render works when deployed into a sub-directory of the docroot.

.. note::

    Read the Twig `reference`_ for Symfony document to learn more about the
    various Twig functions.

Traits
------

``Silex\Application\TwigTrait`` adds the following shortcuts:

* **render**: Renders a view with the given parameters and returns a Response
  object.

.. code-block:: php

    return $app->render('index.html', ['name' => 'Fabien']);

    $response = new Response();
    $response->setTtl(10);

    return $app->render('index.html', ['name' => 'Fabien'], $response);

.. code-block:: php

    // stream a view
    use Symfony\Component\HttpFoundation\StreamedResponse;

    return $app->render('index.html', ['name' => 'Fabien'], new StreamedResponse());

* **renderView**: Renders a view with the given parameters and returns a string.

.. code-block:: php

    $content = $app->renderView('index.html', ['name' => 'Fabien']);

Customization
-------------

You can configure the Twig environment before using it by extending the
``twig`` service::

    $app->extend('twig', function($twig, $app) {
        $twig->addGlobal('pi', 3.14);
        $twig->addFilter('levenshtein', new \Twig_Filter_Function('levenshtein'));

        return $twig;
    });

For more information, check out the `official Twig documentation
<http://twig.sensiolabs.org>`_.

.. _reference: https://symfony.com/doc/current/reference/twig_reference.html#controller