refactor: refactor and update template structure and logic

.gitignore

@@ -20,3 +20,4 @@ vendor/
 bin/php-cs-fixer
 /plugin/local/
 node_modules/
+*caches/

README.md

@@ -6,23 +6,26 @@
 [![Actions Status](https://github.com/phppkg/easytpl/workflows/Unit-Tests/badge.svg)](https://github.com/phppkg/easytpl/actions)
 [![zh-CN readme](https://img.shields.io/badge/中文-Readme-brightgreen.svg?style=for-the-badge&maxAge=2592000)](README.zh-CN.md)
 
-⚡️ Simple and fastly template engine for PHP
+⚡️ Simple and fastly template engine for PHP.
 
 ## Features
 
 - It's simple, lightweight and fastly.
   - No learning costs, syntax like PHP template
   - It is simply processed and converted into native PHP syntax
   - Compatible with PHP native syntax
-- support simple echo print syntax. eg: `{{= $var }}` `{{ $var }}` `{{ echo $var }}`
-- support all control syntax. such as `if,elseif,else;foreach;for;switch`
+- support simple echo print syntax. eg: `{{ var }}` `{{= $var }}` `{{ $var }}` `{{ echo $var }}`
+  - allow ignore prefix `$`, will auto append on compile.
 - support chained access array value. eg: `{{ $arr.0 }}` `{{ $map.name }}` `{{ $map.user.name }}`
+- support all control syntax. such as `if,elseif,else;foreach;for;switch`
+- support php builtin function as filters. eg: `{{ $var | ucfirst }}`  `{{ date('Y-m-d') }}`
 - More secure, the output will be processed automatically through `htmlspecialchars` by default
   - You can set to disable output filtering or manually use the `raw` filter
-- support php builtin function as filters. eg: `{{ $var | ucfirst }}`
 - support add custom filters.
   - default builtin filters: `upper` `lower` `nl`
 - support add custom directive.
+  - `EasyTemplate` built in support `include`: `{{ include('parts/header.tpl') }}`
+  - `ExtendTemplate` built in support `extends` `block` `endblock`
 - support comments in templates. eg: `{{# comments ... #}}`
 
 ## Install
@@ -305,17 +308,69 @@ $tpl->addDirective(
     'include',
     function (string $body, string $name) {
         /** will call {@see EasyTemplate::include()} */
-        return '$this->' . $name . $body;
+        return '$this->include' . $body;
     }
 );
 ```
 
-Use in template:
+**Use in template**
 
 ```php
-
 {{ include('part/header.tpl', ['title' => 'My world']) }}
+```
+
+## Extends template
+
+New directives:
+
+- `extends` extends a layout template file.
+  - syntax: `{{ extends('layouts/main.tpl') }}`
+- `block` define a new template block start.
+  - syntax: `{{ block 'header' }}`
+- `endblock` mark a block end.
+  - syntax: `{{ endblock }}`
+
+```php
+use PhpPkg\EasyTpl\ExtendTemplate;
+
+$et = new ExtendTemplate();
+$et->render('home/index.tpl');
+```
+
+### Examples for extend
 
+- on layout file: `layouts/main.tpl`
+
+```php
+{{ block 'header' }}
+header contents in layout main.
+{{ endblock }}
+
+{{ block 'body' }}
+body contents in layout main.
+{{ endblock }}
+
+{{ block 'footer' }}
+footer contents in layout main.
+{{ endblock }}
+```
+
+- on page file: `home/index.tpl`
+
+```php
+{{ extends('layouts/main.tpl') }}
+
+{{ block 'body' }}
+body contents in home index.
+{{ endblock }}
+```
+
+**Rendered results**
+
+```text
+header contents in layout main.
+body contents in home index.
+footer contents in layout main.
 ```
 
 ## Dep packages

README.zh-CN.md

@@ -14,15 +14,18 @@
   - 无学习成本
   - 仅仅简单处理并转换为原生PHP语法
   - 兼容PHP原生语法使用
-- 更加简单的输出语法。 例如：`{{= $var }}` `{{ $var }}` `{{ echo $var }}`
-- 支持所有控制语法。 例如 `if,elseif,else;foreach;for;switch`
+- 更加简单的输出语法。 例如：`{{ 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` 过滤器
-- 支持使用PHP内置函数作为过滤器。 例如：`{{ $var | ucfirst }}`
 - 支持添加自定义过滤器
   - 默认内置过滤器：`upper` `lower` `nl`
 - 支持添加自定义指令，提供自定义功能
+  - `EasyTemplate` 内置支持 `include` `contents`
+  - `ExtendTemplate` 提供模板继承功能. 内置支持 `extends` `block` `endblock`
 - 支持模板中添加注释。 例如: `{{# comments ... #}}`
 
 ## 安装
@@ -300,21 +303,70 @@ $tpl->addFilters([
 
 ```php
 $tpl = EasyTemplate::new();
-$tpl->addDirective(
-    'include',
-    function (string $body, string $name) {
-        /** will call {@see EasyTemplate::include()} */
-        return '$this->' . $name . $body;
-    }
-);
+$tpl->addDirective('include',function (string $body, string $name) {
+    /** will call {@see EasyTemplate::include()} */
+    return '$this->include' . $body;
+});
 ```
 
-在模板中使用:
+**在模板中使用**:
 
 ```php
-
 {{ include('part/header.tpl', ['title' => 'My world']) }}
+```
+
+## `extend` 模板
+
+新增指令:
+
+- `extends` 定义继承一个父模板.
+  - 语法: `{{ extends('layouts/main.tpl') }}`
+- `block` 定义开始一个新的模板块.
+  - 语法: `{{ block 'header' }}`
+- `endblock` 标记一个模板块结束.
+  - 语法: `{{ endblock }}`
+
+```php
+use PhpPkg\EasyTpl\ExtendTemplate;
+
+$et = new ExtendTemplate();
+$et->render('home/index.tpl');
+```
+
+### `extend` 模板使用示例
 
+- 基础布局文件: `layouts/main.tpl`
+
+```php
+{{ 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`
+
+```php
+{{ extends('layouts/main.tpl') }}
+
+{{ block 'body' }}
+body contents in home index.
+{{ endblock }}
+```
+
+**渲染结果**
+
+```text
+header contents in layout main.
+body contents in home index.
+footer contents in layout main.
 ```
 
 ## Dep packages