a-blog cms PHP API Reference

Twig
in package

Application

Properties

$loader : CustomLoader|null
$path : string
$theme : string
$twig : Environment|null
$extendsHookDispatched : bool: extendsTwig Hook が発火済みかどうか。
$needsRebuild : bool: pending リストに変更があり次回 render 時に Environment を再構築すべきか。
$options : TwigOptions|null: Environment 構築の挙動を決める設定。null は公開側既定 (現行と同一)。
$pendingExtensions : array<class-string, AbstractExtension>: 拡張側から登録された Extension (Environment 構築時に flush)。同型クラスの二重登録は最後の登録を採用する。
$pendingFilters : array<string, array{name: string, callable: callable, options: array}>: 拡張側から登録された Filter (Environment 構築時に flush)。 Filter 名をキーにして同名の二重登録を最後の登録で束ねる。 extendsTwig Hook は Environment 再構築のたびに再発火し得るため、同名 Filter が複数積まれて addFilter が LogicException を投げるのを防ぐ。
$pendingFunctions : array<string, array{name: string, callable: callable, options: array}>: 拡張側から登録された Function (Environment 構築時に flush)。 Function 名をキーにして同名の二重登録を最後の登録で束ねる ($pendingFilters と同様)。
$pendingTemplatePaths : array<string, array<int, string>>: 拡張側から登録されたテンプレートディレクトリ (Environment 構築時に flush)。
$stringLoader : ArrayLoader|null: renderString 用に文字列テンプレートを載せる ArrayLoader。 useStringLoader 有効時のみ生成される。

Methods

__construct() : mixed
addExtension() : void: 拡張を追加 (既存 API)。
addFunction() : void: Functionを追加 (既存 API)。
addTemplatePath() : void: 拡張側がテンプレートディレクトリを名前空間付きで登録するための窓口。 Environment 構築前なら pending に積み、構築済みなら即時反映する。
applyBuiltInExtensions() : void: 組込みの Twig 拡張フルセット ({@see TwigOptions::DEFAULT_EXTENSIONS}) を Environment に attach する。
clearCache() : void: Twigのキャッシュをクリア
createAcmsExtension() : AcmsExtension: `setDefaultFilters` 済みの {@see AcmsExtension} を生成して返す。
defaultFilterNames() : array<int, string>: Twig 標準 Filter 名の一覧を返す。
load() : void: twigテンプレートをロード
registerExtension() : void: 拡張側が register する用の Extension 登録窓口。
registerFilter() : void: 拡張側が register する用の Filter 登録窓口。
registerFunction() : void: 拡張側が register する用の Function 登録窓口。
render() : string: レンダリング (既存 API)。
renderString() : string: 文字列テンプレートをレンダリングする。
renderTemplate() : string: テンプレ名と変数を渡してレンダリングする。
attachBuiltInExtensions() : void: 組込みの Twig 拡張を Environment に attach する。
bootstrapEnvironment() : void: Environment を構築する。
dispatchExtendsTwigHook() : void: extendsTwig Hook を発火する。
buildSandboxPolicy() : SecurityPolicy: サンドボックスの許可リストを組み立てる。
createLoader() : LoaderInterface: options に応じて Environment 用のローダを構築する。
flushPending() : void: pending に積まれた登録物を Environment / Loader に一括 attach する。
makeBuiltInExtension() : AbstractExtension|null: 組込み拡張キー ({@see TwigOptions::EXTENSION_ACMS} 等) を拡張インスタンスへ解決する。
resolveOptions() : TwigOptions: 解決済みの設定を返す。null のときは公開側既定を組み立てる。
resolveThemeDirectories() : array<int, string>: テーマ名からテンプレートディレクトリリストを解決する。

$loader


        protected
            CustomLoader|null
    $loader

$path


        protected
            string
    $path
     = ''

$theme


        protected
            string
    $theme
     = ''

$twig


        protected
            Environment|null
    $twig

$extendsHookDispatched

extendsTwig Hook が発火済みかどうか。


        private
            bool
    $extendsHookDispatched
     = false

bootstrapEnvironment で 1 回だけ発火させる。Environment を再構築 (needsRebuild) しても二重発火しないようフラグで管理する。

$needsRebuild

pending リストに変更があり次回 render 時に Environment を再構築すべきか。


        private
            bool
    $needsRebuild
     = false

