Symfony 定义的 Twig 扩展

编辑此页

Twig 是 Symfony 应用程序中使用的模板引擎。Twig 定义了数十个默认的过滤器和函数，但 Symfony 也定义了一些过滤器、函数和标签，以便将各种 Symfony 组件与 Twig 模板集成。本文解释了所有这些扩展。

提示

如果 Symfony 提供的这些扩展不够用，你可以创建自定义 Twig 扩展以定义更多的过滤器和函数。

函数

render

        1
        {{ render(uri, options = []) }}
    

uri: 类型: string | ControllerReference
options (可选): 类型: array 默认值: []

向给定的内部 URI 或控制器发出请求并返回结果。渲染策略可以在选项的 strategy 键中指定。它通常用于在模板中嵌入控制器。

render_esi

        1
        {{ render_esi(uri, options = []) }}
    

uri: 类型: string | ControllerReference
options (可选): 类型: array 默认值: []

它类似于 render 函数，并定义了相同的参数。但是，当启用 ESI 支持时，它会生成 ESI 标签，否则会回退到 render 的行为。

提示

render_esi() 函数是 render 的快捷函数示例。它根据函数名称中给出的内容自动设置策略，例如 render_hinclude() 将使用 hinclude.js 策略。这适用于所有 render_*() 函数。

fragment_uri

        1
        {{ fragment_uri(controller, absolute = false, strict = true, sign = true) }}
    

controller: 类型: ControllerReference
absolute (可选): 类型: boolean 默认值: false
strict (可选): 类型: boolean 默认值: true
sign (可选): 类型: boolean 默认值: true

生成片段的 URI。

controller

        1
        {{ controller(controller, attributes = [], query = []) }}
    

controller: 类型: string
attributes (可选): 类型: array 默认值: []
query (可选): 类型: array 默认值: []

返回 ControllerReference 的实例，用于 render() 和 render_esi() 等函数。

asset

        1
        {{ asset(path, packageName = null) }}
    

path: 类型: string
packageName (可选): 类型: string | null 默认值: null

返回给定 asset 路径的公共路径（可以是 CSS 文件、JavaScript 文件、图像路径等）。此函数考虑了应用程序的安装位置（例如，如果项目在主机子目录中访问）和可选的 asset 包基本路径。

Symfony 通过 assets.version、assets.version_strategy 和 assets.json_manifest_path 配置选项提供了各种缓存清除实现。

另请参阅

阅读更多关于从模板链接到 Web assets 的信息。

asset_version

        1
        {{ asset_version(path, packageName = null) }}
    

path: 类型: string
packageName (可选): 类型: string | null 默认值: null

返回包的当前版本，更多信息请参见创建和使用模板。

csrf_token

        1
        {{ csrf_token(intention) }}
    

intention: 类型: string - 用于标识令牌的任意字符串。

渲染 CSRF 令牌。如果你想在不由 Symfony 表单组件管理的常规 HTML 表单中进行 CSRF 保护，请使用此函数。

is_granted

        1
        {{ is_granted(role, object = null, field = null) }}
    

role: 类型: string
object (可选): 类型: object
field (可选): 类型: string

如果当前用户具有给定的角色，则返回 true。

可选地，可以传递一个对象供 voter 使用。更多信息可以在安全中找到。

logout_path

        1
        {{ logout_path(key = null) }}
    

key (可选): 类型: string

为给定的防火墙生成相对登出 URL。如果未提供 key，则为用户登录的当前防火墙生成 URL。

logout_url

        1
        {{ logout_url(key = null) }}
    

key (可选): 类型: string

等同于 logout_path 函数，但它将生成绝对 URL 而不是相对 URL。

path

        1
        {{ path(route_name, route_parameters = [], relative = false) }}
    

name: 类型: string
parameters (可选): 类型: array 默认值: []
relative (可选): 类型: boolean 默认值: false

返回给定路由的相对 URL（不包含 scheme 和 host）。如果启用了 relative，它将创建相对于当前路径的路径。

另请参阅

阅读更多关于 Symfony 路由和在 Twig 模板中创建链接的信息。

url

        1
        {{ url(route_name, route_parameters = [], schemeRelative = false) }}
    

name: 类型: string
parameters (可选): 类型: array 默认值: []
schemeRelative (可选): 类型: boolean 默认值: false

