Symfony Twig Extensions¶
Twig is the default template engine for Symfony. By itself, it already contains a lot of built-in functions, filters, tags and tests (learn more about them from the Twig Reference).
Symfony adds custom extensions on top of Twig to integrate some components into the Twig templates. The following sections describe the custom functions, filters, tags and tests that are available when using the Symfony Core Framework.
There may also be tags in bundles you use that aren’t listed here.
Functions¶
render¶
2.2 新版功能: The render() function was introduced in Symfony 2.2. Prior, the {% render %} tag was used and had a different signature.
{{ render(uri, options) }}
- uri
- type: string | ControllerReference
- options
- type: array default: []
Renders the fragment for the given controller (using the controller function) or URI. For more information, see Embedding Controllers.
The render strategy can be specified in the strategy key of the options.
render_esi¶
{{ render_esi(uri, options) }}
- uri
- type: string | ControllerReference
- options
- type: array default: []
Generates an ESI tag when possible or falls back to the behavior of render function instead. For more information, see Embedding Controllers.
小技巧
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¶
2.2 新版功能: The controller() function was introduced in Symfony 2.2.
{{ controller(controller, attributes, query) }}
- controller
- type: string
- attributes
- type: array default: []
- query
- type: array default: []
Returns an instance of ControllerReference to be used with functions like render() and render_esi().
asset¶
{{ asset(path, packageName) }}
- path
- type: string
- packageName
- 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 Linking to Assets.
asset_version¶
{{ asset_version(packageName) }}
- packageName
- type: string | null default: null
Returns the current version of the package, more information in Linking to Assets.
form¶
{{ form(view, variables) }}
- view
- type: FormView
- variables
- type: array default: []
Renders the HTML of a complete form, more information in the Twig Form reference.
form_start¶
{{ form_start(view, variables) }}
- view
- type: FormView
- variables
- type: array default: []
Renders the HTML start tag of a form, more information in the Twig Form reference.
form_end¶
{{ form_end(view, variables) }}
- view
- type: FormView
- variables
- 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¶
{{ 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.
form_widget¶
{{ form_widget(view, variables) }}
- view
- type: FormView
- variables
- type: array default: []
Renders a complete form or a specific HTML widget of a field, more information in the Twig Form reference.
form_errors¶
{{ 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¶
{{ form_label(view, label, variables) }}
- view
- type: FormView
- label
- type: string default: null
- variables
- type: array default: []
Renders the label for the given field, more information in the Twig Form reference.
form_row¶
{{ form_row(view, variables) }}
- view
- type: FormView
- variables
- 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¶
{{ form_rest(view, variables) }}
- view
- type: FormView
- variables
- type: array default: []
Renders all fields that have not yet been rendered, more information in the Twig Form reference.
csrf_token¶
{{ csrf_token(intention) }}
- intention
- type: string
Renders a CSRF token. Use this function if you want CSRF protection without creating a form.
is_granted¶
{{ is_granted(role, object, field) }}
- role
- type: string
- object
- type: object
- field
- type: string
Returns true if the current user has the required role. Optionally, an object can be pasted to be used by the voter. More information can be found in Access Control in Templates.
注解
You can also pass in the field to use ACE for a specific field. Read more about this in Scope of Access Control Entries.
logout_path¶
{{ logout_path(key) }}
- key
- type: string
Generates a relative logout URL for the given firewall.
logout_url¶
{{ logout_url(key) }}
- key
- type: string
Equal to the logout_path function, but it’ll generate an absolute URL instead of a relative one.
path¶
{{ path(name, parameters, relative) }}
- name
- type: string
- parameters
- type: array default: []
- relative
- 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 Linking to Pages.
url¶
{{ url(name, parameters, schemeRelative) }}
- name
- type: string
- parameters
- type: array default: []
- schemeRelative
- 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 Linking to Pages.
Filters¶
humanize¶
2.1 新版功能: The humanize filter was introduced in Symfony 2.1
{{ text|humanize }}
- text
- type: string
Makes a technical name human readable (i.e. replaces underscores by spaces and capitalizes the string).
trans¶
{{ message|trans(arguments, domain, locale) }}
- message
- type: string
- arguments
- type: array default: []
- domain
- type: string default: null
- locale
- type: string default: null
Translates the text into the current language. More information in Translation Filters.
transchoice¶
{{ message|transchoice(count, arguments, domain, locale) }}
- message
- type: string
- count
- type: integer
- arguments
- type: array default: []
- domain
- type: string default: null
- locale
- type: string default: null
Translates the text with pluralization support. More information in Translation Filters.
yaml_encode¶
{{ input|yaml_encode(inline, dumpObjects) }}
- input
- type: mixed
- inline
- type: integer default: 0
- dumpObjects
- type: boolean default: false
Transforms the input into YAML syntax. See Writing YAML Files for more information.
yaml_dump¶
{{ value|yaml_dump(inline, dumpObjects) }}
- value
- type: mixed
- inline
- type: integer default: 0
- dumpObjects
- type: boolean default: false
Does the same as yaml_encode(), but includes the type in the output.
abbr_class¶
{{ 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¶
{{ 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¶
{{ args|format_args }}
- args
- type: array
Generates a string with the arguments and their types (within <em> elements).
format_args_as_text¶
{{ args|format_args_as_text }}
- args
- type: array
Equal to the format_args filter, but without using HTML tags.
file_excerpt¶
{{ file|file_excerpt(line) }}
- file
- type: string
- line
- type: integer
Generates an excerpt of seven lines around the given line.
format_file¶
{{ file|format_file(line, text) }}
- file
- type: string
- line
- type: integer
- text
- 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¶
{{ text|format_file_from_text }}
- text
- type: string
Uses format_file to improve the output of default PHP errors.
file_link¶
{{ file|file_link(line) }}
- line
- type: integer
Generates a link to the provided file (and optionally line number) using a preconfigured scheme.
Tags¶
form_theme¶
{% 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¶
{% trans with vars from domain into locale %}{% endtrans %}
- vars
- type: array default: []
- domain
- type: string default: string
- locale
- type: string default: string
Renders the translation of the content. More information in Twig Templates.
transchoice¶
{% transchoice count with vars from domain into locale %}{% endtranschoice %}
- count
- type: integer
- vars
- type: array default: []
- domain
- type: string default: null
- locale
- type: string default: null
Renders the translation of the content with pluralization support, more information in Twig Templates.
trans_default_domain¶
{% trans_default_domain domain %}
- domain
- type: string
This will set the default domain in the current template.
Tests¶
selectedchoice¶
{% 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.
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
- app.request
- app.session
- app.environment
- app.debug
- app.security
Symfony Standard Edition Extensions¶
The Symfony Standard Edition adds some bundles to the Symfony Core Framework. Those bundles can have other Twig extensions:
- Twig Extensions includes some interesting extensions that do not belong to the Twig core. You can read more in the official Twig Extensions documentation;
- Assetic adds the {% stylesheets %}, {% javascripts %} and {% image %} tags. You can read more about them in the Assetic Documentation.