包简介

A lightweight, secure PHP template engine supporting {{ $variable }}, @include(), and @foreach()/@endforeach directives.

README 文档

README

A lightweight, secure PHP template engine for processing plain HTML files.

Features

Directive	Syntax	Description
Variable output	`{{ $name }}`	Inserts a parameter value (HTML-escaped)
Include	`@include(path/to/partial.html)`	Embeds another template
Conditional	`@if($var) … @else … @endif`	Renders content conditionally
Loop	`@foreach($items) … @endforeach`	Iterates over an array parameter
Loop (alias)	`@foreach($items as $item) … @endforeach`	Iterates with a custom item alias
Loop (key => value)	`@foreach($items as $k => $v) … @endforeach`	Iterates with key and value aliases

Security built-in

All variable output is HTML-escaped (htmlspecialchars) — no raw HTML injection.
@include is path-traversal safe — files outside the configured base directory are rejected.
Circular @include chains are detected and stopped (max depth: 10).
Null bytes in template paths are rejected.

Requirements

PHP 8.1 or higher

Installation

composer require tandrezone/ztemp

Quick Start

<?php

use Tandrezone\Ztemp\TemplateEngine;

$engine = new TemplateEngine(__DIR__ . '/templates');

$html = $engine->render('page.html', [
    'title' => 'Hello World',
    'name'  => 'Alice',
]);

echo $html;

Template Syntax

Variables — `{{ $name }}`

Use double curly braces to output a parameter. The value is automatically HTML-escaped.

<!-- templates/greeting.html -->
<p>Hello, {{ $name }}!</p>
<p>You have {{ $count }} messages.</p>

$engine->render('greeting.html', [
    'name'  => 'Bob',
    'count' => 3,
]);
// → <p>Hello, Bob!</p>
//   <p>You have 3 messages.</p>

Missing variables are silently removed from the output (no placeholder leaks).

Include — `@include(path)`

Embed one template inside another. The path is relative to the engine's base directory.

<!-- templates/layout.html -->
<!DOCTYPE html>
<html>
<head><title>{{ $title }}</title></head>
<body>
@include(header.html)
<main>{{ $body }}</main>
</body>
</html>

<!-- templates/header.html -->
<header><h1>{{ $title }}</h1></header>

All parameters are automatically forwarded to included templates.

Security note: Paths containing ../ or absolute paths (e.g. /etc/passwd) that resolve outside the base directory will throw a RuntimeException.

Conditionals — `@if(...) … @else … @endif`

Conditionals support either:

Variable existence checks ($var, $user.name)
Comparisons ($age >= 18, $name == "Alice")

Function calls inside @if(...) are rejected.

@if($isLoggedIn)
  <p>Welcome back!</p>
@else
  <p>Please sign in.</p>
@endif

You can also wrap the if-body in { ... }:

@if($name){<strong>{{ $name }}</strong>}@endif

Foreach — `@foreach($param) … @endforeach`

Iterate over an array parameter. Three styles are supported.

Default style (implicit `$item` alias)

<!-- templates/list.html -->
<ul>
@foreach($items)
  <li>{{ $item }}</li>
@endforeach
</ul>

$engine->render('list.html', [
    'items' => ['apple', 'banana', 'cherry'],
]);

Custom item alias — `@foreach($items as $alias)`

<!-- templates/list.html -->
<ul>
@foreach($items as $fruit)
  <li>{{ $fruit }}</li>
@endforeach
</ul>

Key => value aliases — `@foreach($items as $key => $val)`

Use this form to access the array key alongside the value, or to iterate over associative arrays with named fields.

<!-- templates/attributes.html -->
<dl>
@foreach($attributes as $k => $v)
  <dt>{{ $k }}</dt>
  <dd>{{ $v }}</dd>
@endforeach
</dl>

$engine->render('attributes.html', [
    'attributes' => ['color' => 'red', 'size' => 'large'],
]);

Associative / object array (default alias)

<!-- templates/users.html -->
<table>
@foreach($users)
  <tr>
    <td>{{ $item.name }}</td>
    <td>{{ $item.email }}</td>
  </tr>
@endforeach
</table>

The same works with a custom alias or key=>value syntax:

@foreach($users as $user)
  <p>{{ $user.name }}</p>
@endforeach

@foreach($users as $idx => $user)
  <p>{{ $idx }}: {{ $user.name }}</p>
@endforeach

$engine->render('users.html', [
    'users' => [
        ['name' => 'Alice', 'email' => 'alice@example.com'],
        ['name' => 'Bob',   'email' => 'bob@example.com'],
    ],
]);

If the referenced variable does not exist or is not an array the block is removed from the output.

Nested foreach

@foreach blocks can be nested to any depth.

<!-- templates/catalog.html -->
@foreach($categories)
<h2>{{ $item.name }}</h2>
<ul>
@foreach($tags)
  <li>{{ $item }}</li>