返回给定路由的绝对 URL（包含 scheme 和 host）。如果启用了 schemeRelative，它将创建 scheme 相对的 URL。

另请参阅

阅读更多关于 Symfony 路由和在 Twig 模板中创建链接的信息。

absolute_url

        1
        {{ absolute_url(path) }}
    

path: 类型: string

从传递的相对路径返回绝对 URL（包含 scheme 和 host）。将其与 asset() 函数结合使用，为 Web assets 生成绝对 URL。阅读更多关于链接到 CSS、JavaScript 和图像 Assets 的信息。

relative_path

        1
        {{ relative_path(path) }}
    

path: 类型: string

从传递的绝对 URL 返回相对路径。例如，假设你在应用程序的以下页面上：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

创建与 ExpressionLanguage 组件相关的 Expression。

impersonation_path

        1
        {{ impersonation_path(identifier) }}
    

identifier: 类型: string

生成你可以访问以模拟用户的 URL，由 identifier 参数标识。

impersonation_url

        1
        {{ impersonation_url(identifier) }}
    

identifier: 类型: string

它类似于 impersonation_path 函数，但它生成绝对 URL 而不是相对 URL。

impersonation_exit_path

        1
        {{ impersonation_exit_path(exitTo = null) }}
    

exitTo (可选): 类型: string

生成你可以访问以退出用户模拟的 URL。退出模拟后，用户将被重定向到当前 URI。如果你希望重定向到不同的 URI，请在 exitTo 参数中定义其值。

如果没有用户被模拟，则该函数返回一个空字符串。

impersonation_exit_url

        1
        {{ impersonation_exit_url(exitTo = null) }}
    

exitTo (可选): 类型: string

它类似于 impersonation_exit_path 函数，但它生成绝对 URL 而不是相对 URL。

t

        1
        {{ t(message, parameters = [], domain = 'messages')|trans }}
    

message: 类型: string
parameters (可选): 类型: array 默认值: []
domain (可选): 类型: string 默认值: messages

创建一个可以传递给 trans 过滤器的 Translatable 对象。

        1
        {{ text|humanize }}
    

text: 类型: string

将给定的字符串转换为人类可读的字符串（通过将下划线替换为空格，将字符串大写等）。例如，当向最终用户显示 PHP 属性/变量的名称时，它非常有用

        1
