Skip to content

Latest commit

 

History

History
405 lines (291 loc) · 7.57 KB

README.md

File metadata and controls

405 lines (291 loc) · 7.57 KB
Raw

EasyTpl

License Php Version GitHub tag (latest SemVer) Actions Status zh-CN readme

⚡️ 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 }} {{ $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 add custom filters.
    • default builtin filters: upper lower nl
  • support add custom directive.
    • EasyTemplate built in support layout include contents
    • ExtendTemplate built in support extends block endblock
  • support comments in templates. eg: {{# comments ... #}}

Install

  • Required PHP 8.0+

composer

composer require phppkg/easytpl

Quick start

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;

Output:

My name is INHERE,
My develop tags:

- php
- go
- java

More usage

The syntax is the same as the PHP native template, and the special syntax added is just to make it more convenient to use.

  • EasyTemplate enables output filtering by default, which can be used to render view templates.
  • TextTemplate turns off output filtering and is mainly used for text processing, code generation, etc.

Config template

use PhpPkg\EasyTpl\EasyTemplate;

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

// do something ...

more settings：

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

Echo variable

The following statements are the same, can be used to print out variable values

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

More:

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

By default, the output result will be automatically processed through htmlspecialchars, unless disabled or manually used raw filter

  • Set to disable output filtering $t->disableEchoFilter()
  • Disable output filtering in the template {{ $name | raw }}

Chained access array

Can use . to quick access array value.

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

Use in template:

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

If blocks

only 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 blocks

foreach:

tags:

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

{{ endforeach }}

with keys:

tags:

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

{{ endforeach }}

Add comments

The contents wrapped with {{ and }} will be ignored as comments.

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

multi lines:

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

Use Filters

Default built-in filters:

  • upper - equals strtoupper
  • lower - equals strtolower
  • nl - append newline \n

Using the filters

You can use the filters in any of your templates.

Regular usage:

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

Chained usage:

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

Passing non-static values:

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

Passing variables as filter parameters:

{{
    $suffix = '￥';
}}

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

Custom filters

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);
    },
]);

Use in template:

{{
  $name = 'inhere';
}}

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

Custom directives

You can use the directives implement some special logic.

EasyTemplate built in support: layout include contents

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

Use layout

  • page template home01.tpl
{{ layout('layouts/layout01.tpl') }}

on home: block body;

Use include

Use in template

{{ 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 }}
use PhpPkg\EasyTpl\ExtendTemplate;

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

Examples for extend

  • on layout file: 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 }}
  • on page file: home/index.tpl
{{ extends('layouts/main.tpl') }}

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

Rendered results

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

Dep packages

Related

License

MIT