# php模版引擎
**Repository Path**: phpyos/php-template-engine
## Basic Information
- **Project Name**: php模版引擎
- **Description**: 简易的php模板引擎,由lecms剥离而来
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# PHP 模板引擎使用文档
> 一个轻量级、高效的 PHP 模板解析器，类似 Smarty 但语法更简洁。
---
## 📑 目录
1. [特性介绍](#特性介绍)
2. [快速开始](#快速开始)
3. [目录结构](#目录结构)
4. [模板语法](#模板语法)
5. [Block 块功能](#block-块功能)
6. [高级配置](#高级配置)
7. [完整示例](#完整示例)
8. [常见问题](#常见问题)
---
## ✨ 特性介绍
### 主要特性
| 特性 | 说明 |
|------|------|
| 🚀 简洁语法 | 类似 Smarty，更易上手 |
| 🔄 变量输出 | 支持变量、数组、运算输出 |
| 📝 流程控制 | 支持循环和条件判断 |
| 📎 模板包含 | 支持子模板嵌套 |
| 🧩 Block 块 | 可复用的 UI 组件 |
| 🌐 语言包 | 多语言支持 |
| ⚡ 模板缓存 | 编译后自动缓存 |
| 🗜️ 代码压缩 | 生产环境优化 |
---
## 🚀 快速开始
### 1. 基础使用
```php
assign('title', '欢迎使用');
$view->assign('username', '张三');
$view->assign_value('count', 100);
// 显示模板
$view->display('index.htm');
?>
```
### 2. 常量说明
| 常量 | 必需 | 说明 |
|------|------|------|
| `APP_NAME` | ✅ | 应用名称，用于目录命名 |
| `RUNTIME_PATH` | ✅ | 模板编译缓存目录 |
| `VIEW_PATH` | ✅ | 原始模板目录 |
| `BLOCK_PATH` | ❌ | Block 块函数目录 |
| `DEBUG` | 推荐 | 调试模式开关 |
| `CODE_COMPRESS` | ❌ | 代码压缩（1开启，0关闭） |
---
## 📁 目录结构
```
项目根目录/
├── myapp_view/ # 模板编译目录（需写入权限）
│ └── default/ # 默认主题编译文件
├── myapp_view_diy/ # DIY 模板编译目录（可选）
├── views/ # 原始模板目录
│ └── default/ # 默认主题
│ ├── index.htm
│ ├── inc-header.htm # 包含文件自动加 inc- 前缀
│ └── inc-footer.htm
├── blocks/ # Block 函数目录
│ └── block_global_nav.lib.php
├── view.class.php # 模板类文件
└── index.php # 入口文件
```
---
## 📝 模板语法
### 1. 变量输出
```html
{$title}
用户：{$username}
ID：{$user[id]}
邮箱：{$user['email']}
名称：{$user["name"]}
总价：{@$price * $quantity}
折扣：{@$price * 0.8}
大写：{@strtoupper($name)}
```
### 2. 循环语法
```html
{loop:$users $user}
{$user[name]} - {$user[email]}
{/loop}
{loop:$products $product $key}
{$key}：{$product[name]}
{/loop}
{loop:$categories $category}
{$category[name]}
{loop:$category[items] $item}
- {$item[name]}
{/loop}
{/loop}
{if:count($users) > 0}
{loop:$users $user}
{$user[name]}
{/loop}
{else}
暂无数据
{/if}
```
### 3. 条件判断
```html
{if:$score >= 90}
优秀
{elseif:$score >= 60}
及格
{else}
不及格
{/if}
{if:$username && $is_login}
欢迎回来
{/if}
{if:$age >= 18 && $age <= 60}
符合年龄要求
{/if}
```
**支持的运算符：** `==` `===` `!=` `!==` `>` `<` `>=` `<=` `&&` `||` `!`
### 4. 包含子模板
```html
{inc:header}
{inc:common/nav}
{$title}
{inc:header}
{$content}
{inc:footer}
```
> 💡 提示：`{inc:header}` 会查找 `inc-header.htm` 文件
### 5. PHP 代码
```html
{php}
$total = 0;
foreach($items as $item) {
$total += $item['price'];
}
echo "总价：{$total}元";
{/php}
{php}
$status_map = [
1 => '待处理',
2 => '处理中',
3 => '已完成'
];
$status = $status_map[$order['status']] ?? '未知';
{/php}
状态：{$status}
```
### 6. 语言包
**PHP 端配置：**
```php
'欢迎光临',
'hello' => '你好',
'user' => [
'name' => '用户名',
'email' => '邮箱'
]
];
$_SERVER['lang'] = $lang;
$view->assign('lang', $lang);
?>
```
**模板中使用：**
```html
{lang:welcome}
{lang:hello} {$username}
{lang:user.name}: {$username}
{lang:user.email}: {$email}
```
---
## 🧩 Block 块功能
### 1. 创建 Block
文件命名规则：`block_{名称}.lib.php`
```php
'首页',
'theme' => 'light'
];
$config = array_merge($defaults, $config);
// 导航数据
$navs = [
['name' => '首页', 'url' => '/'],
['name' => '产品', 'url' => '/product'],
['name' => '关于', 'url' => '/about']
];
// 生成 HTML
$html = '';
return $html;
}
?>
```
### 2. 使用 Block
```html
{block:global_nav current="首页"}
{/block}
{block:product_list limit="10" category="hot" order="desc"}
{loop:$data $product}
{$product[name]} - {$product[price]}元
{/loop}
{$site[title]}
{lang:user_count}：{$total}
{if:$total > 0}
| ID |
{lang:name} |
{lang:email} |
{lang:role} |
{loop:$users $user}
| {$user[id]} |
{$user[name]} |
{$user[email]} |
{$user[role]} |
{/loop}
{else}
暂无数据
{/if}
{inc:footer}
```
**头部模板 (views/default/inc-header.htm)：**
```html
{$site[title]}
```
**底部模板 (views/default/inc-footer.htm)：**
```html
```
---
## ❓ 常见问题
### Q1: 模板文件找不到？
**检查：**
- [ ] `VIEW_PATH` 路径是否正确
- [ ] 文件是否在正确的主题目录下
- [ ] 文件权限是否可读
### Q2: 编译目录写入失败？
```bash
# Linux/Mac
chmod 755 runtime/
chmod 777 runtime/ # 或更宽松的权限
# Windows
# 右键属性 → 安全 → 编辑权限
```
### Q3: 如何清除缓存？
```bash
# 删除编译文件
rm -rf runtime/*.php
# 或在浏览器添加参数 ?clear_cache=1（需代码支持）
```
### Q4: 变量不显示？
**检查：**
- [ ] 是否使用 `$view->assign()` 赋值
- [ ] 变量名是否一致（区分大小写）
- [ ] 查看编译后的文件排查问题
### Q5: 如何在模板中使用函数？
```html
{@date('Y-m-d', $time)}
{@number_format($price, 2)}
{@substr($str, 0, 10)}
```
---
## 💡 最佳实践
### 性能优化
| 建议 | 说明 |
|------|------|
| 关闭 DEBUG | 生产环境设为 `false` |
| 开启压缩 | `CODE_COMPRESS = 1` |
| 使用缓存 | 编译后自动缓存 |
| 合理使用 Block | 封装重复组件 |
| 拆分模板 | 使用 `{inc:xxx}` |
### 安全建议
```php
assign('content', htmlspecialchars($user_input));
// 2. 限制 PHP 功能（可选）
// 注释掉模板引擎中的 PHP 解析代码
// 3. 路径安全
// 验证包含文件是否在允许目录内
// 4. 生产环境配置
define('DEBUG', false);
error_reporting(0);
ini_set('display_errors', 0);
?>
```
---
## 📄 许可证
本项目采用 MIT 许可证。
---
## 📝 更新日志
### Version 1.0
- ✅ 基础模板语法
- ✅ Block 块功能
- ✅ 模板缓存
- ✅ 代码压缩
- ✅ 多语言支持