ThinkPHP 2.1 自定義標籤庫導入完整指南：從手動到自動載入

前言

ThinkPHP 2.1 的標籤庫擴充機制強大但文件較少。本文詳細記錄從建立自定義標籤類、配置導入、到實現自動載入的完整過程，避開常見坑點。

一、建立自定義標籤類

路徑慣例：@.Mylibs.Tag.TagLibTest (即 Lib/Mylibs/Tag/TagLibTest.class.php)

<?php
import('TagLib'); // 載入基類

class TagLibTest extends TagLib
{
    // 定義標籤屬性
    protected $tags = [
        // attr: 屬性清單, close: 是否閉合(0/1), level: 巢狀層級
        'article' => [
            'attr'  => 'name,field,limit,order,where,sql,key,mod',
            'close' => 1,
            'level' => 3,
        ],
    ];

    /** 實作 article 標籤：查詢資料庫並迭代輸出 */
    public function _article($attr, $content)
    {
        $tag = $this->parseXmlAttr($attr, 'article');
        
        $resultVar = $tag['result'] ?? 'article';
        $keyVar    = $tag['key']    ?? 'i';
        $modVal    = $tag['mod']    ?? '2';
        
        // 建構查詢 SQL
        if (!empty($tag['name'])) {
            $sql = "M('{$tag['name']}')";
            $sql .= $tag['field'] ? "->field('{$tag['field']}')" : '';
            $sql .= $tag['order'] ? "->order('{$tag['order']}')" : '';
            $sql .= $tag['where'] ? "->where('{$tag['where']}')" : '';
            $sql .= '->select()';
        } elseif (!empty($tag['sql'])) {
            $sql = "M()->query('{$tag['sql']}')";
        } else {
            return ''; // 無模型名也無 SQL，直接返回空
        }
        
        // 產生 PHP 模板代碼
        $parseStr = "<?php \$_result={$sql}; if (\$_result): \${$keyVar}=0;";
        $parseStr .= "foreach (\$_result as \$key=>\${$resultVar}):";
        $parseStr .= "++\${$keyVar}; \$mod = (\${$keyVar} % {$modVal}); ?>";
        $parseStr .= $content; // 標籤內容
        $parseStr .= "<?php endforeach; endif; ?>";
        
        return $parseStr;
    }
}

二、手動導入 (每個模板需宣告)

專案 Conf/taglibs.php：

<?php
return [
    'test' => '@.Mylibs.Tag.TagLibTest',
];

模板中使用：

<tagLib name="test" />
<test:article name="Article" limit="10">
    <h3>{$article.title}</h3>
    <p>{$article.content}</p>
</test:article>

三、自動導入：三種方案比較

方案 A：配置 TAGLIB_PRE_LOAD (官方建議，但 2.1 有 Bug)

// Conf/config.php
'TAGLIB_PRE_LOAD' => 'test',

問題：ThinkPHP 2.1 核心會嘗試實例化 TagLibTest 卻找不到類，拋出「實例化一個不存在的類」錯誤。

方案 B：修改核心 common/alias.php (不推薦，升級困難)

// ThinkPHP/Common/alias.php
'TagLibTest' => THINK_PATH . '/Lib/Think/Template/TagLib/TagLibTest.class.php',

方案 C：在基礎控制器 _initialize() 手動 import (推薦，簡單有效)

// Lib/Action/BaseAction.class.php
class BaseAction extends Action
{
    protected function _initialize()
    {
        import('@.Mylibs.Tag.TagLibTest');
    }
}

所有控制器繼承 BaseAction 即可自動載入標籤庫，無需修改核心。

方案 D：配置 APP_AUTOLOAD_PATH (最優雅，ThinkPHP 2.1+ 支援)

// Conf/config.php
'APP_AUTOLOAD_PATH' => 'Think.Util.,@.Mylibs.Tag.',
'TAGLIB_PRE_LOAD'   => 'test',

配合自動載入路徑，清除快取後即可正常使用，無需修改任何核心檔案。

四、模板中完整使用範例

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>ThinkPHP 自定義標籤示範</title>
</head>
<body>
<div class="main">
    <h2>自定義 article 標籤：直接查詢資料庫列表</h2>
    <table border="1" cellpadding="5">
        <thead>
            <tr><th>ID</th><th>標題</th><th>內容</th></tr>
        </thead>
        <test:article name="Article" limit="10" order="id DESC">
            <tr>
                <td>{$article.id}</td>
                <td>{$article.title}</td>
                <td>{$article.content}</td>
            </tr>
        </test:article>
    </table>
</div>
</body>
</html>

五、常見問題排查

六、總結

ThinkPHP 2.1 自定義標籤庫導入的最佳路徑：

1. 建立 @.Mylibs.Tag.TagLibTest 類別
2. 配置 APP_AUTOLOAD_PATH => '@.Mylibs.Tag.'
3. 配置 TAGLIB_PRE_LOAD => 'test'
4. 清除 Runtime/ 快取
5. 模板直接使用 <test:article> 無需 <tagLib> 宣告

此方案零修改核心、相容性佳、維護容易，推薦用於所有 ThinkPHP 2.1 專案。

延伸閱讀：ThinkPHP 入門教程、ThinkPHP 模板操作技巧總結、Smarty 模板入門基礎教程