Twig\Environment は最初の render で ExtensionSet が initialized になり、それ以降は addFilter / addFunction / addExtension が例外で弾かれる。このフラグが立っているときは render の冒頭で bootstrap をやり直す。

$options

Environment 構築の挙動を決める設定。null は公開側既定 (現行と同一)。


        private
            TwigOptions|null
    $options

サービスコンテナにキー違いで同じ Twig クラスを登録する際、クロージャ登録で注入する。

$pendingExtensions

拡張側から登録された Extension (Environment 構築時に flush)。同型クラスの二重登録は最後の登録を採用する。


        private
            array<class-string, AbstractExtension>
    $pendingExtensions
     = []

$pendingFilters

拡張側から登録された Filter (Environment 構築時に flush)。 Filter 名をキーにして同名の二重登録を最後の登録で束ねる。 extendsTwig Hook は Environment 再構築のたびに再発火し得るため、同名 Filter が複数積まれて addFilter が LogicException を投げるのを防ぐ。


        private
            array<string, array{name: string, callable: callable, options: array}>
    $pendingFilters
     = []

$pendingFunctions

拡張側から登録された Function (Environment 構築時に flush)。 Function 名をキーにして同名の二重登録を最後の登録で束ねる ($pendingFilters と同様)。


        private
            array<string, array{name: string, callable: callable, options: array}>
    $pendingFunctions
     = []

$pendingTemplatePaths

拡張側から登録されたテンプレートディレクトリ (Environment 構築時に flush)。


        private
            array<string, array<int, string>>
    $pendingTemplatePaths
     = []

namespace => list

$stringLoader

renderString 用に文字列テンプレートを載せる ArrayLoader。 useStringLoader 有効時のみ生成される。


        private
            ArrayLoader|null
    $stringLoader
     = null

__construct()


    public
                    __construct([TwigOptions|null $options = null ]) : mixed

Parameters

$options : TwigOptions|null = null: Environment 構築の設定。null で公開側既定 (現行と同一)

addExtension()

拡張を追加 (既存 API)。


    public
                    addExtension(AbstractExtension $extension) : void

互換のため Environment 構築前 (load 未実行) の呼び出しも受け付け、 pending に積んで構築時に attach する。

Parameters

$extension : AbstractExtension

addFunction()

Functionを追加 (既存 API)。


    public
                    addFunction(string $name, callable $function) : void

互換のため Environment 構築前の呼び出しも受け付け、pending に積む。

Parameters

$name : string
$function : callable

addTemplatePath()

拡張側がテンプレートディレクトリを名前空間付きで登録するための窓口。 Environment 構築前なら pending に積み、構築済みなら即時反映する。


    public
                    addTemplatePath(string $dir[, string|null $namespace = null ]) : void

Parameters

$dir : string
$namespace : string|null = null: null の場合は MAIN_NAMESPACE

applyBuiltInExtensions()

組込みの Twig 拡張フルセット ({@see TwigOptions::DEFAULT_EXTENSIONS}) を Environment に attach する。


    public
            static        applyBuiltInExtensions(Environment $twig[, array<int, string>|null $defaultFilters = null ]) : void

拡張構成を 1 箇所に集約するためのユーティリティ。dump を提供する DebugExtension を含むため、運営者入力テンプレを評価するサンドボックス経路では使わず、TwigOptions::$extensions を [EXTENSION_ACMS] のように絞る。インスタンス側の attach は attachBuiltInExtensions を参照。

Parameters

$twig : Environment
$defaultFilters : array<int, string>|null = null: null のとき defaultFilterNames を使う

clearCache()

Twigのキャッシュをクリア


    public
                    clearCache() : void

createAcmsExtension()

`setDefaultFilters` 済みの {@see AcmsExtension} を生成して返す。


    public
            static        createAcmsExtension([array<int, string>|null $defaultFilters = null ]) : AcmsExtension

サンドボックス経路 (template.mail.twig.sandboxed / extensions=[EXTENSION_ACMS]) は DebugExtension 等の危険な拡張を避けつつ AcmsExtension のフィルタ・関数だけを許可リストに合成したいため、フル attach を行う applyBuiltInExtensions ではなくこちらを使う。

Parameters

$defaultFilters : array<int, string>|null = null: null のとき defaultFilterNames を使う

Return values

AcmsExtension

defaultFilterNames()

