1.9.4. カスタムヘルパー

Template オブジェクトにカスタムの Helpers オブジェクトを提供することができます。このカスタム Helpers オブジェクトに、好きなヘルパーメソッドを追加できます。あなたのヘルパーメソッドは、その Template インスタンスによって処理されるテンプレートファイル内で利用可能になります。

1.9.4.1. Helpers クラスの作成

最も簡単な方法は、HtmlHelpers を拡張して新しいクラスにメソッドを追加することです。

例えば、以下のカスタム Helpers クラスは、文字列をROT-13で暗号化し、適切にエスケープするメソッドを追加しています：

<?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));
    }
}

あるいは、ベースの Helpers オブジェクトを拡張し、HtmlHelperMethods トレイトを使用することもできます：

<?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));
    }
}

最後に、HTMLを全く使用しない場合は、単に Helpers クラスを拡張するだけで構いません。

<?php
namespace Project\Template\Helper;

use Qiq\Helpers;

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

1.9.4.2. Helpers の使用

カスタム Helpers クラスを作成したら、そのインスタンスを使用して Template を作成します：

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

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

これで、テンプレートファイル内でカスタムヘルパーメソッドを使用できます。

プレーンなPHPで使用する場合 ...

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

... もしくは、Qiq構文で使用する場合：

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

どちらの方法でも、出力は "Hello World!" となります。

1.9.4.3. ヘルパークラス

必要に応じて、ヘルパーのロジックをクラスに配置し、オートワイヤリングされる Qiq\Container（後述）からそのクラスのインスタンスを $this->get() を使用して取得することができます。

例えば、ROT-13のロジックをクラスに配置した場合...

<?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));
    }
}

... このようにして、カスタム Helpers オブジェクト内からそのクラスのインスタンスを get() で取得し、好きなように使用できます

<?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);
    }
}

1.9.4.4. Helpers コンテナ

Helpers クラスはオートワイヤリングされる Qiq\Container オブジェクトを使用します。カスタムヘルパーメソッド内で、$this->get() を使用して Qiq\Container からオブジェクトを取得できます。 Qiq\Container を設定するには、クラスコンストラクタのパラメータ名と値の配列を使用してインスタンス化し、それを使用して Helpers を作成します。例えば、Escape のエンコーディングを 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)
);

Qiq\Container は比較的低機能です。必要に応じて、Qiq\Container を任意の PSR-11 ContainerInterface インスタンスに置き換えることができます

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

$psr11container = new Psr11Container();

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