# view
**Repository Path**: fiberphp/view
## Basic Information
- **Project Name**: view
- **Description**: 📄 FiberPHP 视图组件 —— 支持原生 PHP / Twig 多模板引擎，适配器模式设计，开箱即用。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-09-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# FiberPHP View
FiberPHP 视图引擎：原生 PHP 模板（布局继承/区块管理/编译自动转义），可选 Twig 3.0 适配器。
## 环境要求
- PHP >= 8.3
- `fiberphp/contract`、`fiberphp/container`（框架核心契约）
- 可选 `twig/twig ^3.0`（选 'twig' 引擎时）
## 安装
```bash
composer require fiberphp/view
```
选 Twig 引擎时额外安装：
```bash
composer require twig/twig:^3.0
```
## 目录结构
```
src/
├── View.php # 视图管理器（静态入口 + 单例引擎）
├── ViewProvider.php # 服务提供者
├── helpers.php # 助手函数 view()
├── Engine/
│ ├── EngineInterface.php # 模板引擎契约
│ ├── PhpEngine.php # 原生 PHP 引擎（布局/区块/编译自动转义）
│ ├── TwigEngine.php # Twig 3.0 适配器
│ └── Compiler.php # {{ }} / {!! !!} 编译器
└── Concern/
├── ManagesLayouts.php # 布局管理 trait
└── ManagesSections.php # 区块管理 trait
```
## 配置
`config/view.php`：
```php
return [
'engine' => 'php', // 'php'（默认）或 'twig'
'paths' => [base_path('resource/views')], // 模板搜索路径
'cache_path' => runtime_path('views'), // 编译缓存目录（null 走系统临时目录）
'compile' => true, // PhpEngine：关闭后 {{ }} 不编译（前端框架冲突场景）
'twig' => [ // Twig 引擎配置
'debug' => false, // 调试模式（关闭自动转义、缓存，开启 strict_variables）
'globals' => [], // 全局模板变量
'filters' => [], // 自定义过滤器 [name => callable]
'functions' => [], // 自定义函数 [name => callable]
],
];
```
## 快速开始
### 基础渲染
```php
use FiberPHP\View\View;
// 渲染模板并返回 HTML 字符串
$html = View::render('home.index', ['title' => 'Hello']);
// 渲染模板并返回 HTTP 响应（需 fiberphp/http）
return View::response('home.index', ['title' => 'Hello']);
```
### 助手函数
```php
$html = view('home.index', ['title' => 'Hello']);
```
## 原生 PHP 模板（engine=php）
模板文件为原生 PHP，通过 `$this` 访问引擎方法。
### 变量输出
```php
Hello,
```
### 编译语法（可选，默认开启）
- `{{ $var }}` — 自动 HTML 转义输出（安全）
- `{!! $html !!}` — 原样输出（仅限可信内容）
- 关闭编译：`view.compile => false`（与 Vue 等 {{ }} 框架共存场景）
### HTML 转义
```php
escape($userInput) ?>
```
### 布局继承
页面模板 `page.php`：
```php
layout('layout'); ?>
section('title'); ?>页面标题end(); ?>
```
布局模板 `layout.php`：
```php
<?= $this->yield('title', '默认标题') ?>
yield('content') ?>
```
### 模板包含
```php
```
### 区块管理
```php
section('sidebar'); ?>
菜单项1
菜单项2
end(); ?>
push('scripts', ''); ?>
prepend('sidebar', '首页'); ?>
```
在布局中输出区块：
```php
yield('sidebar') ?>
yield('scripts') ?>
```
## Twig 模板（engine=twig）
模板名 dot 写法自动转 Twig 路径：`home.index` → `home/index.twig`。
### 基础渲染
```twig
{# home/index.twig #}
{{ title }}
Hello, {{ name }}
```
默认开启 HTML 自动转义（`autoescape: html`），调试模式（`view.twig.debug=true`）下关闭。
### 控制结构
```twig
{% if user.isAdmin %}
后台
{% endif %}
{% for item in items %}
{{ item.name }}
{% endfor %}
```
### 包含与继承
```twig
{% extends 'layout.twig' %}
{% block title %}页面标题{% endblock %}
{% block content %}
页面内容
{% endblock %}
```
```twig
{{ include('partials.menu.twig', { items: menu }) }}
```
### 自定义过滤器/函数
通过 `view.twig.filters` / `view.twig.functions` 注册：
```php
// config/view.php
'twig' => [
'filters' => [
'money' => fn($n) => '¥' . number_format($n, 2),
],
'functions' => [
'asset' => fn($path) => '/assets/' . $path,
],
],
```
模板内使用：
```twig
{{ price|money }}
{{ asset('css/app.css') }}
```
## API
### View 静态方法
| 方法 | 说明 |
|---------------------------------------------|-----------------------------------|
| `View::render($template, $data)` | 渲染模板，返回 HTML 字符串 |
| `View::response($template, $data, $status)` | 渲染模板，返回 HTTP 响应 |
| `View::engine()` | 获取引擎实例（按 view.engine 配置）|
| `View::setEngine($engine)` | 注入自定义引擎（覆盖配置） |
### PhpEngine 方法
| 方法 | 说明 |
|-----------------------------|----------------|
| `layout($template)` | 设置布局模板 |
| `section($name)` | 开始区块捕获 |
| `end()` | 结束区块捕获 |
| `yield($name, $default)` | 输出区块内容 |
| `push($name, $content)` | 追加内容到区块 |
| `prepend($name, $content)` | 前置内容到区块 |
| `include($template, $data)` | 包含子模板 |
| `escape($value)` | HTML 转义 |
### TwigEngine 方法
| 方法 | 说明 |
|----------------------------|-----------------------------------------------|
| `render($template, $data)` | 渲染 Twig 模板（dot 写法自动转路径） |
| `getEnvironment()` | 获取底层 `Twig\Environment`（扩展配置用） |
## 测试
```bash
composer install
./vendor/bin/phpunit
```
## License
MIT