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 }}

{{ $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

License

MIT

phppkg / easytpl

Maintainers

Details