包简介

Template Engine for lightweight templates with automatic escaping

README 文档

README

Simplates as a template engine for PHP for lightweight templates with automatic escaping

basic usage

Your PHP file:

$templateEngine = new \Hengeb\Simplates\Engine('/path/to/your/templates');
echo $templateEngine->render('user/profile', [
    'name' => 'Bob',
    'hobbys' => '<div style="position:absolute;display:grid;place-items:center;height:100dvh;background:black;inset:0;color:limegreen;font-size:400%">Your page is now mine<!--',
]);

And in /path/to/your/templates/user/profile.php (or /path/to/your/templates/user/profile.tpl.php if you prefer) put:

<h3><?=$name></h3>

<div>My Hobbys are: <?=$hobbys?></div>

This will be rendered like this:

<h3>Bob</h3>

<div>My Hobbys are: &lt;div style=&quot;position:absolute;display:grid;place-items:center;height:100dvh;background:black;inset:0;color:limegreen;font-size:400%&quot;&gt;Your page is now mine&lt;!--</div>

The strings are escaped automatically but object methods and properties can be accessed.

You can use the raw method of a variable to access the raw data:

<?=$hobbys->raw()?> or just: <?=$hobbys->raw?>

no escaping in text output

If, in the example above, you had saved your template as /path/to/your/templates/user/profile.txt.php (note the .txt in the file name), then no auto-escaping takes place but you can still use all the other features of template variables.

advanced auto-escaping feature

Object properties and return values will be auto-escaped as well. Variables can be arrays as well.

A more advaned example:

class User {
    public function __construct(public string $name, public string $hobbys)
    {
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function getHobbys(): string
    {
        return $this->hobbys;
    }
}

echo $templateEngine->render('user/list', [
    'users' => [
        new User('Alice', 'Coding'),
        new User('Bob', '<script>hijackPage();</script>'),
    ],
]);

And in your template:

<?php if(count($users) === 0): ?>
    <p>There are no users to show.</p>
<?php else: ?>
    <table>
        <tr><th>Name</th><th>Hobbys</th></tr>
        <?php foreach($users as $user): ?>
            <tr><td><?=$user->getName()?>></td><td><?=$user->getHobbys()?></tr>
        <?php endforeach; ?>
    </table>
<?php endif; ?>

This will render like this (white space has been modified in the result):

<table>
    <tr><th>Name</th><th>Hobbys</th></tr>
    <tr><td>Alice</td><td>Coding</td></tr>
    <tr><td>Bob</td><td>&lt;script&gt;hijackPage();&lt;/script&gt;</td></tr>
</table>

Dates and times

echo $templateEngine->render('now', [
    'now' => new \DateTimeImmutable('now'),
    '_timeZone' => new \DateTimeZone('Europe/Berlin'),
]);

and in your template now.tpl.php:

<div>current date: <?=$now->format('d.m.Y')?></div>

result:

<div>current date: 14.12.2024</div>

The date is converted to the provided time zone (variable named _timeZone). If you do not provide a time zone, the time zone will not be changed.

Another way is to provide the timezone name in the call of the format method:

<div>current date: <?=$now->format('d.m.Y', 'Europe/Berlin`)?></div>

global variables

In the examples above all the variables are passed in the context of the template. If a variable is used in many places you can set a global template variable like this:

$templateEngine->set('currentUser', $currentUser);
$templateEngine->set('_timeZone', new \DateTimeZone('Europe/Berlin'));

Reusing templates

You can use the extends and include methods to reuse templates:

In your template, use:

<?php $this->extends('layout', ['title' => $user->getName()]); ?>

<?php $this->include('partials/alert', ['message' => 'Your data has been saved.']); ?>

Hello, <?=$name?>!

And in layout.php put:

<!DOCTYPE html>
<html>
    <head>
        <title><?=$title->raw?></title>
    </head>
    <body>
        <h1><?=$title->raw?></h1>
        <?=$_contents->raw?>
    </body>
</html>

And in partials/alert.php put:

<div class="alert"><?=$message></div>

Result:

<!DOCTYPE html>
<html>
    <head>
        <title>Bob</title>
    </head>
    <body>
        <h1>Bob</h1>
<div class="alert">Your data has been saved.</div>
Hello, Bob!
    </body>
</html>

return values

You can return values from your template content to the calling context.

For example, if you have a template for an email you might want to use your template to generate the subject and return it:

In your template mail/confirm.txt.php:

<?php
$returnValue = $subject = 'Please confirm your email address';
?>
Hello <?=$name?>,

Please go to <?=$url?> to confirm your email address.

And in the calling context:

$body = $templateEngine->render('mail/confirm', [
    'name' => $name,
    'url' => $url,
], $subject);
$mailService->send($address, $subject, $body);

falsish values

The auto-escaping feature comes with the drawback that falsish variables cannot be checked with if ($value) or if (!empty($value)) because in PHP, objects are always truish and technically, all the template variables are object (of the TemplateVariable class).

Use the engine's check, the variable's isTrue or isEmpty methods or other means instead:

instead of:

<?php if ($array): ?>
<?php if ($isError): ?>
<?php if ($name): ?>
<?php if (!empty($mightNotBeSet)): ?>
<?php if ($checkboxValue): ?>

use

<?php if ($this->check($array)): ?> or <?php if ($array-isTrue()): ?> or <?php if (!$array-isEmpty()): ?> or <?php if (count($array)): ?>
<?php if ($this->check($isError)): ?> or <?php if ($isError-isTrue()): ?> or <?php if (!$isError-isEmpty()): ?>
<?php if ($this->check($name)): ?> or <?php if ($name-isTrue()): ?> or <?php if (!$name-isEmpty()): ?> or <?php if ("$name"): ?> or <?php if ($name != ""): ?> or <?php if ("$name" !== ""): ?>
<?php if ($this->check($mightNotBeSet)): ?>
<?php if ($this->check($checkboxValue)): ?> or <?php if ($checkboxValue-isTrue()): ?> or <?php if (!$checkboxValue-isEmpty()): ?>

the suggested means are:

<?php if ($this->check($array)): ?> or <?php if (count($array)): ?>
<?php if ($this->check($isError)): ?> or <?php if ($isError-isTrue()): ?>
<?php if ($this->check($name)): ?> or <?php if ("$name"): ?> or <?php if ($name != ""): ?> or <?php if ("$name" !== ""): ?>
<?php if ($this->check($mightNotBeSet)): ?>
<?php if ($this->check($checkboxValue)): ?> or <?php if ($checkboxValue-isTrue()): ?>

built-in methods of template variables

Template variables come with some handy methods that make writing templates cleaner. Use them like this: <?=$data->json()?>

escape(): escape HTML special characters (only needed in non-auto-escaping contexts)
raw(): do not escape (only needed in auto-escaping contexts)
json(bool $pretty = false): JSON representation of the data. Use like this:
htmlTable(): return HTML table of the array content
htmlList(string $listType = 'ol'): return HTML list of array contents
dump(): wrap value in <pre> tag
implode(string $separator = ', '): implode array list
inputHidden(string $name = ''): create HTML input element of type=hidden
input(...$attributes): create HTML input element of type=text (default) or similar types like type=date (call like this: $date->input(type: 'date')), you can also add a label with a lable attribute.
box(...$attributes): create HTML input element of type=checkbox (default) or type=radio, you can also add a label with a lable attribute.
textarea(...$attributes): create HTML textarea element.
select(array $options, ...$attributes): create HTML select element. The $options parameter is an array like [value => label, ...]

Note that methods of the actual object that is stored in the template variable are a bit harder to access if their name coincidentally matches one of the built-in methods of the template variable proxy class. You would have to use the __call method in this case: <?=$variable->__call('input', [$arguments])?>

extend the functionality

You can extend the TemplateVariable class and add your own methods. You have to extend the Engine class as well so it uses your class:

class TemplateVariable extends \Hengeb\Simplates\TemplateVariable
{
    public function bold(): string
    {
        return "<span style='font-weight:bold'>" . $this->__toString() . "</span>";
    }
}

// connect the extension to the engine
\Hengeb\Simplates\Engine::$proxyClass = TemplateVariable::class;

With this extended template engine, every template variable has a bold() method:

Hello, <?=$name->bold()?>!

This will render like this:

Hello, <span style='font-weight:bold'>Bob</span>!

Of course, you can also extend the Engine class itself to provide extra features.

hengeb/simplates 适用场景与选型建议

hengeb/simplates 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 82 次下载、GitHub Stars 达 0，最近一次更新时间为 2024 年 12 月 14 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 hengeb/simplates 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 hengeb/simplates 我们能提供哪些服务？

定制开发 / 二次开发

基于 hengeb/simplates 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

hengeb/simplates

包简介