2
3
4
5
6
        {{ 'dateOfBirth'|humanize }}    {# renders: Date of birth #}
{{ 'DateOfBirth'|humanize }}    {# renders: Date of birth #}
{{ 'date-of-birth'|humanize }}  {# renders: Date-of-birth #}
{{ 'date_of_birth'|humanize }}  {# renders: Date of birth #}
{{ 'date of birth'|humanize }}  {# renders: Date of birth #}
{{ 'Date Of Birth'|humanize }}  {# renders: Date of birth #}
    

trans

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

message: 类型: string | Translatable
arguments (可选): 类型: array 默认值: []
domain (可选): 类型: string 默认值: null
locale (可选): 类型: string 默认值: null

将文本翻译成当前语言。更多信息请参见翻译过滤器。

sanitize_html

        1
        {{ body|sanitize_html(sanitizer = "default") }}
    

body: 类型: string
sanitizer (可选): 类型: string 默认值: "default"

使用 HTML Sanitizer 组件对文本进行清理。更多信息请参见 HTML Sanitizer。

yaml_encode

        1
        {{ input|yaml_encode(inline = 0, dumpObjects = false) }}
    

input: 类型: mixed
inline (可选): 类型: integer 默认值: 0
dumpObjects (可选): 类型: boolean 默认值: false

将输入转换为 YAML 语法。

inline 参数是生成的输出切换到内联 YAML 的级别

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        {% set array = {
    'a': {
        'c': 'e'
    },
    'b': {
        'd': 'f'
    }
} %}

{{ array|yaml_encode(inline = 0) }}
{# output:
   { a: { c: e }, b: { d: f } } #}

{{ array|yaml_encode(inline = 1) }}
{# output:
   a: { c: e }
   b: { d: f } #}
    

dumpObjects 参数启用 PHP 对象的转储

        1
2
3
4
        // ...
$object = new \stdClass();
$object->foo = 'bar';
// ...
    

        1
2
3
4
5
        {{ object|yaml_encode(dumpObjects = false) }}
{# output: null #}

{{ object|yaml_encode(dumpObjects = true) }}
{# output: !php/object 'O:8:"stdClass":1:{s:5:"foo";s:7:"bar";}' #}
    

有关更多信息，请参见 Yaml 组件。

yaml_dump

        1
        {{ value|yaml_dump(inline = 0, dumpObjects = false) }}
    

value: 类型: mixed
inline (可选): 类型: integer 默认值: 0
dumpObjects (可选): 类型: boolean 默认值: false

与 yaml_encode() 的作用相同，但输出中包含类型。

inline 参数是生成的输出切换到内联 YAML 的级别

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        {% set array = {
    'a': {
        'c': 'e'
    },
    'b': {
        'd': 'f'
    }
} %}

{{ array|yaml_dump(inline = 0) }}
{# output:
   %array% { a: { c: e }, b: { d: f } } #}

{{ array|yaml_dump(inline = 1) }}
{# output:
   %array% a: { c: e }
   b: { d: f } #}
    

dumpObjects 参数启用 PHP 对象的转储

        1
2
3
4
        // ...
$object = new \stdClass();
$object->foo = 'bar';
// ...
    

        1
2
3
4
5
        {{ object|yaml_dump(dumpObjects = false) }}
{# output: %object% null #}

{{ object|yaml_dump(dumpObjects = true) }}
{# output: %object% !php/object 'O:8:"stdClass":1:{s:3:"foo";s:3:"bar";}' #}
    

abbr_class

        1
        {{ class|abbr_class }}
    

class: 类型: string

生成 <abbr> 元素，其中包含 PHP 类的短名称（当用户将鼠标悬停在元素上时，工具提示中将显示 FQCN）。

abbr_method

        1
        {{ method|abbr_method }}
    

method: 类型: string

使用 FQCN::method() 语法生成 <abbr> 元素。如果 method 是 Closure，则将使用 Closure 代替，如果 method 没有类名，则将其显示为函数（method()）。

format_args

        1
        {{ args|format_args }}
    

args: 类型: array

生成一个字符串，其中包含参数及其类型（在 <em> 元素内）。

format_args_as_text

        1
        {{ args|format_args_as_text }}
    

args: 类型: array

等同于 format_args 过滤器，但不使用 HTML 标签。

file_excerpt

        1
        {{ file|file_excerpt(line, srcContext = 3) }}
    

file: 类型: string
line: 类型: integer
srcContext (可选): 类型: integer

在给定的 line 号周围生成代码文件的摘录。srcContext 参数定义要在给定行号周围显示的行总数（使用 -1 显示整个文件）。

format_file

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

file: 类型: string
line: 类型: integer
text (可选): 类型: string 默认值: null

在 <a> 元素内生成文件路径。如果路径在内核根目录中，则内核根目录路径将替换为 kernel.project_dir（在悬停时在工具提示中显示完整路径）。

format_file_from_text

        1
        {{ text|format_file_from_text }}
    

text: 类型: string

使用 format_file 来改进默认 PHP 错误的输出。

file_link

        1
        {{ file|file_link(line) }}
    

file: 类型: string
line: 类型: integer

使用预配置的 scheme 生成到提供的文件和行号的链接。

file_relative

        1
        {{ file|file_relative }}
    

file: 类型: string

它将给定的绝对文件路径转换为相对于项目根目录的新文件路径

        1
2
        {{ '/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' #}
    

如果给定的文件路径不在项目目录中，将返回 null 值。

serialize

        1
        {{ object|serialize(format = 'json', context = []) }}
    

object: 类型: mixed
format (可选): 类型: string
context (可选): 类型: array

接受可以由 Serializer 组件序列化的任何数据，并以指定的 format 返回序列化字符串。

emojify

7.1

emojify 过滤器在 Symfony 7.1 中引入。

        1
        {{ text|emojify(catalog = null) }}
    

text

类型: string

catalog (可选)

类型: string | null

用于生成文本表示的 emoji 集 (slack、github、gitlab 等)

它将 emoji 的文本表示形式（例如 :wave:）转换为实际的 emoji (👋)

        1
2
3
        {{ ':+1:'|emojify }}                 {# renders: 👍 #}
{{ ':+1:'|emojify('github') }}       {# renders: 👍 #}
{{ ':thumbsup:'|emojify('gitlab') }} {# renders: 👍 #}
    

版本