Smarty 模板引擎快速入門：安裝配置與基本使用完整教學

前言

Smarty 是 PHP 經典的模板引擎，透過「編譯模板為 PHP 代碼」實現高效能，嚴格分離「邏輯 (PHP)」與「顯示 (Template)」。本文從安裝、目錄結構、基礎語法到實戰範例，完整引導快速上手。

一、安裝與目錄結構

Composer 安裝 (推薦)

composer require smarty/smarty

手動下載

官網：https://www.smarty.net/ 下載最新穩定版，解壓至專案 `lib/Smarty/`

必要目錄結構 (需可寫入權限)

project/
├── lib/
│   └── Smarty/           # Smarty 核心庫
├── templates/            # 模板檔 (*.tpl)
├── templates_c/          # 編譯快取 (需寫入權限 775)
├── cache/                # 快取檔 (需寫入權限 775)
├── configs/              # 設定檔 (可選)
└── public/
    └── index.php         # 入口檔

二、核心配置檔：smarty_init.php

<?php
require_once __DIR__ . '/lib/Smarty/libs/Smarty.class.php';

$smarty = new Smarty();

// 目錄設定 (絕對路徑最安全)
$smarty->setTemplateDir(__DIR__ . '/templates/');
$smarty->setCompileDir(__DIR__ . '/templates_c/');
$smarty->setCacheDir(__DIR__ . '/cache/');
$smarty->setConfigDir(__DIR__ . '/configs/');

// 開發環境關閉快取，正式環境開啟
$smarty->caching = false;           // true = 開啟快取
$smarty->cache_lifetime = 3600;     // 快取壽命 (秒)

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

// 除錯模式
$smarty->debugging = false;
$smarty->error_reporting = E_ALL & ~E_NOTICE;

// 常用全域變數
$smarty->assign('SITE_NAME', 'My Website');
$smarty->assign('BASE_URL', 'https://example.com/');

三、基礎模板語法

1. 變數輸出

<!-- 模板檔：templates/index.tpl -->
<html>
<head><title><{$page_title}></title></head>
<body>
  <h1>歡迎 <{$user.name|default:'訪客'}> </h1>
  <p>Email: <{$user.email|escape}></p>
  <p>註冊時間: <{$user.created_at|date_format:'%Y-%m-%d'}></p>
</body>
</html>

2. 修飾詞 (Modifiers) - 管道式處理

3. 條件判斷

<{if $user.logged_in}>
  <p>歡迎回來，<{$user.name}></p>
  <{if $user.role == 'admin'}>
    <a href="/admin">管理後台</a>
  <{/if}>
<{elseif $user.banned}>
  <p style="color:red">帳號已停用</p>
<{else}>
  <a href="/login">請登入</a>
<{/if}>

4. 迴圈遍歷

<ul>
<{foreach $products as $product}>
  <li>
    <strong><{$product.name}></strong> - 
    <span class="price">$<{$product.price|number_format:2}></span>
    <{if $product.on_sale}><span class="badge">特價</span><{/if}>
  </li>
<{foreachelse}>
  <li>目前無商品</li>
<{/foreach}>
</ul>

<!-- 取得索引 -->
<{foreach $items as $idx => $item}>
  <div class="item-<{$idx}>"><{$item}></div>
<{/foreach}>

5. 變數操作

<{assign var="total" value=$price * $qty}>
<{assign var="fullName" value=$firstName|cat:" "|cat:$lastName}>
<{$fullName}>

<{capture name="sidebar"}>
  這段內容會被捕獲到變數 $smarty.capture.sidebar
<{/capture}>
<{$smarty.capture.sidebar}>

四、PHP 控制器實戰範例

<?php
require 'smarty_init.php';

// 模擬資料
$products = [
  ['id' => 1, 'name' => '筆電', 'price' => 25000, 'on_sale' => true],
  ['id' => 2, 'name' => '滑鼠', 'price' => 500, 'on_sale' => false],
  ['id' => 3, 'name' => '鍵盤', 'price' => 1200, 'on_sale' => true],
];

$user = [
  'name' => '張三',
  'email' => 'zhang@example.com',
  'role' => 'member',
  'logged_in' => true,
  'created_at' => time(),
];

// 指派變數
$smarty->assign('page_title', '商品列表');
$smarty->assign('products', $products);
$smarty->assign('user', $user);

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

五、進階功能速覽

六、常見問題與最佳實踐

1. 權限問題：`templates_c/`、`cache/` 必須給 Web 使用者寫入權限 (`chown www:www` / `chmod 775`)
2. 定界符衝突：前端用 Vue/React 時必須修改 `left_delimiter`/`right_delimiter` (如 `<{` `}>`)
3. 快取不更新：開發時設 `$smarty->caching = false`，或手動刪除 `templates_c/`、`cache/` 內容
4. 變數未定義：模板中用 `{$var|default:''}` 防止 Notice
5. 效能優化：避免在模板中做複雜邏輯，預先在 PHP 整理好資料再 assign
6. 安全性：輸出變數習慣加 `|escape`，除非確定是安全 HTML 內容

七、從 Smarty 遷移到現代替代方案？

新專案建議考慮：

• Twig：Symfony 預設，語法優雅、繼承強大、沙箱安全、效能好
• Blade：Laravel 內建，語法簡潔、編譯快、支援元件
• Latte：Nette 專用，型別安全、自動逃逸、效能極佳

但維護舊專案時，Smarty 仍是穩定可靠的選擇，掌握其核心概念（編譯、快取、修飾詞、區塊）即可高效開發。

總結

Smarty 入門關鍵在於：建立正確目錄權限、配置定界符避免衝突、善用修飾詞處理顯示邏輯、嚴格分離 PHP 邏輯與模板顯示。掌握 `assign`、`display`、`foreach`、`if`、`modifier` 五大核心，即可處理 90% 的模板需求。