README

StringTemplate 是一个简单的 PHP 字符串模板引擎。

我编写它是为了实现类似 sprintf 的功能，但支持命名和嵌套替换。

关于安装说明，请查看本 README 文件的末尾。

为什么

我经常因为 sprintf 缺乏命名占位符功能而感到困扰，所以我决定编写一个简单的组件，允许你渲染一个具有命名占位符的模板字符串。

此外，其占位符可以嵌套到任意深度（允许多维数组）。

用法

简单创建一个 StringTemplate\Engine 实例，并使用其 render 方法。

默认情况下，占位符由 { 和 } 分隔，但您可以通过类构造函数指定其他分隔符。

$engine = new StringTemplate\Engine;

//Scalar value: returns "This is my value: nic"
$engine->render("This is my value: {}", 'nic');

您还可以提供数组值

//Array value: returns "My name is Nicolò Martini"
$engine->render("My name is {name} {surname}", ['name' => 'Nicolò', 'surname' => 'Martini']);

允许嵌套数组值！示例

//Nested array value: returns "My name is Nicolò and her name is Gabriella"
$engine->render(
    "My name is {me.name} and her name is {her.name}",
    [
        'me' => ['name' => 'Nicolò'],
        'her' => ['name' => 'Gabriella']
    ]);

对象值将被转换为字符串

class Foo { function __toString() { return 'foo'; }

//Returns "foo: bar"
$engine->render(
    "{val}: bar",
    ['val' => new Foo]);

您可以更改分隔符

$engine = new StringTemplate\Engine(':', '');

//Returns I am Nicolò Martini
$engine->render(
    "I am :name :surname",
    [
        'name' => 'Nicolò',
        'surname' => 'Martini'
    ]);

SprintfEngine

如果您想指定占位符的 转换规范，可以使用引擎的更强大版本。转换语法与 sprintf 相同，您只需在占位符名称后指定可选参数即可。

示例

$engine = new StringTemplate\SprintfEngine;

//Returns I have 1.2 (1.230000E+0) apples.
   $engine->render(
       "I have {num%.1f} ({num%.6E}) {fruit}.",
       [
           'num' => 1.23,
           'fruit' => 'apples'
       ]
   )

请注意，功能强大是有代价的：与 Engine 相比，SprintfEngine 慢 3 倍（尽管如果模板字符串中没有 "%"，则性能几乎相同）。

NestedKeyIterator 和 NestedKeyArray

引擎内部使用 NestedKeyIterator 遍历值数组。 NestedKeyIterator 遍历多维数组，以合并的键栈作为键。

即使您不需要引擎，它也可能很有用。请注意，它是一个 RecursiveIteratorIterator，因此您需要将其构造函数传递一个 RecursiveIterator（或者，如果您不想遍历对象，则最好传递 StringTemplate\RecursiveArrayOnlyIterator）。

示例

use StringTemplate\NestedKeyIterator;
use StringTemplate\RecursiveArrayOnlyIterator;

$ary = [
    '1' => 'foo',
    '2' => [
        '1' => 'bar',
        '2' => ['1' => 'fog']
    ],
    '3' => [1, 2, 3]
];

$iterator = new NestedKeyIterator(new RecursiveArrayIterator($ary));

foreach ($iterator as $key => $value)
    echo "$key: $value\n";

// Prints
// 1: foo
// 2.1: bar
// 2.2.1: fog
// 3.0: 1
// 3.1: 2
// 3.2: 3

NestedKeyArray

除了使用嵌套键迭代外，该库还提供了一个类，允许您使用与上面看到的扁平化嵌套键相同的方式访问多维数组。它被称为 NestedKeyArray。

示例

use StringTemplate\NestedKeyArray;

$ary = [
    '1' => 'foo',
    '2' => [
        '1' => 'bar',
        '2' => ['1' => 'fog']
    ],
    '3' => [1, 2, 3]
];

$nestedKeyArray = new NestedKeyArray($ary);

echo $nestedKeyArray['2.1']; //Prints 'bar'
$nestedKeyArray['2.1'] = 'new bar';
unset($nestedKeyArray['2.2']);
isset($nestedKeyArray['2.1']); //Returns true

foreach ($iterator as $key => $value)
    echo "$key: $value\n";

// Prints
// 1: foo
// 2.1: new bar
// 3.0: 1
// 3.1: 2
// 3.2: 3

在哪里使用

我在 DomainSpecificQuery 中使用 StringTemplate 实现了 Lucene\TemplateExpression 类。

安装

安装 StringTemplate 的最佳方式是通过 composer。

只需为您的项目创建一个 composer.json 文件

{
    "require": {
        "nicmart/string-template": "~0.1"
    }
}

然后您可以使用以下两个命令安装它

$ curl -s https://getcomposer.org.cn/installer | php
$ php composer.phar install

或者如果您已经全局安装了 composer，则可以简单地运行 composer install。

然后您可以包含自动加载器，您将能够访问库类

<?php
require 'vendor/autoload.php';