README

⚡️ 简单快速PHP模板引擎。

特性

• 简单、轻量且快速。
  • 无学习成本，语法类似PHP模板
  • 直接处理并转换为原生PHP语法
  • 兼容PHP原生语法
• 支持简单的echo print语法。例如：{{ var }} {{= $var }} {{ $var }} {{ echo $var }}
  • 允许忽略前缀$，编译时自动添加。
• 支持链式访问数组值。例如：{{ $arr.0 }} {{ $map.name }} {{ $map.user.name }}
• 支持所有控制语法。例如：if, elseif, else; foreach; for; switch
• 支持PHP内置函数作为过滤器。例如：{{ $var | ucfirst }} {{ date('Y-m-d') }}
• 更安全，输出默认会通过htmlspecialchars自动处理
  • 您可以设置禁用输出过滤或手动使用raw过滤器
• 支持添加自定义过滤器。
  • 默认内置过滤器：upper lower nl
• 支持添加自定义指令。
  • EasyTemplate内置支持layout include contents
  • ExtendTemplate内置支持extends block endblock
• 支持模板中的注释。例如：{{# comments ... #}}

安装

• 需要PHP 8.0+

composer

composer require phppkg/easytpl

快速开始

use PhpPkg\EasyTpl\EasyTemplate;

$tplCode = <<<'CODE'
My name is {{ $name | strtoupper }},
My develop tags:

{{ foreach($tags as $tag) }}
- {{ $tag }}

{{ endforeach }}
CODE;

$t = new EasyTemplate();

$str = $t->renderString($tplCode, [
    'name' => 'inhere',
    'tags' => ['php', 'go', 'java'],
]);

echo $str;

输出:

My name is INHERE,
My develop tags:

- php
- go
- java

更多用法

语法与PHP原生模板相同，添加的特殊语法只是为了使其更方便使用。

• EasyTemplate默认启用输出过滤，可用于渲染视图模板。
• TextTemplate禁用输出过滤，主要用于文本处理、代码生成等。

配置模板

use PhpPkg\EasyTpl\EasyTemplate;

$t = EasyTemplate::new([
    'tplDir'   => 'path/to/templates',
    'allowExt' => ['.php', '.tpl'],
]);

// do something ...

更多设置：

/** @var PhpPkg\EasyTpl\EasyTemplate $t */
$t->disableEchoFilter();
$t->addFilter($name, $filterFn);
$t->addFilters([]);
$t->addDirective($name, $handler);

输出变量

以下语句相同，可用于打印变量值

{{ name }}
{{ $name }}
{{= $name }}
{{ echo $name }}

更多

{{ $name ?: 'inhere' }}
{{ $age > 20 ? '20+' : '<= 20' }}

默认情况下，输出结果将通过htmlspecialchars自动处理，除非禁用或手动使用raw过滤器

• 设置为禁用输出过滤$t->disableEchoFilter()
• 在模板中禁用输出过滤{{ $name | raw }}

链式访问数组

可以使用.快速访问数组值。

$arr = [
    'val0',
    'subKey' => 'val1',
];

在模板中使用

First value is: {{ $arr.0 }} // val0
'subKey' value is: {{ $arr.subKey }} // val1

如果块

仅if

{{ if ($name !== '') }}
hi, my name is {{ $name }}
{{ endif }}

if else:

hi, my name is {{ $name }}
age is {{ $age }}, and
{{ if ($age >= 20) }}
 age >= 20.
{{ else }}
 age < 20.
{{ endif }}

if...elseif...else:

hi, my name is {{ $name }}
age is {{ $age }}, and
{{ if ($age >= 50) }}
 age >= 50.
{{ elseif ($age >= 20) }}
 age >= 20.
{{ else }}
 age < 20.
{{ endif }}

For/Foreach块

foreach:

tags:

{{ foreach($tags as $tag) }}
- {{ $tag }}

{{ endforeach }}

带键

tags:

{{ foreach($tags as $index => $tag) }}
{{ $index }}. {{ $tag }}

{{ endforeach }}

添加注释

使用{{和}}包裹的内容将被视为注释。

{{# comments ... #}}{{ $name }} // inhere

多行

{{#
 this
 comments
 block
#}}{{ $name }} // inhere

使用过滤器

默认内置过滤器

• upper - 等于 strtoupper
• lower - 等于 strtolower
• nl - 添加换行符 \n

使用过滤器

您可以在任何模板中使用过滤器。

常规使用:

{{ 'inhere' | ucfirst }} // Inhere 
{{ 'inhere' | upper }} // INHERE

链式使用:

{{ 'inhere' | ucfirst | substr:0,2 }} // In
{{ '1999-12-31' | date:'Y/m/d' }} // 1999/12/31

传递非静态值:

{{ $name | ucfirst | substr:0,1 }}
{{ $user['name'] | ucfirst | substr:0,1 }}
{{ $userObj->name | ucfirst | substr:0,1 }}
{{ $userObj->getName() | ucfirst | substr:0,1 }}

将变量作为过滤器参数传递:

{{
    $suffix = '￥';
}}

{{ '12.75' | add_suffix:$suffix }} // 12.75￥

自定义过滤器

use PhpPkg\EasyTpl\EasyTemplate;

$tpl = EasyTemplate::new();
// use php built function
$tpl->addFilter('upper', 'strtoupper');

// add more
$tpl->addFilters([
    'last3chars' => function (string $str): string {
        return substr($str, -3);
    },
]);

在模板中使用

{{
  $name = 'inhere';
}}

{{ $name | upper }} // INHERE
{{ $name | last3chars }} // ere
{{ $name | last3chars | upper }} // ERE

自定义指令

您可以使用指令实现一些特殊逻辑。

EasyTemplate内置支持：layout include contents

$tpl = EasyTemplate::new();
$tpl->addDirective(
    'include',
    function (string $body, string $name) {
        /** will call {@see EasyTemplate::include()} */
        return '$this->include' . $body;
    }
);

使用布局

• 页面模板home01.tpl

{{ layout('layouts/layout01.tpl') }}

on home: block body;

使用包含

在模板中使用

{{ include('part/header.tpl', ['title' => 'My world']) }}

扩展模板

新指令

• extends 扩展布局模板文件。
  • 语法：{{ extends('layouts/main.tpl') }}
• block 定义一个新的模板块开始。
  • 语法：{{ block 'header' }}
• endblock 标记块结束。
  • 语法：{{ endblock }}

use PhpPkg\EasyTpl\ExtendTemplate;

$et = new ExtendTemplate();
$et->display('home/index.tpl');

扩展示例

• 在布局文件中：layouts/main.tpl

{{ block 'header' }}
header contents in layout main.
{{ endblock }}

{{ block 'body' }}
body contents in layout main.
{{ endblock }}

{{ block 'footer' }}
footer contents in layout main.
{{ endblock }}

• 在页面文件中：home/index.tpl

{{ extends('layouts/main.tpl') }}

{{ block 'body' }}
body contents in home index.
{{ endblock }}

渲染结果

header contents in layout main.
body contents in home index.
footer contents in layout main.

依赖包

• toolkit/fsutil
• toolkit/stdlib

相关

• https://github.com/twigphp/Twig
• https://github.com/nette/latte
• https://github.com/jenssegers/blade
• https://github.com/fenom-template/fenom
• https://github.com/pug-php/pug

许可证

MIT