Smarty 模板引擎快速上手指南：從安裝到第一個 Hello World

Smarty 是 PHP 歷史上最流行的模板引擎之一，以「編譯型模板」、「豐富修飾符」、「緩存機制」著稱。雖然現代框架 (Laravel Blade, Twig, Latte) 已成主流，但大量存量項目仍在使用 Smarty 3/4。本文提供最精簡的 Smarty 4 安裝配置與入門實戰。

一、 環境要求與安裝

• PHP ≥ 7.1 (Smarty 4.x)、≥ 5.3 (Smarty 3.x)
• Composer 安裝 (推薦)：

  composer require smarty/smarty ^4.2
  

• 或手動下載：官網下載頁，解壓 libs/ 到項目 vendor/smarty/。

二、 目錄結構規範

project/
├── public/              # Web 根目錄
│   └── index.php        # 入口文件
├── templates/           # 模板源文件 (.tpl)
│   ├── index.tpl
│   └── layouts/
├── templates_c/         # 編譯緩存 (需寫入權限)
├── cache/               # 模板緩存 (需寫入權限)
├── configs/             # 配置文件 (可選)
└── vendor/
    └── smarty/smarty/
        └── libs/
            └── Smarty.class.php

關鍵：templates_c/ 和 cache/ **必須可寫** (Linux: chmod 775、擁有者為 php-fpm 用戶；Windows: 給 IIS_IUSRS 完全控制)。

三、 核心配置與初始化 (index.php)

<?php
require_once __DIR__ . '/../vendor/autoload.php'; // Composer 自動加載
// require_once __DIR__ . '/../vendor/smarty/libs/Smarty.class.php'; // 手動模式

use Smarty\Smarty;

$smarty = new Smarty();

$smarty->setTemplateDir(__DIR__ . '/../templates/');
$smarty->setCompileDir(__DIR__ . '/../templates_c/');
$smarty->setCacheDir(__DIR__ . '/../cache/');
$smarty->setConfigDir(__DIR__ . '/../configs/');

// 開發環境關閉緩存、開啟調試
$smarty->caching = false;
$smarty->force_compile = true; // 模板修改即時生效
$smarty->debugging = true;     // 開啟 Smarty Debug Console (Ctrl+Alt+D)

// 定界符修改 (可選，避免與 JS/Vue/React 模板語法衝突)
$smarty->left_delimiter  = '<{';
$smarty->right_delimiter = '}>';

// 賦值
$smarty->assign('name', 'World');
$smarty->assign('user', ['name' => 'Alice', 'role' => 'Admin']);
$smarty->assign('items', ['Apple', 'Banana', 'Orange']);

// 顯示模板
$smarty->display('index.tpl');

四、 模板語法速查 (index.tpl)

<!DOCTYPE html>
<html>
<head>
    <title><{$title|default:'Smarty Demo'}></title>
</head>
<body>
    <h1>Hello, <{$name|escape:'html'}>!</h1>

    <!-- 變量修飾符 -->
    <p>大寫: <{$name|upper}></p>
    <p>截取: <{$long_text|truncate:20:'...'}></p>
    <p>日期格式化: <{$timestamp|date_format:'%Y-%m-%d %H:%M'}></p>

    <!-- 條件判斷 -->
    <{if $user.role == 'Admin'}>
        <span class="badge">管理員</span>
    <{elseif $user.role == 'Editor'}>
        <span class="badge">編輯</span>
    <{else}>
        <span class="badge">訪客</span>
    <{/if}>

    <!-- 循環 -->
    <ul>
    <{foreach $items as $item}>
        <li><{$item@iteration}>. <{$item|escape}></li>
    <{/foreach}>
    </ul>

    <!-- 包含子模板 -->
    <{include file='layouts/footer.tpl'}>

    <!-- 字面量區塊 (輸出原始 JS/CSS，不解析定界符) -->
    <{literal}>
    <script>
        const data = { foo: 'bar' }; // 大括號不會被 Smarty 解析
        console.log(data);
    </script>
    <{/literal}>
</body>
</html>

五、 進階特性速覽

六、 避坑指南

1. 編碼統一：PHP 文件、模板文件、資料庫連接、HTML meta 全部 **UTF-8 無 BOM**。
2. 輸出轉義：默認 {$var} **不轉義**，務必用 {$var|escape:'html'} 或 {$var|escape:'htmlall'} 防 XSS，或啟用 $smarty->escape_html = true (Smarty 3.1+)。
3. 定界符衝突：前端用 Vue/React/Alpine 時，默認 { } 必衝突，**必改為 <{ }> 或 {% %}**。
4. 緩存目錄權限：部署腳本中務必包含 chown -R www-data:www-data templates_c cache。
5. 不要在模板裡寫複雜邏輯：控制器預處理好數據，模板只負責展示。

七、 總結

Smarty 入門極簡：**安裝 → 設四個目錄 → assign → display**。掌握 變量輸出、修飾符、條件、循環、包含、字面量 六大核心語法即可應對 90% 模板需求。對於存量項目，按避坑指南穩健維護；新項目建議評估 Twig (Symfony/Laravel 生態)、Latte (類 PHP 語法、極快、上下文感知轉義) 或框架內置引擎。