エクステンションの作成
***********

.[perex]
エクステンションは、カスタムタグ、フィルタ、関数、プロバイダなどを定義できる再利用可能なクラスです。

Latteでカスタマイズしたものを別のプロジェクトで再利用したり、他の人と共有したりするときにエクステンションを作成します。
また、プロジェクトのテンプレートで使用したい特定のタグやフィルタをすべて含む、各ウェブプロジェクト用の拡張機能を作成することも便利です。


拡張機能クラス .[#toc-extension-class]
===============================

Extensionは、[api:Latte\Extension] を継承したクラスです。 Latteへの登録は、`addExtension()` を用いて（あるいは[設定ファイルによって |application:en:configuration#Latte]）行います。

```php
$latte = new Latte\Engine;
$latte->addExtension(new MyLatteExtension);
```

複数の拡張機能を登録し、それらが同じ名前のタグ、フィルタ、または関数を定義している場合、最後に追加された拡張機能が優先されます。これは、拡張機能がネイティブタグ/フィルタ/関数をオーバーライドできることも意味しています。

クラスに変更を加え、自動リフレッシュがオフになっていない場合、Latteは自動的にテンプレートを再コンパイルします。

クラスは以下のメソッドのいずれかを実装することができます。

```php
abstract class Extension
{
	/**
	 * Initializes before template is compiler.
	 */
	public function beforeCompile(Engine $engine): void;

	/**
	 * Returns a list of parsers for Latte tags.
	 * @return array<string, callable>
	 */
	public function getTags(): array;

	/**
	 * Returns a list of compiler passes.
	 * @return array<string, callable>
	 */
	public function getPasses(): array;

	/**
	 * Returns a list of |filters.
	 * @return array<string, callable>
	 */
	public function getFilters(): array;

	/**
	 * Returns a list of functions used in templates.
	 * @return array<string, callable>
	 */
	public function getFunctions(): array;

	/**
	 * Returns a list of providers.
	 * @return array<mixed>
	 */
	public function getProviders(): array;

	/**
	 * Returns a value to distinguish multiple versions of the template.
	 */
	public function getCacheKey(Engine $engine): mixed;

	/**
	 * Initializes before template is rendered.
	 */
	public function beforeRender(Template $template): void;
}
```

拡張機能がどのようなものであるかについては、組み込みの"CoreExtension":https://github.com/nette/latte/blob/master/src/Latte/Essential/CoreExtension.php をご覧ください。


beforeCompile(Latte\Engine $engine): void  .[method]
----------------------------------------------------

テンプレートがコンパイルされる前に呼び出されます。このメソッドは、例えばコンパイルに関連する初期化などに使用することができます。


getTags(): array  .[method]
---------------------------

テンプレートがコンパイルされたときに呼び出されます。[タグ解析関数 |#Tag Parsing Function]である *タグ名 => callable* の連想配列を返します。

```php
public function getTags(): array
{
	return [
		'foo' => [FooNode::class, 'create'],
		'bar' => [BarNode::class, 'create'],
		'n:baz' => [NBazNode::class, 'create'],
		// ...
	];
}
```

`n:baz` タグは純粋なn:attributeを表し、すなわち属性としてのみ記述可能なタグである。

`foo` と`bar` のタグの場合、Latte はそれらがペアであるかどうかを自動的に認識し、ペアであれば`n:inner-foo` と`n:tag-foo` の接頭辞を持つ変種を含めて n:attribute を使って自動的に記述することができます。

このようなn:attributeの実行順序は`getTags()` が返す配列の中の順序で決まります．従って、`n:foo` は`n:bar` の前に実行されます。 `<div n:bar="..." n:foo="...">`.

複数の拡張子にわたってn:属性の順序を決定する必要がある場合には、`order()` ヘルパーメソッドを使用して下さい。`before` xor`after` パラメータはどのタグがタグの前と後に順序付けられるかを決定します。

```php
public function getTags(): array
{
	return [
		'foo' => self::order([FooNode::class, 'create'], before: 'bar')]
		'bar' => self::order([BarNode::class, 'create'], after: ['block', 'snippet'])]
	];
}
```


getPasses(): array .[method]
----------------------------

テンプレートがコンパイルされるときに呼び出されます。ASTを走査し修正するいわゆる[コンパイラパスを |#compiler passes]表す関数である、連想配列 *name pass => callable* を返します。

ここでも、`order()` ヘルパー・メソッドが使えます。`before` または`after` パラメータの値には、before/after all の意味を持つ `*` を指定することができます。

```php
public function getPasses(): array
{
	return [
		'optimize' => [Passes::class, 'optimizePass'],
		'sandbox' => self::order([$this, 'sandboxPass'], before: '*'),
		// ...
	];
}
```


beforeRender(Latte\Engine $engine): void .[method]
--------------------------------------------------

これは各テンプレートのレンダリングの前に呼び出されます。このメソッドは、例えば、レンダリング中に使用される変数を初期化するために使用することができます。


getFilters(): array .[method]
-----------------------------

テンプレートがレンダリングされる前に呼び出されます。[フィルタを |extending-latte#filters]連想配列で返します *フィルタ名 => callable*.

```php
public function getFilters(): array
{
	return [
		'batch' => [$this, 'batchFilter'],
		'trim' => [$this, 'trimFilter'],
		// ...
	];
}
```


getFunctions(): array .[method]
-------------------------------

テンプレートがレンダリングされる前に呼び出されます。[関数を |extending-latte#functions]連想配列で返します *関数名 => callable*.

```php
public function getFunctions(): array
{
	return [
		'clamp' => [$this, 'clampFunction'],
		'divisibleBy' => [$this, 'divisibleByFunction'],
		// ...
	];
}
```


getProviders(): array .[method]
-------------------------------

テンプレートがレンダリングされる前に呼び出されます。プロバイダの配列を返します。プロバイダは通常、ランタイムにタグを使用するオブジェクトです。これらのプロバイダーは、`$this->global->...` を介してアクセスします。

```php
public function getProviders(): array
{
	return [
		'myFoo' => $this->foo,
		'myBar' => $this->bar,
		// ...
	];
}
```


getCacheKey(Latte\Engine $engine): mixed .[method]
--------------------------------------------------

テンプレートがレンダリングされる前に呼び出されます。戻り値はコンパイルされたテンプレートファイルの名前に含まれるハッシュを持つキーの一部になります。したがって、異なる戻り値に対して、Latteは異なるキャッシュファイルを生成します。


Latteはどのように動くのか？ .[#toc-how-does-latte-work]
============================================

カスタムタグやコンパイラパスの定義方法を理解するためには、Latteがどのように動作しているかを理解することが不可欠です。

Latteのテンプレートコンパイルは簡単に言うと以下のような仕組みになっています。

- まず、**レクサー**がテンプレートのソースコードを処理しやすいように小さな断片（トークン）にトークン化します。
- 次に、**パーサ**がトークンのストリームを意味のあるノードツリー（抽象構文木、AST)に変換します。
- 最後に、コンパイラはASTからテンプレートをレンダリングするPHPクラスを **生成** して、それをキャッシュします。

実は、コンパイルはもう少し複雑です。Latteは2つ**のレキサとパーサを持っています。1つはHTMLテンプレート用、もう1つはタグの中にあるPHPのようなコード用のレキサです。また、トークン化の後にパーシングが実行されるわけではなく、レキサーとパーサーが2つの「スレッド」で並行して実行され、協調しているのです。ロケットサイエンスですね :-)

さらに、すべてのタグは独自のパーシング ルーチンを持っています。パーサーはタグに遭遇すると、そのパース関数を呼び出します（[Extension::getTags() |#getTags]を返します）。
その仕事は、タグの引数と、ペアタグの場合は内部のコンテンツを解析することです。それはASTの一部となる*node*を返します。詳細については、[タグ解析関数を |#Tag parsing function]参照してください。

パーサーが作業を終えると、テンプレートを表す完全なASTができあがります。ルート・ノードは`Latte\Compiler\Nodes\TemplateNode` です。ツリー内の個々のノードは、タグだけでなく、HTML要素、その属性、タグの内部で使用されるすべての式などを表します。

この後、いわゆる[コンパイラー・パスが |#Compiler passes]登場します。これは、ASTを修正する関数（[Extension::getPasses() |#getPasses]によって返されます）です。

テンプレートのコンテンツの読み込みから、パース、結果のファイルの生成までの全プロセスは、このコードでシーケンス化することができ、実験して中間結果をダンプすることができます。

```php
$latte = new Latte\Engine;
$source = $latte->getLoader()->getContent($file);
$ast = $latte->parse($source);
$latte->applyPasses($ast);
$code = $latte->generate($ast, $file);
```


ASTの例 .[#toc-example-of-ast]
----------------------------

ASTのイメージをつかむために、サンプルを追加します。これはソースのテンプレートです。

```latte
{foreach $category->getItems() as $item}
	<li>{$item->name|upper}</li>
	{else}
	no items found
{/foreach}
```

そして、これがASTの形式での表現です。

/--pre
Latte\Compiler\Nodes\<b>TemplateNode</b>(
   Latte\Compiler\Nodes\<b>FragmentNode</b>(
      - Latte\Essential\Nodes\<b>ForeachNode</b>(
           expression: Latte\Compiler\Nodes\Php\Expression\<b>MethodCallNode</b>(
              object: Latte\Compiler\Nodes\Php\Expression\<b>VariableNode</b>('$category')
              name: Latte\Compiler\Nodes\Php\<b>IdentifierNode</b>('getItems')
           )
           value: Latte\Compiler\Nodes\Php\Expression\<b>VariableNode</b>('$item')
           content: Latte\Compiler\Nodes\<b>FragmentNode</b>(
              - Latte\Compiler\Nodes\<b>TextNode</b>('  ')
              - Latte\Compiler\Nodes\<b>Html\ElementNode</b>('li')(
                   content: Latte\Essential\Nodes\<b>PrintNode</b>(
                      expression: Latte\Compiler\Nodes\Php\Expression\<b>PropertyFetchNode</b>(
                         object: Latte\Compiler\Nodes\Php\Expression\<b>VariableNode</b>('$item')
                         name: Latte\Compiler\Nodes\Php\<b>IdentifierNode</b>('name')
                      )
                      modifier: Latte\Compiler\Nodes\Php\<b>ModifierNode</b>(
                         filters:
                            - Latte\Compiler\Nodes\Php\<b>FilterNode</b>('upper')
                      )
                   )
                )
            )
            else: Latte\Compiler\Nodes\<b>FragmentNode</b>(
               - Latte\Compiler\Nodes\<b>TextNode</b>('no items found')
            )
        )
   )
)
\--


カスタムタグ .[#toc-custom-tags]
==========================

新しいタグを定義するには、3つのステップが必要です。

[- タグのパース関数を |#tag parsing function]定義する (タグをノードにパースする役割を果たす)
- ノードクラスを作成する([PHPコードの生成と |#generating PHP code] [ASTのトラバースを |#AST traversing]担当する)
-[Extension::getTags() |#getTags]を使ってタグを登録する


タグのパース関数 .[#toc-tag-parsing-function]
-------------------------------------

タグのパース処理は、そのパース関数([Extension::getTags() |#getTags]によって返されるもの)によって処理されます。この関数の仕事は、タグの中にあるすべての引数を解析し、チェックすることです(これを行うにはTagParserを使用します)。
さらに、タグがペアである場合、TemplateParserに依頼して内部のコンテンツを解析して返します。
この関数はノードを生成して返します．ノードは通常，`Latte\Compiler\Nodes\StatementNode` の子であり，これがASTの一部となります．

各ノードに対してクラスを作成し，パース関数を静的ファクトリとしてその中にエレガントに配置します．例として、おなじみの`{foreach}` タグを作ってみましょう。

```php
use Latte\Compiler\Nodes\StatementNode;

class ForeachNode extends StatementNode
{
	// a parsing function that just creates a node for now
	public static function create(Latte\Compiler\Tag $tag): self
	{
		$node = $tag->node = new self;
		return $node;
	}

	public function print(Latte\Compiler\PrintContext $context): string
	{
		// code will be added later
	}

	public function &getIterator(): \Generator
	{
		// code will be added later
	}
}
```

解析関数`create()` はオブジェクト[api:Latte\Compiler\Tag] に渡され、タグの基本情報（クラシックタグか n:attribute か、どの行にあるかなど）を持ち、主に`$tag->parser` にある[api:Latte\Compiler\TagParser] にアクセスします。

タグが引数を持たなければならない場合は、`$tag->expectArguments()` を呼び出して引数の存在をチェックします。`$tag->parser` オブジェクトのメソッドはそれらをパースするために利用できます。

-`parseExpression(): ExpressionNode` PHP 風の式 (例:`10 + 3`) に対応します。
-`parseUnquotedStringOrExpression(): ExpressionNode` 式または引用符で囲まれていない文字列に対して
-`parseArguments(): ArrayNode` 配列の内容 (例:`10, true, foo => bar`)
-`parseModifier(): ModifierNode` 修飾子に対して (例:`|upper|truncate:10`)
-`parseType(): expressionNode` typehint 用 (例:`int|string` または`Foo\Bar[]`)

と、トークンを直接操作する低レベルの[api:Latte\Compiler\TokenStream] があります。

-`$tag->parser->stream->consume(...): Token`
-`$tag->parser->stream->tryConsume(...): ?Token`

Latte は PHP の構文を少しずつ拡張しています。例えば、修飾子を追加したり、三項演算子を短くしたり、 単純な英数字の文字列を引用符なしで書けるようにしたりしています。これが、PHPの代わりに*PHP-like*という言葉を使う理由です。したがって、`parseExpression()` メソッドは`foo` を`'foo'` のようにパースします。
さらに、*unquoted-string* は、引用符で囲む必要がなく、同時に英数字である必要もない文字列の特殊なケースです。例えば、`{include ../file.latte}` タグのファイルへのパスがこれにあたります。これをパースするには、`parseUnquotedStringOrExpression()` メソッドを使用します。

.[note]
Latteの一部であるノードクラスを勉強することは，パース処理の細かな部分をすべて学ぶのに最適な方法です．

`{foreach}` タグに戻りましょう。このタグでは、`expression + 'as' + second expression` という形式の引数を想定して、次のように解析しています。

```php
use Latte\Compiler\Nodes\StatementNode;
use Latte\Compiler\Nodes\Php\ExpressionNode;
use Latte\Compiler\Nodes\AreaNode;

class ForeachNode extends StatementNode
{
	public ExpressionNode $expression;
	public ExpressionNode $value;

	public static function create(Latte\Compiler\Tag $tag): self
	{
		$tag->expectArguments();
		$node = $tag->node = new self;
		$node->expression = $tag->parser->parseExpression();
		$tag->parser->stream->consume('as');
		$node->value = $parser->parseExpression();
		return $node;
	}
}
```

変数`$expression` と`$value` に書き込んだ式は、サブノードを表しています。

.[tip]
サブノードを持つ変数は **public** として定義し、必要であれば[以降の処理ステップで |#Compiler Passes]変更できるようにする。また、[トラバースの |#AST Traversing]ために**利用可能にする**ことも必要である。

私たちのようなペアのタグの場合、メソッドはTemplateParserにタグの内部コンテンツを解析させなければなりません。これは`yield` で処理され、''[inner content, end tag]'' というペアが返されます。内部コンテンツを変数`$node->content` に格納します。

```php
public AreaNode $content;

public static function create(Latte\Compiler\Tag $tag): \Generator
{
	// ...
	[$node->content, $endTag] = yield;
	return $node;
}
```

`yield` キーワードによって`create()` メソッドが終了し、TemplateParser に制御が戻されます。その後、`create()` に制御が戻され、中断したところから続行されます。`yield`, メソッドを使用すると、自動的に`Generator` が返されます。

また、`yield` にタグ名の配列を渡して、終了タグの前に出現した場合にパースを停止させることもできます。これは `{foreach}...{else}...{/foreach}`の実装に役立ちます。`{else}` が発生した場合、それ以降の内容を`$node->elseContent` にパースします。

```php
public AreaNode $content;
public ?AreaNode $elseContent = null;

public static function create(Latte\Compiler\Tag $tag): \Generator
{
	// ...
	[$node->content, $nextTag] = yield ['else'];
	if ($nextTag?->name === 'else') {
		[$node->elseContent] = yield;
	}

	return $node;
}
```

ノードを返すとタグのパースが完了する。


PHPコードの生成 .[#toc-generating-php-code]
-------------------------------------

各ノードは`print()` メソッドを実装する必要があります。テンプレートの指定された部分をレンダリングするPHPコード(ランタイムコード)を返します。パラメータとしてオブジェクト[api:Latte\Compiler\PrintContext] が渡されます。このオブジェクトには、 結果のコードの組み立てを簡略化する便利なメソッド`format()` があります。

`format(string $mask, ...$args)` メソッドは、マスクに以下のプレースホルダーを受け付けます。
-`%node` はノードを表示します。
-`%dump` PHP に値をエクスポートします。
-`%raw` は、テキストを変換せずに直接挿入します。
-`%args` は、関数呼び出しの引数として ArrayNode をプリントします。
-`%line` は行番号付きのコメントを出力します。
-`%escape(...)` 内容をエスケープします。
-`%modify(...)` モディファイアを適用する
-`%modifyContent(...)` ブロックにモディファイアを適用


`print()` 関数は次のようになります (簡単のために`else` ブランチは無視します)。

```php
public function print(Latte\Compiler\PrintContext $context): string
{
	return $context->format(
		<<<'XX'
			foreach (%node as %node) %line {
				%node
			}

			XX,
		$this->expression,
		$this->value,
		$this->position,
		$this->content,
	);
}
```

変数`$this->position` は[api:Latte\Compiler\Node] クラスですでに定義されており、パーサーによって設定されます。この変数には、ソースコード内のタグの位置を行と列の番号で表した[api:Latte\Compiler\Position] オブジェクトが含まれます。

ランタイムコードは、補助変数を使用することができます。テンプレート自身が使用する変数との衝突を避けるために、それらの変数の前に`$ʟ__` という文字を付けるのが慣例となっています。

また、実行時に任意の値を使用することができ、それらは[Extension::getProviders() |#getProviders]メソッドを使用してプロバイダの形でテンプレートに渡されます。これらの値には`$this->global->...` を使ってアクセスします。


ASTのトラバース .[#toc-ast-traversing]
--------------------------------

ASTツリーを深くトラバースするためには、`getIterator()` メソッドを実装する必要があります。これによって、サブノードへのアクセスが可能になる。

```php
public function &getIterator(): \Generator
{
	yield $this->expression;
	yield $this->value;
	yield $this->content;
	if ($this->elseContent) {
		yield $this->elseContent;
	}
}
```

`getIterator()` は参照を返すことに注意。これは、ノードビジターが個々のノードを他のノードに置き換えることができるようにするものである。

.[warning]
ノードがサブノードを持つ場合、このメソッドを実装し、すべてのサブノードを利用できるようにする必要がある。さもなければ、セキュリティホールができてしまう。例えば、サンドボックスモードではサブノードを制御できず、許可されていないコンストラクトがその中で呼び出されないようにすることができない。

子ノードがない場合でも、メソッド本体に`yield` キーワードが存在しなければならないので、次のように記述する。

```php
public function &getIterator(): \Generator
{
	if (false) {
		yield;
	}
}
```


補助ノード.[#toc-auxiliarynode]
--------------------------

Latte用の新しいタグを作成する場合は、ASTツリーでそれを表現する専用のノードクラスを作成することをお勧めします（上記の例の`ForeachNode` クラスを参照）。このクラスでは、`print()` メソッドのボディと、`getIterator()` メソッドによってアクセス可能になったノードのリストをコンストラクタのパラメータとして渡すことができます：

```php
// Latte\Compiler\Nodes\Php\Expression\AuxiliaryNode
// or Latte\Compiler\Nodes\AuxiliaryNode

$node = new AuxiliaryNode(
	// body of the print() method:
	fn(PrintContext $context, $argNode) => $context->format('myFunc(%node)', $argNode),
	// nodes accessed via getIterator() and also passed into the print() method:
	[$argNode],
);
```


コンパイラのパス .[#toc-compiler-passes]
================================

コンパイラパスは、ASTを変更したり、ASTの情報を収集するための関数です。これらは[Extension::getPasses() |#getPasses]メソッドによって返されます。


ノードトラバーサ .[#toc-node-traverser]
-------------------------------

AST を扱う最も一般的な方法は、[api:Latte\Compiler\NodeTraverser] を使うことです。

```php
use Latte\Compiler\Node;
use Latte\Compiler\NodeTraverser;

$ast = (new NodeTraverser)->traverse(
	$ast,
	enter: fn(Node $node) => ...,
	leave: fn(Node $node) => ...,
);
```

enter* 関数 (すなわち visitor) は、ノードが最初に遭遇したとき、そのサブノードが処理される前に呼び出される。leave*関数は、すべてのサブノードが訪問された後に呼び出される。
よくあるパターンは、*enter*で何らかの情報を収集し、それに基づいて*leave*で修正を行うというものである。leave*が呼ばれた時点で、ノード内のすべてのコードはすでに訪問され、必要な情報が収集されている。

ASTを変更するには？最も簡単な方法は、単にノードのプロパティを変更することである。もう一つの方法は、新しいノードを返すことで、ノードを完全に置き換えることである。例：次のコードは，ASTのすべての整数を文字列に変更する（例えば，42は`'42'` に変更される）．

```php
use Latte\Compiler\Nodes\Php;

$ast = (new NodeTraverser)->traverse(
	$ast,
	leave: function (Node $node) {
		if ($node instanceof Php\Scalar\IntegerNode) {
            return new Php\Scalar\StringNode((string) $node->value);
        }
	},
);
```

ASTは数千のノードを含むことがあり，そのすべてを走査するのは時間がかかる場合がある．場合によっては，完全な探索を避けることも可能である．

ツリー内のすべての`Html\ElementNode` を探す場合、一度`Php\ExpressionNode` を見てしまうと、その子ノードをすべてチェックする意味がないことがわかります。なぜなら、HTML は式の中に入れることができないからです。この場合、トラバーサーにクラス・ノードに再帰しないように指示することができます。

```php
$ast = (new NodeTraverser)->traverse(
	$ast,
	enter: function (Node $node) {
		if ($node instanceof Php\ExpressionNode) {
			return NodeTraverser::DontTraverseChildren;
        }
        // ...
	},
);
```

特定の1つのノードだけを探している場合は、そのノードを見つけた後に探索を完全に中断することも可能です。

```php
$ast = (new NodeTraverser)->traverse(
	$ast,
	enter: function (Node $node) {
		if ($node instanceof Nodes\ParametersNode) {
			return NodeTraverser::StopTraversal;
        }
        // ...
	},
);
```


ノードヘルパー .[#toc-node-helpers]
----------------------------

クラス[api:Latte\Compiler\NodeHelpers] は、特定のコールバックなどを満たす AST ノードを見つけることができるメソッドをいくつか提供します。いくつかの例を示します。

```php
use Latte\Compiler\NodeHelpers;

// finds all HTML element nodes
$elements = NodeHelpers::find($ast, fn(Node $node) => $node instanceof Nodes\Html\ElementNode);

// finds first text node
$text = NodeHelpers::findFirst($ast, fn(Node $node) => $node instanceof Nodes\TextNode);

// converts PHP value node to real value
$value = NodeHelpers::toValue($node);

// converts static textual node to string
$text = NodeHelpers::toText($node);
```