Twig 標準 Filter 名の一覧を返す。


    public
            static        defaultFilterNames() : array<int, string>

AcmsExtension::setDefaultFilters に渡し、Twig 標準と衝突する Corrector 由来フィルタ (nl2br など) を acms_ プレフィックス版のみに絞り込むために使う。公開側 Environment・メール用 Trusted/Sandboxed の各レンダラで同じ値を共有する。

Return values

array<int, string>

load()

twigテンプレートをロード


    public
                    load(string $path, string $theme) : void

Parameters

$path : string
$theme : string

registerExtension()

拡張側が register する用の Extension 登録窓口。


    public
                    registerExtension(AbstractExtension $extension) : void

同型クラスの二重登録は最後の登録を採用する (Twig\Environment::addExtension は同型クラスを二度 attach すると例外を投げるため)。

Parameters

$extension : AbstractExtension

registerFilter()

拡張側が register する用の Filter 登録窓口。


    public
                    registerFilter(string $name, callable $callable[, array<string, mixed> $options = [] ]) : void

Environment 未構築なら pending に積み、構築済みなら即時 addFilter する。

Parameters

$name : string
$callable : callable
$options : array<string, mixed> = []: Twig\TwigFilter のコンストラクタ第 3 引数と同じ

registerFunction()

拡張側が register する用の Function 登録窓口。


    public
                    registerFunction(string $name, callable $callable[, array<string, mixed> $options = [] ]) : void

Parameters

$name : string
$callable : callable
$options : array<string, mixed> = []: Twig\TwigFunction のコンストラクタ第 3 引数と同じ

render()

レンダリング (既存 API)。


    public
                    render() : string

Return values

string

renderString()

文字列テンプレートをレンダリングする。


    public
                    renderString(string $template[, array<string, mixed> $context = [] ][, string $name = 'string_template' ]) : string

useStringLoader を有効にした構成で使う。文字列を ArrayLoader に載せて render する。 useThemeLoader も有効なら、テンプレ内の include/extends 先はテーマ階層から解決される。

Parameters

$template : string: レンダリングするテンプレート文字列
$context : array<string, mixed> = []
$name : string = 'string_template': autoescape 戦略がテンプレ名を参照する場合に使う論理名 (拡張子を含めると良い)

Return values

string

renderTemplate()

テンプレ名と変数を渡してレンダリングする。


    public
                    renderTemplate(string $name[, array<string, mixed> $context = [] ]) : string

Environment 未構築なら最低限の構築を行う。テーマは config('theme') を採用し、解決できなければ system のみを fallback とする。

Parameters

$name : string
$context : array<string, mixed> = []

Return values

string

attachBuiltInExtensions()

組込みの Twig 拡張を Environment に attach する。


    protected
                    attachBuiltInExtensions(Environment $twig, array<int, string> $defaultFilters) : void

attach する拡張は TwigOptions::$extensions で指定されたキー集合に従う (公開側・メールのファイル経路は既定のフルセット、サンドボックス経路は [EXTENSION_ACMS] のみ等)。拡張ポイントとして protected で切り出しており、テストサブクラスから空実装で上書きすることで、 ACMS の完全初期化を必要としない単体テストが書ける。

Parameters

$twig : Environment
$defaultFilters : array<int, string>: Twig 標準 Filter 名一覧 (AcmsExtension が利用)

bootstrapEnvironment()

Environment を構築する。


    protected
                    bootstrapEnvironment(string $theme) : void

テーマ → system の順でテンプレートディレクトリを積み、組込み拡張・Hook 拡張・ pending のテンプレートパス / Filter / Function / Extension を flush する。

Parameters

$theme : string

dispatchExtendsTwigHook()

extendsTwig Hook を発火する。


    protected
                    dispatchExtendsTwigHook() : void

通常運用では HOOK_ENABLE が無効化されているとき (config.user.php で 0 など) に Hook を呼ばないようガードする。テストサブクラスから上書きすることで、Hook 発火を強制できる単体テスト経路も確保する。

buildSandboxPolicy()

サンドボックスの許可リストを組み立てる。


    private
                    buildSandboxPolicy(TwigOptions $options) : SecurityPolicy

基本許可 (options 由来) に、AcmsExtension のフィルタ/関数名を合成する。これにより運営者入力でも acms_* フィルタ・module() などの組込み関数が許可リスト内で使える。タグはオプション指定のみ (include/extends を許可リストに入れなければ運営者は他ファイルを取り込めない)。

