Symfony Twig Extensions
Warning: You are browsing the documentation for Symfony 3.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.
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
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) }}
path
-
type:
string
packageName
(optional)-
type:
string
|null
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. Symfony provides various cache busting
implementations via the Framework Configuration Reference (FrameworkBundle),
Framework Configuration Reference (FrameworkBundle), and
Framework Configuration Reference (FrameworkBundle) configuration options.
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_widget
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.
See also
Read Routing to learn more about the Routing component.
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.
See also
Read Routing to learn more about the Routing component.
absolute_url
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
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).
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, 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
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.
Tags
form_theme
1
{% 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 How to Customize Form Rendering.
trans
1
{% 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 Translations.
transchoice
1
{% transchoice count with vars from domain into locale %}{% endtranschoice %}
count
-
type:
integer
vars
(optional)-
type:
array
default:[]
domain
(optional)-
type:
string
default:null
locale
(optional)-
type:
string
default:null
Renders the translation of the content with pluralization support, more information in Translations.
trans_default_domain
1
{% trans_default_domain domain %}
domain
-
type:
string
This will set the default domain in the current template.
stopwatch
1
{% stopwatch 'name' %}...{% endstopwatch %}
This will time the run time of the code inside it and put that on the timeline of the WebProfilerBundle.
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.token
, a TokenInterface object representing the security tokenapp.flashes
, returns flash messages from the session