README

轻量、快速且简单的模板引擎，您可以用PHP编写模板。

PHPTemplate是一个非常简单且轻量级的模板引擎，您可以用PHP编写模板，但仍然努力帮助您编写默认安全的模板。它提供默认安全的变量访问，以及一些您将在30秒内学会并开始使用的辅助方法！

希望PHP中能有更多的模板引擎。

-- 没有人 | 曾经。

在最简单的形式中，您可以抛入任何PHP文件，其输出将被返回。您可以可选地传递额外的变量，这些变量将在模板内部可用，并且这些变量默认会被清理，以使忘记清理任何用户输入变得困难。

简单示例

模板文件: test-template.php

<strong>Hello World</strong>

如何使用模板

$template = new Ayesh\PHPTemplate\PHPTemplate('test-template.php'); // <-- Path to the template file.
$contents = $template->render();
// $contents will contain the contents of the `test-template.php` file.

带有变量的示例

模板文件: test-template.php

Good morning <em><?= $v['name']; ?></em>
Welcome to <?= $v['sitename']; ?>

如何使用模板

$vars = [
  'name' => '<script>alert("xss!");</script>',
  'sitename' => 'PHPTemplate',
];
$template = new Ayesh\PHPTemplate\PHPTemplate('test-template.php');
$contents = $template->render($vars);

在模板内部，特殊的 $v 变量将可用，并包含您在实例化 $template 对象时提供的所有变量。

每次您访问这些变量时，它们默认都会被清理。在上面的例子中，请注意 $vars['name'] 变量包含JavaScript。如果您不清理这个变量，它将被解释为JavaScript，使您的网站容易受到跨站脚本攻击。然而，PHPTemplate库默认会清理这些变量，从而产生以下输出

Good morning <em>&lt;script&gt;alert(&quot;xss!&quot;);&lt;/script&gt;<em>,
Welcome to PHPTemplate

上述片段包含模板文件中使用的HTML，但请注意 $vars['name'] 变量已被清理为HTML实体。浏览器 不会 将其解释为JavaScript，而是会打印出以下内容，浏览器不会解释JavaScript

早上好 <script>alert("xss!");</script>

欢迎使用PHPTemplate

除了HTML清理，此库还提供URL清理。考虑以下模板

模板文件: test-template.php

<a href="<?= $v[':user_website']; ?>">User Web site</a>

注意，在上面的模板中，我们使用冒号前缀（:）访问 user_website 变量。这将向模板引擎提示我们期望URL被清理。

一个典型的攻击是用户提供了一个如 javascript:alert("xss"); 的URL，技术上是一个有效的URI，但在点击时执行JavaScript。使用 PHPTemplate，您可以轻松清理这些URL，允许 http://、https:// 和 ftp:// 协议，但不允许上述协议。

上述模板将被渲染为

$vars = [
  'user_website' => 'javascript:alert("xss");',
];
$template = new Ayesh\PHPTemplate\PHPTemplate('test-template.php');
$contents = $template->render($vars);

输出

<a href="alert(&#039;xss!&#039;);">User Web site</a>

上述模板是安全的，尽管我们使用的变量本身不安全。

请参阅完整参考以获取更多信息。

安装

您可以通过Composer轻松安装此库。

composer require ayesh/phptemplate

默认情况下，下载内容不会包含包含自动化测试中使用的某些模板的 tests 目录。如果您以 Git 克隆或任何其他方式（如 composer prefer source）下载库，请确保 tests 目录无法通过您的 web 服务器访问。这些脚本不包含任何有害内容，但会输出一些您不想要的随机字符串到浏览器。好消息是，除非您明确下载源代码，否则这些测试将不会包括在内。

安装后，您可以包含 composer 自动加载器

require 'vendor/autoload.php';

参考

访问变量

• $v['example'] : 变量默认会被 HTML 清理
• $v[':example'] : 变量会被清理以确保它是一个安全的 URL。
• $v['!example'] : 变量将 不 进行任何清理（可能不安全）。

请注意，这种数组访问方式 保证 是一个字符串。如果您访问未设置的变量，或除 字符串、浮点数或整数 之外的其他类型，将返回一个空字符串。这使得访问您不确定是否存在存在的变量变得更容易。

要访问复杂变量，您可以使用 $v->get('variable') 辅助函数。它将返回您最初设置的任何变量。这 不保证 是一个字符串，也没有进行清理。

辅助方法

PHPTemplate 提供了一些辅助方法，可以帮助您构建模板。

$v->get('variable'):

返回在 new PHPTemplate(['variable' => foo]) 调用中设置的原始 variable（本例中为 foo），如果未设置则返回空字符串。此返回值未经清理。您可以使用以下提供的辅助函数根据需要对其进行清理。

$v->escape('foo')

将提供的文本字符串转义，以确保它不包含任何会被解释为 HTML 的内容。您还可以在 HTML 属性中使用此 escape 方法，因为它也会将单引号和双引号转换为 HTML 实体。

$v->url('https://example.com')

清理提供的 URL，确保它只包含相对路径，或协议为 http://、https:// 或 ftp:// 的 URI。任何其他协议（如 javascript:）都将被删除。

$v->attributes(['foo' => 'bar')

将提供的数组扩展为 HTML 属性。在本例中，您可以使用以下模板

<a <?= $v->attributes(['href' => 'https://ayesh.me', 'rel' => 'nofollow'); ?>Click</a>`

这将得到以下结果

<a href="https://ayesh.me" rel="nofollow">Click</a>

$v->error('发生了一些错误')

这是抛出类型为 TemplateError 的错误的一个快捷方式，父调用者可以捕获它。您可能永远不需要使用此方法，但这是在您的模板无法继续且您希望终止并向父调用者报告错误的一个简单方法。

贡献

欢迎贡献！请注意，我的目标是拥有一个最简单的模板引擎，它只做该做的事，并将任何复杂的事情留给编写模板的人。性能改进和简单而有用的辅助方法将非常受欢迎。对于安全问题，请联系我，而不是在公共问题队列中报告。