PHPLib 模板類中文詳解：原始碼逐行註釋與核心機制分析

類別結構概覽

class Template {
    var $classname = "Template";
    var $debug = false;
    var $root = ".";              // 模板根目錄
    var $file = array();          // handle => 完整路徑
    var $varkeys = array();       // 變數正則鍵
    var $varvals = array();       // 變數值
    var $unknowns = "remove";     // 未定義變數處理：remove/comment/keep
    var $halt_on_error = "yes";   // yes/report/no
    var $last_error = "";
    // ... 方法定義
}

核心方法詳解

建構子 Template($root, $unknowns)

設定根目錄與未知變數策略，預設 remove（刪除）。

set_root($root)

驗證目錄存在，設定 $this->root。

set_file($varname, $filename) / set_file(array)

建立 handle 到檔案路徑的對應，支援單筆與批次。路徑經 filename() 處理為絕對路徑。

set_block($parent, $varname, $name)

從父模板提取 <!-- BEGIN varname -->...<!-- END varname --> 區塊，以 {name} 取代，區塊內容存入 $varname 變數，支援巢狀。

set_var($varname, $value, $append)

設定變數值，自動建立正則鍵 /{varname}/，支援陣列批次與追加模式。

subst($varname)

載入模板檔，以 preg_replace($this->varkeys, $varvals_quoted, $str) 一次性替換所有已知變數，回傳結果字串。

parse($target, $varname, $append)

呼叫 subst() 解析模板，結果存入 $target 變數（可追加）。支援陣列批次解析多個模板。

finish($str)

最終處理：根據 $unknowns 處理殘留未定義變數（刪除/註解/保留）。

p($varname) / get($varname)

輸出或取回經 finish() 處理的變數值。

loadfile($varname)

惰性載入：首次使用時才讀取檔案內容到 $varvals。

特殊功能

• savetofile($dir, $varname)：將解析結果靜態化存檔。
• renew()：清空所有快取變數與檔案對應，重置物件狀態。
• 錯誤處理：halt() / haltmsg() 依 $halt_on_error 決定是否終止。

設計亮點

• 正則替換一次完成所有變數，效能優於逐個 str_replace。
• 區塊巢狀透過遞迴正則實現，靈活強大。
• 惰性載入減少不必要 I/O。
• 未知變數三種策略適應不同開發習慣。