.. index:: single: Symfony Twig extensions Twig Extensions Defined by Symfony ================================== :ref:`Twig ` is the template engine used in Symfony applications. There are tens of `default filters and functions defined by Twig`_, but Symfony also defines some filters, functions and tags to integrate the various Symfony components with Twig templates. This article explains them all. .. tip:: If these extensions provided by Symfony are not enough, you can :doc:`create a custom Twig extension ` to define even more filters and functions. .. _reference-twig-functions: Functions --------- .. _reference-twig-function-render: render ~~~~~~ .. code-block:: twig {{ render(uri, options = []) }} ``uri`` **type**: ``string`` | ``ControllerReference`` ``options`` *(optional)* **type**: ``array`` **default**: ``[]`` Makes a request to the given internal URI or controller and returns the result. The render strategy can be specified in the ``strategy`` key of the options. It's commonly used to :ref:`embed controllers in templates `. .. _reference-twig-function-render-esi: render_esi ~~~~~~~~~~ .. code-block:: twig {{ render_esi(uri, options = []) }} ``uri`` **type**: ``string`` | ``ControllerReference`` ``options`` *(optional)* **type**: ``array`` **default**: ``[]`` It's similar to the `render`_ function and defines the same arguments. However, it generates an ESI tag when :doc:`ESI support ` is enabled or falls back to the behavior of `render`_ otherwise. .. tip:: The ``render_esi()`` function is an example of the shortcut functions of ``render``. It automatically sets the strategy based on what's given in the function name, e.g. ``render_hinclude()`` will use the hinclude.js strategy. This works for all ``render_*()`` functions. controller ~~~~~~~~~~ .. code-block:: twig {{ controller(controller, attributes = [], query = []) }} ``controller`` **type**: ``string`` ``attributes`` *(optional)* **type**: ``array`` **default**: ``[]`` ``query`` *(optional)* **type**: ``array`` **default**: ``[]`` Returns an instance of ``ControllerReference`` to be used with functions like :ref:`render() ` and :ref:`render_esi() `. .. _reference-twig-function-asset: asset ~~~~~ .. code-block:: twig {{ asset(path, packageName = null) }} ``path`` **type**: ``string`` ``packageName`` *(optional)* **type**: ``string`` | ``null`` **default**: ``null`` Returns the public path of the given asset path (which can be a CSS file, a JavaScript file, an image path, etc.). This function takes into account where the application is installed (e.g. in case the project is accessed in a host subdirectory) and the optional asset package base path. Symfony provides various cache busting implementations via the :ref:`reference-framework-assets-version`, :ref:`reference-assets-version-strategy`, and :ref:`reference-assets-json-manifest-path` configuration options. .. seealso:: Read more about :ref:`linking to web assets from templates `. asset_version ~~~~~~~~~~~~~~ .. code-block:: twig {{ asset_version(packageName = null) }} ``packageName`` *(optional)* **type**: ``string`` | ``null`` **default**: ``null`` Returns the current version of the package, more information in :ref:`templates-link-to-assets`. .. _reference-twig-function-csrf-token: csrf_token ~~~~~~~~~~ .. code-block:: twig {{ csrf_token(intention) }} ``intention`` **type**: ``string`` - an arbitrary string used to identify the token. Renders a CSRF token. Use this function if you want :doc:`CSRF protection ` in a regular HTML form not managed by the Symfony Form component. is_granted ~~~~~~~~~~ .. code-block:: twig {{ is_granted(role, object = null, field = null) }} ``role`` **type**: ``string``, ``string[]`` ``object`` *(optional)* **type**: ``object`` ``field`` *(optional)* **type**: ``string`` Returns ``true`` if the current user has the given role. If several roles are passed in an array, ``true`` is returned if the user has at least one of them. Optionally, an object can be passed to be used by the voter. More information can be found in :ref:`security-template`. logout_path ~~~~~~~~~~~ .. code-block:: twig {{ logout_path(key = null) }} ``key`` *(optional)* **type**: ``string`` Generates a relative logout URL for the given firewall. If no key is provided, the URL is generated for the current firewall the user is logged into. logout_url ~~~~~~~~~~ .. code-block:: twig {{ logout_url(key = null) }} ``key`` *(optional)* **type**: ``string`` Equal to the `logout_path`_ function, but it'll generate an absolute URL instead of a relative one. path ~~~~ .. code-block:: twig {{ path(route_name, route_parameters = [], relative = false) }} ``name`` **type**: ``string`` ``parameters`` *(optional)* **type**: ``array`` **default**: ``[]`` ``relative`` *(optional)* **type**: ``boolean`` **default**: ``false`` Returns the relative URL (without the scheme and host) for the given route. If ``relative`` is enabled, it'll create a path relative to the current path. .. seealso:: Read more about :doc:`Symfony routing ` and about :ref:`creating links in Twig templates `. url ~~~ .. code-block:: twig {{ url(route_name, route_parameters = [], schemeRelative = false) }} ``name`` **type**: ``string`` ``parameters`` *(optional)* **type**: ``array`` **default**: ``[]`` ``schemeRelative`` *(optional)* **type**: ``boolean`` **default**: ``false`` Returns the absolute URL (with scheme and host) for the given route. If ``schemeRelative`` is enabled, it'll create a scheme-relative URL. .. seealso:: Read more about :doc:`Symfony routing ` and about :ref:`creating links in Twig templates `. absolute_url ~~~~~~~~~~~~ .. code-block:: twig {{ absolute_url(path) }} ``path`` **type**: ``string`` Returns the absolute URL (with scheme and host) from the passed relative path. Combine it with the :ref:`asset() function ` to generate absolute URLs for web assets. Read more about :ref:`Linking to CSS, JavaScript and Image Assets `. relative_path ~~~~~~~~~~~~~ .. code-block:: twig {{ relative_path(path) }} ``path`` **type**: ``string`` Returns the relative path from the passed absolute URL. For example, assume you're on the following page in your app: ``http://example.com/products/hover-board``. .. code-block:: twig {{ relative_path('http://example.com/human.txt') }} {# ../human.txt #} {{ relative_path('http://example.com/products/products_icon.png') }} {# products_icon.png #} expression ~~~~~~~~~~ Creates an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` related to the :doc:`ExpressionLanguage component `. Form Related Functions ~~~~~~~~~~~~~~~~~~~~~~ The following functions related to Symfony Forms are also available. They are explained in the article about :doc:`customizing form rendering `: * :ref:`form() ` * :ref:`form_start() ` * :ref:`form_end() ` * :ref:`form_widget() ` * :ref:`form_errors() ` * :ref:`form_label() ` * :ref:`form_help() ` * :ref:`form_row() ` * :ref:`form_rest() ` .. _reference-twig-filters: Filters ------- .. _reference-twig-humanize-filter: humanize ~~~~~~~~ .. code-block:: twig {{ text|humanize }} ``text`` **type**: ``string`` Makes a technical name human readable (i.e. replaces underscores by spaces or transforms camelCase text like ``helloWorld`` to ``hello world`` and then capitalizes the string). trans ~~~~~ .. code-block:: twig {{ message|trans(arguments = [], domain = null, locale = null) }} ``message`` **type**: ``string`` ``arguments`` *(optional)* **type**: ``array`` **default**: ``[]`` ``domain`` *(optional)* **type**: ``string`` **default**: ``null`` ``locale`` *(optional)* **type**: ``string`` **default**: ``null`` Translates the text into the current language. More information in :ref:`Translation Filters `. yaml_encode ~~~~~~~~~~~ .. code-block:: twig {{ input|yaml_encode(inline = 0, dumpObjects = false) }} ``input`` **type**: ``mixed`` ``inline`` *(optional)* **type**: ``integer`` **default**: ``0`` ``dumpObjects`` *(optional)* **type**: ``boolean`` **default**: ``false`` Transforms the input into YAML syntax. See :ref:`components-yaml-dump` for more information. yaml_dump ~~~~~~~~~ .. code-block:: twig {{ value|yaml_dump(inline = 0, dumpObjects = false) }} ``value`` **type**: ``mixed`` ``inline`` *(optional)* **type**: ``integer`` **default**: ``0`` ``dumpObjects`` *(optional)* **type**: ``boolean`` **default**: ``false`` Does the same as `yaml_encode() `_, but includes the type in the output. abbr_class ~~~~~~~~~~ .. code-block:: twig {{ class|abbr_class }} ``class`` **type**: ``string`` Generates an ```` element with the short name of a PHP class (the FQCN will be shown in a tooltip when a user hovers over the element). abbr_method ~~~~~~~~~~~ .. code-block:: twig {{ method|abbr_method }} ``method`` **type**: ``string`` Generates an ```` element using the ``FQCN::method()`` syntax. If ``method`` is ``Closure``, ``Closure`` will be used instead and if ``method`` doesn't have a class name, it's shown as a function (``method()``). format_args ~~~~~~~~~~~ .. code-block:: twig {{ args|format_args }} ``args`` **type**: ``array`` Generates a string with the arguments and their types (within ```` elements). format_args_as_text ~~~~~~~~~~~~~~~~~~~ .. code-block:: twig {{ args|format_args_as_text }} ``args`` **type**: ``array`` Equal to the `format_args`_ filter, but without using HTML tags. file_excerpt ~~~~~~~~~~~~ .. code-block:: twig {{ file|file_excerpt(line, srcContext = 3) }} ``file`` **type**: ``string`` ``line`` **type**: ``integer`` ``srcContext`` *(optional)* **type**: ``integer`` Generates an excerpt of a code file around the given ``line`` number. The ``srcContext`` argument defines the total number of lines to display around the given line number (use ``-1`` to display the whole file). format_file ~~~~~~~~~~~ .. code-block:: twig {{ file|format_file(line, text = null) }} ``file`` **type**: ``string`` ``line`` **type**: ``integer`` ``text`` *(optional)* **type**: ``string`` **default**: ``null`` Generates the file path inside an ```` element. If the path is inside the kernel root directory, the kernel root directory path is replaced by ``kernel.project_dir`` (showing the full path in a tooltip on hover). format_file_from_text ~~~~~~~~~~~~~~~~~~~~~ .. code-block:: twig {{ text|format_file_from_text }} ``text`` **type**: ``string`` Uses `format_file`_ to improve the output of default PHP errors. file_link ~~~~~~~~~ .. code-block:: twig {{ file|file_link(line) }} ``file`` **type**: ``string`` ``line`` **type**: ``integer`` Generates a link to the provided file and line number using a preconfigured scheme. file_relative ~~~~~~~~~~~~~ .. code-block:: twig {{ file|file_relative }} ``file`` **type**: ``string`` It transforms the given absolute file path into a new file path relative to project's root directory: .. code-block:: twig {{ '/var/www/blog/templates/admin/index.html.twig'|file_relative }} {# if project root dir is '/var/www/blog/', it returns 'templates/admin/index.html.twig' #} If the given file path is out of the project directory, a ``null`` value will be returned. .. _reference-twig-tags: Tags ---- .. _reference-twig-tag-form-theme: form_theme ~~~~~~~~~~ .. code-block:: twig {% form_theme form resources %} ``form`` **type**: ``FormView`` ``resources`` **type**: ``array`` | ``string`` Sets the resources to override the form theme for the given form view instance. You can use ``_self`` as resources to set it to the current resource. More information in :doc:`/form/form_customization`. trans ~~~~~ .. code-block:: twig {% trans with vars from domain into locale %}{% endtrans %} ``vars`` *(optional)* **type**: ``array`` **default**: ``[]`` ``domain`` *(optional)* **type**: ``string`` **default**: ``string`` ``locale`` *(optional)* **type**: ``string`` **default**: ``string`` Renders the translation of the content. More information in :ref:`translation-tags`. trans_default_domain ~~~~~~~~~~~~~~~~~~~~ .. code-block:: twig {% trans_default_domain domain %} ``domain`` **type**: ``string`` This will set the default domain in the current template. stopwatch ~~~~~~~~~ .. code-block:: twig {% stopwatch 'name' %}...{% endstopwatch %} This will time the run time of the code inside it and put that on the timeline of the WebProfilerBundle. .. _reference-twig-tests: Tests ----- The following tests related to Symfony Forms are available. They are explained in the article about :doc:`customizing form rendering `: * :ref:`selectedchoice() ` * :ref:`rootform() ` Global Variables ---------------- app ~~~ The ``app`` variable is injected automatically by Symfony in all templates and provides access to lots of useful application information. Read more about the :ref:`Twig global app variable `. .. _`default filters and functions defined by Twig`: https://twig.symfony.com/doc/2.x/#reference