# Smarty 到 Twig 迁移指南

## 第一阶段：准备工作

### 1. 安装 Twig
```bash
composer require twig/twig
```

### 2. 创建 Twig 配置
```php
// 在 lib/TwigConfig.php 中
$twig = new \Twig\Environment($loader, [
    'cache' => SITE_DIR . '/cache/twig/',
    'auto_reload' => true,
    'debug' => DEBUG ?? false,
]);
```

## 第二阶段：语法转换

### Smarty vs Twig 语法对比

| Smarty | Twig | 说明 |
|--------|------|------|
| `{$variable}` | `{{ variable }}` | 变量输出 |
| `{if $condition}` | `{% if condition %}` | 条件判断 |
| `{foreach $items as $item}` | `{% for item in items %}` | 循环 |
| `{include 'file.tpl'}` | `{% include 'file.twig' %}` | 包含文件 |
| `{* comment *}` | `{# comment #}` | 注释 |

### 3. 转换常用模板

从最简单的模板开始：
- `header.tpl` → `header.twig`
- `footer.tpl` → `footer.twig`
- `listItem.tpl` → `listItem.twig`

## 第三阶段：功能迁移

### 自定义函数转换
```php
// Smarty
$this->registerPlugin('function', 'getLocalizedString', [$this, 'getLocalizedString']);

// Twig
$twig->addFunction(new \Twig\TwigFunction('getLocalizedString', function($key) {
    return Localization::getString($key);
}));
```

### 修饰符转换
```php
// Smarty 修饰符
{$text|escape:'html'}

// Twig 过滤器
{{ text|escape('html') }}
```

## 第四阶段：测试和部署

### 1. 并行运行
在迁移期间，同时支持两种模板引擎：
```php
if (file_exists($template . '.twig')) {
    return $twigEngine->fetch($template . '.twig', $vars);
} else {
    return $smartyEngine->fetch($template . '.tpl', $vars);
}
```

### 2. 性能测试
使用提供的 benchmark 脚本测试性能。

### 3. 逐步替换
按模块逐步替换：
1. 通用模板 (common/)
2. 简单模块
3. 复杂模块

## 第五阶段：清理工作

### 1. 删除旧文件
迁移完成后删除：
- Smarty 库文件
- `.tpl` 模板文件
- Smarty 缓存目录

### 2. 更新配置
移除 Smarty 相关配置，更新为 Twig 配置。

## 迁移时间估计

- 小型项目 (< 50 个模板): 1-2 周
- 中型项目 (50-200 个模板): 2-4 周
- 大型项目 (> 200 个模板): 1-2 个月

## 回滚计划

如果需要回滚，保留 Smarty 作为备用方案至少一个月。