2.9.4. Custom Helpers

You can provide your Template objects with a custom Helpers object. In that custom Helpers object, you can add any helper methods you like. Your helper methods will available inside template files processed by that Template instance.

2.9.4.1. Creating A Helpers Class

The easiest thing to do is extend HtmlHelpers and add a method on that new class.

For example, the following custom Helpers class adds a method to ROT-13 a string, escaping it appropriately:

<?php
namespace Project\Template\Helper;

use Qiq\Helper\Html\HtmlHelpers;

class CustomHelpers extends HtmlHelpers
{
    public function rot13(string $str) : string
    {
        return $this->h(str_rot13($str));
    }
}

Alternatively, you can extend the base Helpers object, and use the HtmlHelperMethods trait:

<?php
namespace Project\Template\Helper;

use Qiq\Helper\Html\HtmlHelperMethods;
use Qiq\Helpers;

class CustomHelpers extends Helpers
{
    use HtmlHelperMethods;

    public function rot13(string $str) : string
    {
        return $this->h(str_rot13($str));
    }
}

Finally, if you are not using HTML at all, you can just extend the Helpers class.

<?php
namespace Project\Template\Helper;

use Qiq\Helpers;

class CustomHelpers extends Helpers
{
    public function rot13(string $str) : string
    {
        return str_rot13($str);
    }
}

2.9.4.2. Using Your Helpers

Once you have a custom Helpers class, create your Template with an instance of it:

use Project\Template\Helper\CustomHelpers;
use Qiq\Template;

$template = Template::new(
    paths: ...,
    helpers: new CustomHelpers(),
);

Now you can use your custom helper methods in a template file, either in plain PHP ...

<?= $this->rot13('Uryyb Jbeyq!'); ?>

... or in Qiq syntax:

{{= rot13 ('Uryyb Jbeyq!') }}

Either way, the output will be "Hello World!".

2.9.4.3. Helper Classes

If you like, you can put your helper logic in a class, then retrieve an instance of that class from the autowiring Qiq\Container (described below) using $this->get().

For example, if you put the ROT-13 logic into a class ...

<?php
namespace Project\Template\Helper;

use Qiq\Helper\Html\Escape;

class Rot13
{
    public function __construct(protected Escape $escape)
    {
    }

    public function __invoke(string $str): string
    {
        return $this->escape->h(str_rot13($str));
    }
}

... you can then get() an instance of that class from inside your custom Helpers object and use it as you wish:

<?php
namespace Project\Template\Helper;

use Project\Template\Helper\Rot13;
use Qiq\Helper\Html\HtmlHelpers;

class CustomHelpers extends HelperHelpers
{
    public function rot13(string $str) : string
    {
        return $this->get(Rot13::class)->__invoke($str);
    }
}

2.9.4.4. Helpers Container

The Helpers class uses an autowiring Qiq\Container object. In your custom helper methods, you can use $this->get() to retrieve an object from the Qiq\Container.

To configure the Qiq\Container, instantiate it with an array of class constructor parameter names and values, and create your Helpers with it. For example, to change the Escape encoding to something other than UTF-8:

use Project\Template\Helper\CustomHelpers;
use Qiq\Container;
use Qiq\Helper\Html\Escape;
use Qiq\Template;

$container = new Container([
    Escape::class => [
        'encoding' => 'EUC-JP'
    ],
]);

$template = Template::new(
    paths: ...,
    helpers: new CustomHelpers($container)
);

The Qiq\Container is relatively low-powered. If you wish, you can replace the Qiq\Container with any PSR-11 ContainerInterface instance:

use Project\Template\Helper\CustomHelpers;
use Project\Psr11Container;
use Qiq\Template;

$psr11container = new Psr11Container();

$template = Template::new(
    paths: ...,
    helpers: new CustomHelpers($psr11container)
);