Twig 內建函數完全參考：attribute、block、constant、cycle、dump、parent、random、range

Twig 函數以 function_name() 形式呼叫，執行邏輯並回傳值供輸出或進一步處理。本文詳細說明所有 8 個內建函數的語法、參數、回傳值與實戰範例。

函數速覽表

詳細函數參考

1. attribute — 動態存取

{{ attribute(object, method) }}
{{ attribute(object, method, arguments) }}
{{ attribute(array, item) }}

用途：屬性/方法名稱存於變數中，或屬性名稱包含特殊字元時。

{# 動態呼叫方法 #}
{% set method = 'getName' %}
{{ attribute(user, method) }}

{# 動態存取陣列鍵 #}
{% set key = 'user_name' %}
{{ attribute(userData, key) }}

{# 帶參數呼叫 #}
{{ attribute(service, 'process', [param1, param2]) }}

2. block — 輸出區塊內容

<title>{% block title %}{% endblock %}</title>
<h1>{{ block('title') }}</h1>

在同一模板中多次輸出同一區塊，或在父模板中預覽子區塊內容。

3. constant — 讀取常數

{{ some_date|date(constant('DATE_W3C')) }}
{{ constant('Namespace\\ClassName::CONSTANT_NAME') }}

避免在模板硬編碼常數值，支援命名空間常數（需雙跳脫反斜線）。

4. cycle — 循環取值

{% set fruits = ['apple', 'orange', 'citrus'] %}
{% for i in 0..10 %}
    {{ cycle(fruits, i) }}
{% endfor %}

輸出：apple, orange, citrus, apple, orange, citrus... 適合 Zebra striping、循環色系分配。

5. dump — 除錯輸出 (1.5+)

前置條件：需啟用 Debug 擴充：

$twig = new Twig\Environment($loader);
$twig->addExtension(new Twig\Extension\DebugExtension());

用法

{{ dump(user, categories) }} {# 輸出指定變數 #}
{{ dump() }}                 {# 輸出所有當前上下文變數 #}

底層呼叫 PHP var_dump()，輸出至標準輸出（Web 環境直接顯示在頁面）。

6. parent — 父區塊內容

{% extends "base.twig" %}
{% block sidebar %}
    <h3>Table Of Contents</h3>
    {{ parent() }}
{% endblock %}

在覆寫區塊時保留父內容，實現「擴充而非替換」。

7. random — 隨機取值 (1.5+)

{{ random(['apple', 'orange', 'citrus']) }}
{# 隨機回傳陣列中一個元素 #}

也支援字串（隨機字元）、整數範圍 random(1, 100)、Traversable 物件。

8. range — 產生數字範圍

{% for i in range(0, 3) %}
    {{ i }},
{% endfor %}

輸出：0, 1, 2, 3, 參數：start、end、step=1。等同 0..3 語法糖，但可動態計算參數。

進階組合範例

動態區塊渲染

{% set blocks = ['header', 'content', 'footer'] %}
{% for blockName in blocks %}
    <section data-block="{{ blockName }}">
        {{ block(blockName) }}
    </section>
{% endfor %}

常數驅動日期格式

<time datetime="{{ post.date|date(constant('DATE_ATOM')) }}">
    {{ post.date|date('Y-m-d') }}
</time>

Zebra Striping 兩種寫法

{# 方法 1: cycle #}
{% for row in rows %}
    <tr class="{{ cycle(['odd', 'even'], loop.index0) }}">...</tr>
{% endfor %}

{# 方法 2: loop 變數 #}
{% for row in rows %}
    <tr class="{{ loop.index0 is even ? 'even' : 'odd' }}">...</tr>
{% endfor %}

除錯最佳實務

{# 僅開發環境啟用 #}
{% if app.debug %}
    {{ dump() }}
{% endif %}

自訂函數

$twig = new Twig\Environment($loader);
$twig->addFunction(new Twig\TwigFunction('gravatar', function ($email, $size = 80) {
    $hash = md5(strtolower(trim($email)));
    return "https://www.gravatar.com/avatar/$hash?s=$size";
}));

// 模板使用
<img src="{{ gravatar(user.email, 48) }}" alt="{{ user.name }}" />

總結

Twig 內建函數雖少但精，涵蓋動態存取、區塊複用、常數引用、循環取值、除錯、繼承擴充、隨機與範圍產生等核心需求。搭配過濾器與標籤系統，已能應付絕大多數模板邏輯。複雜業務邏輯請在 PHP 控制器/服務層完成，模板專注於呈現。