Symfony Twig Extensions

Warning: You are browsing the documentation for Symfony 2.x, which is no longer maintained.

Read the updated version of this page for Symfony 7.1 (the current stable version).

Twig is the default template engine for Symfony. By itself, it already contains a lot of built-in functions, filters, tags and tests. You can learn more about them from the Twig Reference.

The Symfony framework adds quite a few extra functions, filters, tags and tests to seamlessly integrate the various Symfony components with Twig templates. The following sections describe these extra features.

Tip

Technically, most of the extensions live in the Twig Bridge. That code might give you some ideas when you need to write your own Twig extension as described in How to Write a custom Twig Extension.

Note

This reference only covers the Twig extensions provided by the Symfony framework. You are probably using some other bundles as well, and those might come with their own extensions not covered here.

Tip

The Twig Extensions repository contains some additional Twig extensions that do not belong to the Twig core, so you might want to have a look at the Twig Extensions documentation.

Functions

render

        1
        {{ 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. It's commonly used to embed controllers in templates.

        1
2
3
4
5
6
7
8
        {# if the controller is associated with a route, use the path() or
   url() functions to generate the URI used by render() #}
{{ render(path('latest_articles', {num: 5})) }}
{{ render(url('latest_articles', {num: 5})) }}

{# if you don't want to expose the controller with a public URL, use
   the controller() function to define the controller to be executed #}
{{ render(controller('AppBundle:Default:latestArticles', {num: 5})) }}
    

The render strategy can be specified in the strategy key of the options.

render_esi

        1
        {{ 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 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

        1
        {{ 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 render() and render_esi().

asset

        1
        {{ asset(path, packageName = null, absolute = false, version = null) }}
    

path: type: string
packageName (optional): type: string | null default: null
absolute (deprecated as of 2.7): type: boolean default: false
version (deprecated as of 2.7): type: string default null

Returns a public path to path, which takes into account the base path set for the package and the URL path. More information in Creating and Using Templates. For asset versioning, see Framework Configuration Reference (FrameworkBundle).

asset_version

        1
        {{ asset_version(packageName = null) }}
    

packageName (optional): type: string | null default: null

Returns the current version of the package, more information in Creating and Using Templates.

form

        1
        {{ form(view, variables = []) }}
    

view: type: FormView
variables (optional): type: array default: []

Renders the HTML of a complete form, more information in the Twig Form reference.

form_start

        1
        {{ form_start(view, variables = []) }}
    

view: type: FormView
variables (optional): type: array default: []

Renders the HTML start tag of a form, more information in the Twig Form reference.

form_end

        1
        {{ form_end(view, variables = []) }}
    

view: type: FormView
variables (optional): type: array default: []

Renders the HTML end tag of a form together with all fields that have not been rendered yet, more information in the Twig Form reference.

form_enctype

        1
        {{ form_enctype(view) }}
    

view: type: FormView

Renders the required enctype="multipart/form-data" attribute if the form contains at least one file upload field, more information in the Twig Form reference.

        1
        {{ form_widget(view, variables = []) }}
    

view: type: FormView
variables (optional): type: array default: []

Renders a complete form or a specific HTML widget of a field, more information in the Twig Form reference.

form_errors

        1
        {{ form_errors(view) }}
    

view: type: FormView

Renders any errors for the given field or the global errors, more information in the Twig Form reference.

form_label

        1
        {{ form_label(view, label = null, variables = []) }}
    

view: type: FormView
label (optional): type: string default: null
variables (optional): type: array default: []

Renders the label for the given field, more information in the Twig Form reference.

form_row

        1
        {{ form_row(view, variables = []) }}
    

view: type: FormView
variables (optional): type: array default: []

Renders the row (the field's label, errors and widget) of the given field, more information in the Twig Form reference.

form_rest

        1
        {{ form_rest(view, variables = []) }}
    

view: type: FormView
variables (optional): type: array default: []

Renders all fields that have not yet been rendered, more information in the Twig Form reference.

csrf_token

        1
        {{ csrf_token(intention) }}
    

intention: type: string

Renders a CSRF token. Use this function if you want CSRF protection without creating a form.

is_granted

        1
        {{ 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 Security.

Note

You can also pass in the field to use ACE for a specific field. Read more about this in How to Use advanced ACL Concepts.

logout_path

        1
        {{ 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

        1
        {{ 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

        1
        {{ path(name, 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. More information in Creating and Using Templates.

url

        1
        {{ url(name, 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. More information in Creating and Using Templates.

absolute_url

2.7

The absolute_url() function was introduced in Symfony 2.7.

        1
        {{ absolute_url(path) }}
    

path: type: string

Returns the absolute URL from the passed relative path. For example, assume you're on the following page in your app: http://example.com/products/hover-board.

        1
2
3
4
5
        {{ absolute_url('/human.txt') }}
{# http://example.com/human.txt #}

{{ absolute_url('products_icon.png') }}
{# http://example.com/products/products_icon.png #}
    

relative_path

2.7

The relative_path() function was introduced in Symfony 2.7.

        1
        {{ 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.

        1
2
3
4
5
        {{ relative_path('http://example.com/human.txt') }}
{# ../human.txt #}

{{ relative_path('http://example.com/products/products_icon.png') }}
{# products_icon.png #}
    

expression

Creates an Expression in Twig. See "Template Expressions".

Filters

humanize

        1
        {{ 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).

2.3

Transforming camelCase text into human readable text was introduced in Symfony 2.3.

trans

        1
        {{ 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 Translation Filters.

transchoice

        1
        {{ message|transchoice(count, arguments = [], domain = null, locale = null) }}
    

message: type: string
count: type: integer
arguments (optional): type: array default: []
domain (optional): type: string default: null
locale (optional): type: string default: null

Translates the text with pluralization support. More information in Translation Filters.

yaml_encode

        1
        {{ 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 The Yaml Component for more information.

yaml_dump

        1
        {{ 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

        1
        {{ class|abbr_class }}
    

class: type: string

Generates an <abbr> 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

        1
        {{ method|abbr_method }}
    

method: type: string

Generates an <abbr> 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

        1
        {{ args|format_args }}
    

args: type: array

Generates a string with the arguments and their types (within <em> elements).

format_args_as_text

        1
        {{ args|format_args_as_text }}
    

args: type: array

Equal to the format_args filter, but without using HTML tags.

file_excerpt

        1
        {{ file|file_excerpt(line) }}
    

file: type: string
line: type: integer

Generates an excerpt of a code file around the given line number.

format_file

        1
        {{ file|format_file(line, text = null) }}
    

file: type: string
line: type: integer
text (optional): type: string default: null

Generates the file path inside an <a> element. If the path is inside the kernel root directory, the kernel root directory path is replaced by kernel.root_dir (showing the full path in a tooltip on hover).

format_file_from_text

        1
        {{ text|format_file_from_text }}
    

text: type: string

Uses format_file to improve the output of default PHP errors.

file_link

        1
        {{ file|file_link(line) }}
    

file: type: string
line: type: integer

Generates a link to the provided file and line number using a preconfigured scheme.

Tests

selectedchoice

        1
        {% if choice is selectedchoice(selectedValue) %}
    

choice: type: ChoiceView
selectedValue: type: string

Checks if selectedValue was checked for the provided choice field. Using this test is the most effective way.

rootform

        1
2
3
        {% if form is rootform %}
    {# ... #}
{% endif %}
    

form: type: FormView

Checks if the given form does not have a parent form view. This is the only safe way of testing it because checking if the form contains a field called parent is not reliable.

Global Variables

app

The app variable is available everywhere and gives access to many commonly needed objects and values. It is an instance of GlobalVariables.

The available attributes are:

app.user, a PHP object representing the current user;
app.request, a Request object;
app.session, a Session object;
app.environment, a string with the name of the execution environment;
app.debug, a boolean telling whether the debug mode is enabled in the app;
app.security (deprecated as of 2.6).

Symfony Standard Edition Extensions

The Symfony Standard Edition adds some bundles to the Symfony Core Framework. Those bundles can have other Twig extensions:

Assetic adds the {% stylesheets %}, {% javascripts %} and {% image %} tags. You can read more about them in the Assetic Documentation.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version