TemplateRenderer
in package
uses
FieldTrait
メールテンプレート（ファイル経路・文字列直接入力）の描画を担う。
Twig（tpl_twig 有効時）→ 既存 ACMS テンプレートパイプライン、の2段で処理する。 「描画」に責務を限定し、送信（Engine）とは分離する（Symfony の Mailer/Mime/BodyRenderer 分割と同型）。
Table of Contents
Methods
- getMailTxt() : string
- メールテンプレートの解決
- getMailTxtFromTxt() : string
- 文字列直接入力 (フォームの件名・本文など運営者の管理画面入力) からメール本文を組み立てる。
- buildFieldTrait() : array<string|int, mixed>|null
- フィールドを連想配列として組み立て
- resolveTemplateUrlsTrait() : array<string|int, mixed>
- toStructured の出力に対し、path フィールドの URL 解決と html フィールドの 絶対化（テンプレート出力固有）を適用する。
- buildMailTwigContext() : array<string, mixed>
- Field を Twig コンテキスト辞書に組み立てる。
- mailTwig() : Twig
- メール用 Twig サービスをサービスコンテナから取得する。
- renderAcmsMailPipeline() : string
- メールテキストを既存の ACMS テンプレートパイプラインで組み立てる。
- renderMailTwigIfEnabled() : string
- メールテンプレ文字列を指定の Twig サービスで評価する (Twig → ACMS の 2 段の 1 段目)。
- resolveTemplateUrlsInGroupRowTrait() : array<string|int, mixed>
- グループ内の 1 行に含まれるマルチ項目（連想配列構造）に対して URL 解決を適用。
- resolveTemplateUrlsInMultiEntryTrait() : array<string|int, mixed>
- マルチ項目フィールドエントリ（'value'/'array' を持つ）に対して URL 解決を適用。
Methods
getMailTxt()
メールテンプレートの解決
public
getMailTxt(string $path, Field $field[, string|null $charset = null ]) : string
Parameters
- $path : string
- $field : Field
- $charset : string|null = null
Return values
stringgetMailTxtFromTxt()
文字列直接入力 (フォームの件名・本文など運営者の管理画面入力) からメール本文を組み立てる。
public
getMailTxtFromTxt(string $txt, Field $field) : string
tpl_twig 有効時はサンドボックス専用の Twig サービス (template.mail.twig.sandboxed) で評価してから ACMS パイプラインへ渡す。ファイル経路 (self::getMailTxt()) と同じく 「self::renderMailTwigIfEnabled() → self::renderAcmsMailPipeline()」の 2 段で処理する。
Parameters
- $txt : string
- $field : Field
Return values
stringbuildFieldTrait()
フィールドを連想配列として組み立て
protected
buildFieldTrait(Field|Field_Validation $field[, string|null $scp = null ]) : array<string|int, mixed>|null
Parameters
- $field : Field|Field_Validation
- $scp : string|null = null
-
子フィールドとして再帰したときの名前（takeover キーの prefix に使う）
Return values
array<string|int, mixed>|null —フィールドが空の場合は null
resolveTemplateUrlsTrait()
toStructured の出力に対し、path フィールドの URL 解決と html フィールドの 絶対化（テンプレート出力固有）を適用する。
protected
resolveTemplateUrlsTrait(array<string|int, mixed> $data, Field|Field_Validation $field) : array<string|int, mixed>
- マルチ項目フィールド (['value' => {...}, 'array' => [...]]) の中の path / html
- グループ内マルチ項目（連番キーの行配列の中の各 baseName）の path / html
単一値フィールドや、グループ内単一値フィールドには URL 解決を適用しない（旧挙動）。
Parameters
- $data : array<string|int, mixed>
- $field : Field|Field_Validation
Return values
array<string|int, mixed>buildMailTwigContext()
Field を Twig コンテキスト辞書に組み立てる。
private
buildMailTwigContext(Field|null $field) : array<string, mixed>
公開側 V2 モジュール / API と同じ FieldTrait::buildFieldTrait() で構造化するため、
Twig からは {{ name.value }} / {{ name.array }} や、メディアフィールドの
{{ photo.value.path }} など公開側と同じ形でアクセスできる。Field オブジェクトは渡さず、
すべて連想配列に展開されるためサンドボックス (メソッド・プロパティアクセス禁止) とも整合する。
takeover (Field 全体の acmsSerialize) はメール本文に露出すると情報漏えいになるため除外する。
Parameters
- $field : Field|null
-
受け取り側のシグネチャ統一のため null を許容する。null のときは空辞書を返す。
Return values
array<string, mixed>mailTwig()
メール用 Twig サービスをサービスコンテナから取得する。
private
mailTwig("template.mail.twig"|"template.mail.twig.sandboxed" $key) : Twig
同じ Twig クラスを設定違いで別キー登録している:
template.mail.twig… ファイル経路 (制作者)。フル機能・非サンドボックスtemplate.mail.twig.sandboxed… フォーム直接入力 (運営者)。サンドボックス
Parameters
- $key : "template.mail.twig"|"template.mail.twig.sandboxed"
-
コンテナ登録キー
Return values
TwigrenderAcmsMailPipeline()
メールテキストを既存の ACMS テンプレートパイプラインで組み立てる。
private
renderAcmsMailPipeline(string $txt, Field $field) : string
var ブロック展開 → template.acms → Field 変数差し込み → IF 展開、の順に通す。
Twig 評価は呼び出し側 (getMailTxt / getMailTxtFromTxt) の責務とし、
このメソッドでは一切行わない。これにより、ファイル経路 (getMailTxt) で Twig レンダ済みの
出力を再び Twig 評価してしまう二重レンダリング (= ユーザー入力フィールド値に含まれる
{{ }} がサンドボックス非経由で評価される SSTI) を防ぐ。
Parameters
- $txt : string
- $field : Field
Return values
stringrenderMailTwigIfEnabled()
メールテンプレ文字列を指定の Twig サービスで評価する (Twig → ACMS の 2 段の 1 段目)。
private
renderMailTwigIfEnabled("template.mail.twig"|"template.mail.twig.sandboxed" $serviceKey, string $tpl, Field $field[, string|null $name = null ]) : string
評価トリガーは公開側テーマと同じく tpl_twig のみ (TwigPolicy::isEnabled())。無効時は Twig を 評価せず $tpl をそのまま返し、後段の ACMS パイプライン (self::renderAcmsMailPipeline()) だけで 処理する。内容推測やフラグでの分岐はしない。これにより getMailTxt (ファイル経路) / getMailTxtFromTxt (文字列直接入力) の双方が「renderMailTwigIfEnabled → renderAcmsMailPipeline」という 同一の流れになる。
信頼境界はサービスキーで切り替える: template.mail.twig はファイル経路 (制作者) のフル機能、 template.mail.twig.sandboxed はフォーム直接入力 (運営者) のサンドボックス評価で SSTI を防ぐ。 フィールド値 (フォーム送信値など) はコンテキストとして渡すだけで、Twig は 1 回しか実行しないため 送信者入力が Twig として再評価されることはない。
Twig 評価が失敗した場合は本文を空に倒さず、Twig 未評価の元テキストへフォールバックする。 「評価できなかったものは評価しない (リテラルのまま後段 ACMS パイプラインへ流す)」とすることで、 サイレントな本文・件名の欠落を防ぎつつ、未評価のため SSTI も生じない。
捕捉は Throwable とする。Twig はレンダリング中の例外を RuntimeException にラップするが、
テンプレートのコンパイル時や self::buildMailTwigContext() (Field 構造化) で
\Error / \TypeError が出る経路もあり、\Exception だけではメール送信フローを
fatal 終了させ得るため。
Parameters
- $serviceKey : "template.mail.twig"|"template.mail.twig.sandboxed"
-
コンテナ登録キー
- $tpl : string
-
評価するテンプレート文字列
- $field : Field
-
Twig コンテキストの元になる Field
- $name : string|null = null
-
レンダの論理名。autoescape が 'name' 戦略の経路 (template.mail.twig) では この拡張子で html / エスケープなしを判定するためファイル名を渡す。autoescape=false のサンドボックス 経路 (template.mail.twig.sandboxed) では論理名が autoescape に影響しないため null とし、 renderString の既定名に委ねる
Return values
string —Twig 評価結果。tpl_twig 無効時・評価失敗時は Twig 未評価の $tpl
resolveTemplateUrlsInGroupRowTrait()
グループ内の 1 行に含まれるマルチ項目（連想配列構造）に対して URL 解決を適用。
private
resolveTemplateUrlsInGroupRowTrait(array<string|int, mixed> $row, Field|Field_Validation $field) : array<string|int, mixed>
グループ内単一値は ['value' => x] の形なのでスキップ。 グループ内マルチ項目は ['alt' => x, 'path' => y, ...] の形。
Parameters
- $row : array<string|int, mixed>
- $field : Field|Field_Validation
Return values
array<string|int, mixed>resolveTemplateUrlsInMultiEntryTrait()
マルチ項目フィールドエントリ（'value'/'array' を持つ）に対して URL 解決を適用。
private
resolveTemplateUrlsInMultiEntryTrait(array<string|int, mixed> $entry, string $baseName, Field|Field_Validation $field) : array<string|int, mixed>
Parameters
- $entry : array<string|int, mixed>
- $baseName : string
- $field : Field|Field_Validation