@endforeach
</ul>
@endforeach

When the outer item is an associative array, its fields are also available to the inner @foreach by their key name, so an inner loop can iterate over a sub-array field of the current outer element:

@foreach($users)
<p>{{ $item.name }}</p>
<ul>
@foreach($skills)
  <li>{{ $item }}</li>
@endforeach
</ul>
@endforeach

$engine->render('users.html', [
    'users' => [
        ['name' => 'Alice', 'skills' => ['PHP', 'JS']],
        ['name' => 'Bob',   'skills' => ['Python']],
    ],
]);

API Reference

`TemplateEngine::__construct(string $basePath = '')`

Parameter	Description
`$basePath`	Absolute path to the directory that contains your templates. When empty, template paths are treated as-is (absolute paths allowed).

Throws RuntimeException if the supplied base path does not exist.

`TemplateEngine::render(string $templatePath, array $params = []): string`

Parameter	Description
`$templatePath`	Path to the template file, relative to `$basePath`.
`$params`	Associative array of parameters available inside the template.

Returns the fully rendered string. Throws RuntimeException on file-not-found, path traversal, or excessive include depth.

Example

See examples/index.php for a complete working demo:

php examples/index.php

Running Tests

composer install
./vendor/bin/phpunit

Security Considerations

What is safe

Variable values are always HTML-escaped — you cannot inject raw HTML or JavaScript through {{ $var }}.
@include resolves paths against the configured base directory and rejects any path that resolves outside it.

What to watch out for

Do not put untrusted content directly in template files — only pass untrusted data through the $params array.
The @foreach body is part of the template (trusted), not the data. Only {{ $item }} / {{ $item.key }} placeholders inside the body are data-driven and escaped.

License

MIT

tandrezone/ztemp 适用场景与选型建议

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

它主要适用于以下技术方向：「templating」「template」「engine」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

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

围绕 tandrezone/ztemp 我们能提供哪些服务？

定制开发 / 二次开发

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

BUG 修复 & 性能优化

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

项目外包 & 长期维护

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

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

与 tandrezone/ztemp 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

shoot/shoot 40

Shoot aims to make providing data to your templates more manageable

plasticstudio/silverstripe-seo 2

A SilverStripe module to optimise the Meta, crawling, indexing, and sharing of your website content (forked from Cyber-Duck/Silverstripe-SEO)

ouxsoft/phpmarkup 0

A Processor for Markup written in PHP. Allows extraction of Markup into a data structure, orchestrated nested manipulation of said structure, and output as (optimized) Markup.

koolreport/twig 0

Allow KoolReport to use twig template engine to render view

xtompie/tpl 0

Simple template engine

gurubob/ascii-table 2

Simple ASCII output of array data

tandrezone/ztemp

包简介

关键字：

README 文档

README

Features

Security built-in

Requirements

Installation

Quick Start

Template Syntax

Variables — `{{ $name }}`

Include — `@include(path)`

Conditionals — `@if(...) … @else … @endif`

Foreach — `@foreach($param) … @endforeach`

Default style (implicit `$item` alias)

Custom item alias — `@foreach($items as $alias)`

Key => value aliases — `@foreach($items as $key => $val)`

Associative / object array (default alias)

Nested foreach

API Reference

`TemplateEngine::__construct(string $basePath = '')`

`TemplateEngine::render(string $templatePath, array $params = []): string`

Example

Running Tests

Security Considerations

What is safe

What to watch out for

License

tandrezone/ztemp 适用场景与选型建议

与 tandrezone/ztemp 相关的其它包

统计信息

GitHub 信息

其他信息

tandrezone/ztemp

包简介

关键字：

README 文档

README

Features

Security built-in

Requirements

Installation

Quick Start

Template Syntax

Variables — {{ $name }}

Include — @include(path)

Conditionals — @if(...) … @else … @endif

Foreach — @foreach($param) … @endforeach

Default style (implicit $item alias)

Custom item alias — @foreach($items as $alias)

Key => value aliases — @foreach($items as $key => $val)

Associative / object array (default alias)

Nested foreach

API Reference

TemplateEngine::__construct(string $basePath = '')

TemplateEngine::render(string $templatePath, array $params = []): string

Example

Running Tests

Security Considerations

What is safe

What to watch out for

License

tandrezone/ztemp 适用场景与选型建议

与 tandrezone/ztemp 相关的其它包

统计信息

GitHub 信息

其他信息

Variables — `{{ $name }}`

Include — `@include(path)`

Conditionals — `@if(...) … @else … @endif`

Foreach — `@foreach($param) … @endforeach`

Default style (implicit `$item` alias)

Custom item alias — `@foreach($items as $alias)`

Key => value aliases — `@foreach($items as $key => $val)`

`TemplateEngine::__construct(string $basePath = '')`

`TemplateEngine::render(string $templatePath, array $params = []): string`