PHPackages                             youniwemi/string-template - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. youniwemi/string-template

ActiveLibrary

youniwemi/string-template
=========================

StringTemplate is a very simple but powefull string template engine for php. It allows named and nested substutions as well as conditionnals et custom filters (originaly a fork of nicmart/StringTemplate)

v0.2.2(2y ago)0496MITPHPPHP >=7.2

Since Sep 14Pushed 2y agoCompare

[ Source](https://github.com/Youniwemi/StringTemplate)[ Packagist](https://packagist.org/packages/youniwemi/string-template)[ RSS](/packages/youniwemi-string-template/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (1)Versions (4)Used By (0)

StringTemplate
==============

[](#stringtemplate)

[![Build Status](https://github.com/youniwemi/StringTemplate/actions/workflows/php.yml/badge.svg?branch=master)](https://github.com/youniwemi/StringTemplate/actions/workflows/php.yml)[![Packagist](https://camo.githubusercontent.com/4b7a2428ee06a1085597229f4189306c9b5f96f8b82518180e8d009fd6dc9ed4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f796f756e6977656d692f737472696e672d74656d706c6174652e737667)](https://packagist.org/packages/youniwemi/string-template/stats)[![Packagist](https://camo.githubusercontent.com/7d2cc325b669bf181317cc48ddc384dc67ab7353c59e8227a6888f252c4929f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f796f756e6977656d692f737472696e672d74656d706c6174652e737667)](https://packagist.org/packages/youniwemi/string-template/stats)

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
---

[](#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
-----

[](#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' => 'John'
    ]);
```

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
--------------

[](#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
----------------

[](#where-is-it-used)

I use StringTemplate in [Instareza](https://www.instareza.com), a booking system for activities, as well as in [Mail Control](https://www.wpmailcontrol.com) for its newsletter upcoming feature.

Install
-------

[](#install)

The best way to install StringTemplate is [through composer](http://getcomposer.org).

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](http://getcomposer.org/doc/00-intro.md#globally).

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

```