README

简单的轻量级PHP模板引擎。

通过变量、条件块和PHP函数作为过滤器来增强文件。通过在文件中任何位置添加变量占位符 <% placeholder %> 创建可重用的模板，并使内容根据您提供的参数动态更改。

功能
需求
安装
- VS Code的模板语法高亮显示
用法

功能

将字符串模板解析为字符串
- 用提供的参数替换变量占位符
- 将过滤器函数应用于变量
  - 使用内置过滤器或提供自定义函数
- 使用 <% if %> 块来条件性地解析模板
  - 使用 <% else %> 块来提供不满足条件时的替代内容
将模板文件解析为字符串
- 将整个文件作为字符串解析
提供自定义正则表达式模式以使用自定义语法解析函数
从模板获取所有变量

需求

PHP >= 8.2
Composer

安装

使用Composer安装

composer require matronator/parsem

然后只需将依赖项添加到您的PHP文件中

use Matronator\Parsem\Parser;

VS Code的模板语法高亮显示

为了获取模板文件（突出显示字符串中的 <% variable|placeholders %> 和 <% if %><% else %><% endif %>）的语法高亮显示，您可以从VS Code扩展市场下载MTRGen Templates Syntax Highlighting 扩展。

用法

模板语法

条件

您可以通过使用 <% if %> 和 <% endif %> 标签在模板中使用条件。条件必须是一个有效的PHP表达式，它将被评估，如果它返回 true，则标签之间的内容将被包含在最终输出中。

您还可以使用 <% else %> 标签来提供不满足条件时的替代内容。

为了在条件中使用提供的参数数组中的变量，您必须在变量名前使用 $ 符号，如下所示： <% if $variable == 'value' %>。 $ 符号用于区分模板变量和关键字，例如 true 或 null。

示例

some:
  key
  <% if $variable == 'value' %>
  with value
  <% else %>
  without value
  <% endif %>

如果您提供一个参数 ['variable' => 'value']，最终输出将是这个

some:
  key
  with value

如果您提供一个参数 ['variable' => 'other value']，最终输出将是这个

some:
  key
  without value

变量

变量用 <% 和 %> 包围，可选地在两侧有空间（两者 <%nospace%> 和 <% space %> 都有效），并且名称必须是一个带可选下划线的字母数字字符串（此正则表达式 [a-zA-Z0-9_]+?）。

默认值

变量可以可选地有一个默认值，如果解析期间没有为该变量提供参数，则将使用该默认值。您可以指定默认值如下：<% variable='Default' %>

如果您要使用过滤器，默认值将位于过滤器之前，即：<% variable='Default'|filter %>

如果默认值为空（即<% var= %>），它将被视为null。

过滤器

您可以选择通过将管道符号|放在变量名后面，然后是过滤器来为变量提供过滤器（管道符号|周围没有空格），如下所示：<% variable|filter %>。

过滤器可以是任何以变量作为函数参数的PHP函数。

示例

如果在模板中我们有<% foo|strtoupper %>，并提供参数['foo' => 'hello world']，最终的（解析）输出将是这样的：HELLO WORLD。

过滤器还可以有除了变量本身之外的其他参数。要将额外的参数传递给过滤器，可以写成这样：<% var|filter:'arg','arg2',20,true %>。冒号之后的每个参数都由逗号分隔，可以具有任何标量类型作为值。

第一个参数始终是我们正在声明过滤器的变量，之后的任何参数都是传递给该变量的。

示例

如果我们有<% foo|substr:1,3 %>，并提供参数['foo' => 'abcdef']，过滤器将使用提供的参数这样调用：substr('abcdef', 1, 3)。因此，最终解析的输出将是这样的：bcd。

到目前为止，您可以为每个变量声明指定一个过滤器，但将来可能会改变。

内置过滤器

有几个内置过滤器您可以使用

upper - 将变量转换为大写

lower - 将变量转换为小写

upperFirst - 将变量的第一个字符转换为大写

lowerFirst - 将变量的第一个字符转换为小写

first - 返回变量的第一个字符

last - 返回变量的最后一个字符

camelCase - 将变量转换为驼峰式

snakeCase - 将变量转换为蛇形

kebabCase - 将变量转换为短横线

pascalCase - 将变量转换为PascalCase

titleCase - 将变量转换为标题案

length - 返回变量的长度

reverse - 反转变量

random - 从变量中返回一个随机字符

truncate - 截断变量到指定的长度

在代码中使用

解析字符串或文件

有两个主要函数可能会对您最有用：parseString和parse。这两个都是静态函数，使用方法如下

use Matronator\Parsem\Parser;

// parseString()
echo Parser::parseString('some <%text%>.', ['text' => 'value']);
// Output: some value.

// parse()
$arguments = [
    'variableName' => 'value',
    'key' => 'other value',
];
$parsedFile = Parser::parse('filename.yaml', $arguments);
echo $parsedFile;
// Output: Will print the parsed contents of the file as string.

方法

`Parser::parseString`

/**
 * Parses a string, replacing all template variables with the corresponding values passed in `$arguments`.
 * @return mixed The parsed string or the original `$string` value if it's not string
 * @param mixed $string String to parse. If not provided with a string, the function will return this value
 * @param array $arguments Array of arguments to find and replace while parsing `['key' => 'value']`
 * @param bool $strict [optional] If set to `true`, the function will throw an exception if a variable is not found in the `$arguments` array. If set to `false` null will be used.
 * @param string|null $pattern [optional] You can provide custom regex with two matching groups (for the variable name and for the filter) to use custom template syntax instead of the default one `<% name|filter %>`
 * @throws RuntimeException If a variable is not found in the `$arguments` array and `$strict` is set to `true`
 */
Parser::parseString(mixed $string, array $arguments = [], bool $strict = true, ?string $pattern = null): mixed

`Parser::parse`

/**
 * @param string $filename Path to the file to parse
 * @see Parser::parseString() for rest of the parameter descriptions
 */
Parser::parse(string $filename, array $arguments = [], bool $strict = true, ?string $pattern = null): string

matronator / parsem

维护者

详细信息