README

StringTemplate is a very simple string template engine for php (and a fork of nicmart/StringTemplate).

It allows named and nested substutions as well as conditionnals et custom filters.

For installing instructions, go to the end of this README.

Why

I have often struggled against sprintf's lack of a named placeholders feature, so I have decided to write once and for all a simple component that allows you to render a template string in which placeholders are named.

Furthermore, its placeholders can be nested as much as you want (multidimensional arrays allowed).

Usage

Simply create an instance of Youniwemi\StringTemplate\Engine, and use its render method.

Placeholders are delimited by default by { and }, but you can specify others through the class constructor.

$engine = new Youniwemi\StringTemplate\Engine;

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

You can also provide an array value:

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

Nested array values are allowed too! Example:

//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']
    ]);

Object values will be converted to strings:

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

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

You can change the delimiters as you want:

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

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

You can use a simple condition:

$engine = new Youniwemi\StringTemplate\Engine();

//Returns Oh! You
$engine->render(
    'Oh! {#name}{test}{/name}',
    [
        'name' => true,
        'test' => 'You'
    ]);

You can use a simple condition with else:

$engine = new Youniwemi\StringTemplate\Engine();

//Returns Oh! My
$engine->render(
    'Oh! {#name}{test}{#else}My{/name}',
    [
        'name' => false,
        'test' => 'You'
    ]);

You can use a simple filters ( lower|upper|esc_html ):

$engine = new Youniwemi\StringTemplate\Engine();

//Returns Oh! JOHN
$engine->render(
    'Oh! {name|upper}',
    [
        'name' => 'John'
    ]);

You can add you own filters:

$engine = new Youniwemi\StringTemplate\Engine('{','}', [
    'ucfist' => 'ucfirst',
    'esc_html' =>  function($string){ return htmlentities($string, ENT_NOQUOTES); } // override a default filter
]);

//Returns Oh! <script>John</script>'
$engine->render(
    'Oh! {name|esc_html}',
    [
        'name' => '<script>John</script>'
    ]);

You can use closures a values

$engine = new Youniwemi\StringTemplate\Engine();

//Returns Oh! John
$engine->render(
    'Oh! {name|upper}',
    [
        'name' => function() {
            return 'John';
        }
    ]);

You can use closures can use the variables

$engine = new Youniwemi\StringTemplate\Engine();

//Returns Oh! John Doe
$engine->render(
    'Oh! {name}',
    [
        'first' => 'John',
        'last' => 'Doe',
        'name' => function($values) {
            return $values['first'].' '.$values['last'];
        }
    ]);

And lastly, you can use sprintf formats:

$engine = new Youniwemi\StringTemplate\Engine;

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

NestedKeyArray

In addition to iteration with nested keys, the library offers a class that allows you to access a multidimensional array with flatten nested keys as the ones seen above. It's called NestedKeyArray.

Example:

use Youniwemi\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

Where is it used

I use StringTemplate in Instareza, a booking system for activities, as well as in Mail Control for its newsletter upcoming feature.

Install

The best way to install StringTemplate is through composer.

Just create a composer.json file for your project:

{
    "require": {
        "youniwemi/string-template": "~0.2"
    }
}

Then you can run these two commands to install it:

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

or simply run composer install if you have have already installed the composer globally.

Then you can include the autoloader, and you will have access to the library classes:

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