Voltのpartialとincludeの違い - こももりりうん

partialとincludeの違いがわからず適当に使っていたら軽くハマったのでその時の調査メモ。

2種類の方法

Voltで他のファイルからテンプレートを読み込んで埋め込むにはpartialとincludeの2種類の方法がある。
普通のテンプレートをただ単に読み込んではめ込むだけならどちらも同じような結果だが、内部の処理が結構違うのでゴリゴリVolt書くならその辺意識して書いたほうが良さげ。

partial

書き方は2通りあってただ単に読み込む書き方と、テンプレートに変数を渡す書き方がある。
文字列を返す関数なので{{ }}で括る。
第一引数には読み込むファイルを指定するが拡張子は不要。
第二引数に配列を指定するとテンプレートに別名で値を渡せる。

{{ partial("partials/footer") }}
{{ partial("partials/footer", ['hoge': huge]) }}

実体はVoltではなくViewのメソッド
- コンパイル時にはテンプレートは読み込まれない
- メソッドの実行時に初めて処理される
- 実行時に毎回Volt周りの処理が走るので遅い
View側で改めて拡張子のチェックからコンパイルとPHPの実行が行われる
- なのでVoltの中に違うテンプレートエンジンのテンプレートを埋め込める

include

partialと同様に2種類の書き方がある。partialとは違って{% %}で括るので注意。

{% include "partials/footer.volt" %}

{# 値を渡す場合はwithの後ろに配列で変数名（key）と中身（Value）を渡す #}
{# コンパイル時にpartialに置き換わるためファイルパスには拡張子を付けない #}
{% include "partials/footer" with ['hoge': huge] %}

挙動的には『指定したファイルをそのままはめ込んでVoltとして解釈されてPHPにコンパイル』って感じ
- 拡張子が『.html』だろうが『.php』だろうが問答無用でVoltとして扱われる
コンパイル時に処理さるらしい
- なので読み込むファイルに構文エラーがあると全体がエラーになる
- コンパイル後のPHPをキャッシュしてコンパイルしないような設定の場合は恩恵が大きい
  - 手元のVMで計測してみたら15%くらいパフォーマンス良かった
withを使うとコンパイル時にpartialに置き換えられる
- partialなのでファイルパスに拡張子は付けてはいけない

まとめ

どっちでもいいような場合は実行速度的な観点からinclude推奨。
ただしpartialじゃないとダメだったりpartialのほうが速度を犠牲にしても何らかのメリットがある場合はpartialもしくはinclude withを使う。

テンプレートを使いまわす上で別名の変数を付けたほうが捗る場合
テンプレートにVoltから値を渡したい場合
違うテンプレートエンジンでテンプレートを読み込みたい場合
Voltで構文エラーが出てしまうようなHTMLを書いていてVoltのコンパイルをスルーしたい場合
- JavaScriptでテンプレートエンジン使ってたりするとよくある