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

傳回給定資源路徑（可以是 CSS 檔案、JavaScript 檔案、影像路徑等）的公開路徑。此函式會考量應用程式的安裝位置（例如，專案在主機子目錄中存取的情況）和選用的資源套件基礎路徑。

Symfony 透過 assets.version、assets.version_strategy 和 assets.json_manifest_path 組態選項提供各種快取清除實作。

另請參閱

深入了解從樣板連結至網路資源。

asset_version

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

path: 類型： string
packageName (選填): 類型： string | null 預設值： null

傳回套件的目前版本，更多資訊請參閱建立和使用樣板。

csrf_token

        1
        {{ csrf_token(intention) }}
    

intention: 類型： string - 用於識別權杖的任意字串。

渲染 CSRF 權杖。如果您想要在非 Symfony Form 組件管理的常規 HTML 表單中使用 CSRF 保護，請使用此函式。

is_granted

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

role: 類型： string
object (選填): 類型： object
field (選填): 類型： string

如果目前使用者具有給定的角色，則傳回 true。

或者，可以傳遞一個物件，供投票器使用。更多資訊請參閱安全性。

logout_path

        1
        {{ logout_path(key = null) }}
    

key (選填): 類型： string

為給定的防火牆產生相對登出 URL。如果未提供金鑰，則會為使用者登入的目前防火牆產生 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() 函式結合，以產生網路資源的絕對 URL。深入了解連結至 CSS、JavaScript 和影像資源。

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 物件。

importmap

當使用 Asset 組件時，輸出 importmap 和一些其他項目。

以下與 Symfony 表單相關的函式也可用。它們在關於自訂表單渲染的文章中說明

篩選器

humanize

        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

產生具有 PHP 類別簡短名稱的 <abbr> 元素（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: 👍 #}
    

版本