拡張アプリ・ユーザー拡張の extendsTwig Hook 由来 (pending) のフィルタ/関数は、サンドボックス経路ではそもそも発火させない (bootstrapEnvironment) ため、ここでも合成しない。第三者拡張の独自フィルタ・関数を運営者の直接入力で実行させないための境界。

strict モードを必ず有効化する。Twig\Sandbox\SecurityPolicy は後方互換のため、strict=false だと extends / use タグと parent / block / attribute 関数を許可リストの有無に関わらず常に通してしまう (Twig 3.12 で非推奨化、4.0 で廃止予定の挙動)。strict 化しない限り、許可タグから extends を外しても運営者入力の {% extends "自身の論理名" %} (自己参照) が実行され、無限再帰でメモリ枯渇 (Fatal Error) に至る。

Parameters

$options : TwigOptions

Return values

SecurityPolicy

createLoader()

options に応じて Environment 用のローダを構築する。


    private
                    createLoader(string $theme, TwigOptions $options) : LoaderInterface

テーマローダ (CustomLoader): include/extends・パス指定 render に必要
文字列ローダ (ArrayLoader): renderString で文字列テンプレを載せる両方有効なら ChainLoader[文字列, テーマ] とし、文字列テンプレを主に include 先をテーマから解決する。

テーマローダの参照は $this->loader に保持し flushPending / addTemplatePath から、文字列ローダは $this->stringLoader に保持し renderString から使う。

Parameters

$theme : string
$options : TwigOptions

Return values

LoaderInterface

flushPending()

pending に積まれた登録物を Environment / Loader に一括 attach する。


    private
                    flushPending() : void

makeBuiltInExtension()

組込み拡張キー ({@see TwigOptions::EXTENSION_ACMS} 等) を拡張インスタンスへ解決する。


    private
            static        makeBuiltInExtension(string $key, array<int, string> $defaultFilters) : AbstractExtension|null

未知のキーは null を返して無視する (呼び出し側で skip)。AcmsExtension のみ defaultFilters を要するため createAcmsExtension 経由で生成する。

Parameters

$key : string: 拡張キー
$defaultFilters : array<int, string>: Twig 標準 Filter 名一覧 (AcmsExtension が利用)

Return values

AbstractExtension|null

resolveOptions()

解決済みの設定を返す。null のときは公開側既定を組み立てる。


    private
                    resolveOptions() : TwigOptions

既定はキャッシュディレクトリのみ実行時定数 (CACHE_DIR) を使うため、コンストラクタ既定値では表現できない。そのため null のときだけここで補う (他の既定値は TwigOptions の既定と一致)。

Return values

TwigOptions

resolveThemeDirectories()

テーマ名からテンプレートディレクトリリストを解決する。


    private
                    resolveThemeDirectories(string $theme) : array<int, string>

親テーマ表記 ({子}@{親}) を再帰的に展開し、最後に system を必ず加える。 Twig\Loader\FilesystemLoader は存在しないパスの追加で例外を投げるため、実在するディレクトリのみに絞り込む。

Parameters

$theme : string

Return values

array<int, string>

Twig in package Application

Table of Contents

Properties

Methods

Properties

$loader

$path

$theme

$twig

$extendsHookDispatched

$needsRebuild

$options

$pendingExtensions

$pendingFilters

$pendingFunctions

$pendingTemplatePaths

$stringLoader

Methods

__construct()

Parameters

addExtension()

Parameters

Tags

addFunction()

Parameters

Tags

addTemplatePath()

Parameters

applyBuiltInExtensions()

Parameters

clearCache()

createAcmsExtension()

Parameters

Return values

defaultFilterNames()

Return values

load()

Parameters

Tags

registerExtension()

Parameters

registerFilter()

Parameters

registerFunction()

Parameters

render()

Return values

renderString()

Parameters

Tags

Return values

renderTemplate()

Parameters

Return values

attachBuiltInExtensions()

Parameters

bootstrapEnvironment()

Parameters

dispatchExtendsTwigHook()

buildSandboxPolicy()

Parameters

Return values

createLoader()

Parameters

Return values

flushPending()

makeBuiltInExtension()

Parameters

Return values

resolveOptions()

Return values

resolveThemeDirectories()

Parameters

Return values

Twig
in package

Application