Twigは、PHPで広く利用されているテンプレートエンジンの1つです。
HTMLとPHPのコードを分離し、読みやすく保守しやすいテンプレートを作成できるのが特徴です。SymfonyやDrupalなど多くの有名フレームワークやCMSでも採用されています。

テンプレート内では、変数の出力、条件分岐、ループ処理、フィルターや関数の利用などを簡潔な構文で記述できます。また、変数を自動的にエスケープする仕組みが備わっており、クロスサイトスクリプティング（XSS）などのセキュリティリスクを軽減します。

• 可読性の高い構文 … PHPコードを直接埋め込む必要がなく、デザイナーやフロントエンドエンジニアも理解しやすい。

• セキュリティ … 自動エスケープにより、安全なHTML出力が可能。

• 拡張性 … 独自のフィルターや関数を追加できるため、柔軟なカスタマイズが可能。

• 高速動作 … コンパイルされたPHPコードとしてキャッシュされるため、パフォーマンスに優れる。

Ver. 3.2 で追加されたTwigテンプレートを利用することで、テンプレートの保守性・再利用性が向上し、チーム開発や長期運用の負担を軽減できます。

管理画面 > テーマ から、使用テーマの編集画面に入り「Twigテンプレート」を有効にすることで、Twig記法が利用することができるようになります。

もしくは、テーマ内の「template.yaml」を以下のように設定することでも可能です。

tpl_top : index.twig
tpl_index : index.twig
tpl_detail : _entry.twig
tpl_404 : 404.twig
tpl_admin : admin.html
tpl_entry_edit : _entry.twig
tpl_login : _member-admin/login.html
tpl_twig: enabled # この行を追加しTwigを有効化

拡張子は「twig」がおすすめ

Twigテンプレートには特に拡張子の制限はありません。
そのため、拡張子が .html のテンプレートファイルにTwigの記法を使っても、正しく動作します。

しかし、Twigで記述する場合は .twig 拡張子を使用することをおすすめします。
理由は、エディタがテンプレートをTwigとして認識し、構文ハイライトやコード補完、Twig専用のフォーマット機能など、開発を効率化する機能を利用できるためです。

ファイル例

index.twig
_entry.twig
_top.twig

URLでテンプレートを指定する場合の注意点

通常、動的テンプレートやインクルード用テンプレートでは、ファイル名をURLで直接指定することはありません。
しかし、ページURLとテンプレートファイル名を合わせたい場合には注意が必要です。

例として、検索結果ページを

https://example.com/search.html

で表示したい場合、テンプレートファイルを search.twig にすると、URLが

https://example.com/search.twig

になってしまいます。

これを避けるには、テンプレートファイル名を search.html.twig にします。
URLと一致する .html 部分を含めたファイル名にすることで、URLを変更せずにTwigテンプレートを利用できます。

URLで指定されたファイル名に対して自動的に .twig 拡張子を持つテンプレートも検索する仕組みがあるため、search.html.twig でも正しく読み込まれます。

Twigが有効なテーマでは、Twig記法と従来のテンプレート記法を混在させて記述できます。
ただし、テンプレートの解決順により、特定の組み合わせでは記法が正しく反映されない場合があります。

テンプレートの解決順

Twigが有効な場合、テンプレートは以下の順序で解決されます。

1. Twigによる記述の解決
   （{% include %} や {% extends %} など、Twigの構文を含む部分が先に処理されます）

2. Twigが解決された後に、従来のテンプレート記法が解決される
   （@include や @extends など、従来の構文が後から処理されます）

このため、処理順の都合で、テンプレートが正しく解決されないパターンがあります。

テンプレートが解決されないパターン

• 従来の @include で読み込んだテンプレートにあるTwig記法は解決されない

• 従来の @extends で継承したテンプレート以下にあるTwig記法は解決されない

• 従来の @extends で継承されているテンプレートは、Twig記法でインクルード出来ない

ここでは、Twigの基本的な構文を紹介します。すでにTwigの利用経験がある方は読み飛ばして構いません。

変数の書き方

変数は {{ }} で囲んで出力します。

{{ title }}
{{ entry.id }}

グローバル変数の書き方

Twigでは、グローバル変数と変数の記法に区別はありません。{{ }} で囲むことで出力できます。Twig標準の仕様に従います。

<h1>{{ BLOG_NAME }}</h1>

変数を定義する

Twig内では、テンプレート内で新しく変数を定義することができます。
変数定義には set タグ を使用します。計算結果や文字列の組み立て、繰り返し処理での一時的な値の保持などに便利です。

従来記法の SetTemplate や SetRendered に近い概念ですが、Twigでは定義した値を変数として直接利用できる点が異なります。従来テンプレートには同等の機能はありません（Twig標準の仕様に準拠）。

{% set greeting = "こんにちは" %}
{% set name = "山田" %}

<p>{{ greeting }}, {{ name }}さん！</p>

文字列の連結

Twigでは、~（チルダ） 演算子を使って文字列を結合できます。
これは、PHPの . 演算子やJavaScriptの + 演算子に相当し、文字列と変数を簡単に組み合わせることができます。

{% set title = "今日の天気" %}
{% set weather = "晴れ" %}

<p>{{ title }} は {{ weather }}です。</p>
<p>{{ title ~ "は" ~ weather ~ "です。" }}</p> <!-- 連結して出力 -->

if文の書き方

Twigでは「ifタグ」を使用して記述します。（Twig標準の仕様に従います）

{% if SESSION_USER_AUTH %}
  <p>
    ログイン中です
  </p>
{% endif %}

条件式の記述例

比較演算子

• ==（等しい）

• !=（等しくない）

• >（大きい）

• <（小さい）

• >=（以上）

• <=（以下）

{% set age = 18 %}

{% if age >= 18 %}
  <p>成人です。</p>
{% else %}
  <p>未成年です</p>
{% endif %}

論理演算子

• and（かつ）

• or（または）

• not（否定）

{% set isLogin = true %}
{% set isAdmin = true %}

{% if isLogin and isAdmin %}
    <p>ログイン済みの管理者です。</p>
{% endif %}

{% if not isLogin %}
    <p>ログインしてください。</p>
{% endif %}

is 演算子

• empty: 空かどうか

• defined: 定義されているかどうか

• null: nullであるかどうか

• even/odd: 偶数か奇数か

• divisible by: 指定した数で割り切れるか

{% set name = '山田' %}
{% set list = [] %}
{% set number = 6 %}

{% if name is defined %}
    <p>名前: {{ name }}</p>
{% endif %}

{% if list is empty %}
    <p>リストは空です。</p>
{% endif %}

{% if number is even %}
<p>
  {{ number }}は偶数です。
</p>
{% endif %}

{% if number is divisible by(2) %}
  <p>{{ number }}は2で割り切れます。</p>
{% elseif number is divisible by(3) %}
  <p>{{ number }}は3で割り切れます。</p>
{% else %}
  <p>{{ number }}は2でも3でも割り切れません。</p>
{% endif %}

in 演算子

{% set colors = ["red", "blue", "green"] %}

{% if "blue" in colors %}
    <p>青色が含まれています。</p>
{% endif %}

ループ処理

Twigでのループの書き方はとてもシンプルです。「forタグ」を使って、配列やリストを簡単にループ処理できます。基本的な構文は以下の通りです。（Twig標準の仕様に従います）

{% set fruits = ['Apple', 'Banana', 'Cherry'] %}

<ul>
    {% for fruit in fruits %}
        <li>{{ fruit }}</li>
    {% endfor %}
</ul>

モジュールで取得したデータをループする例

{% set entrySummary = module('V2_Entry_Summary') %}

<ul>
  {% for entry in entrySummary.entries %}
    <li>{{ entry.title }}</li>
  {% endfor %}
</ul>

インデックスの取得

「loop」という特殊な変数を使用して、ループのインデックスやその他の情報を取得できます。loop.index で1から始まるインデックスを取得したり、loop.index0 で0から始まるインデックスを取得できます。

<ul>
  {% for entry in entrySummary.entries %}
    <li>{{ loop.index }}: {{ entry.title }}</li>
  {% endfor %}
</ul>

その他のloopオプション

• loop.first：ループの最初の要素の場合にtrueを返す

• loop.last：ループの最後の要素の場合にtrueを返す

• loop.revindex：残りの要素数（1からカウント）

• loop.revindex0：残りの要素数（0からカウント）

Twigを拡張し、モジュールのデータを取得するa-blog cms独自の関数を追加しています。関数で呼び出したモジュールのデータを変数に格納して使用します。

例：V2_Entry_Summary モジュールを呼び出して使用する

{% set entrySummary = module('V2_Entry_Summary', 'モジュールID名', { bid: BID, cid: CID }) %}
<div>
  <div class="acms-cssgrid acms-g-cols-1 acms-g-cols-md-3">
    {% for entry in entrySummary.items %}
    <div>
      <h3>{{ entry.title }}</h3>
      <p>{{ entry.summary }}</p>
      <p><a href="{{ entry.url }}" class="acms-btn">詳細をみる</a></p>
    </div>
    {% endfor %}
  </div>
</div>

module() 関数の引数について

＊ 「モジュールID」と「URLコンテキスト」は、従来モジュール同様に省略可能です。

{% set hoge = module('V2_Entry_Summary') %}

V2モジュールの変数の見方

V2モジュールでは、従来のような「変数表」は用意されていません。
その代わりに、Twigテンプレートでモジュールを読み込んだ状態で、クイックサーチ機能から利用可能な変数を確認できる仕組みになっています。

クイックサーチの起動方法

管理者としてログイン中に、以下のショートカットキーを押すことでクイックサーチが開きます。

• Windows / Linux：Ctrl + K

• Mac：⌘（Command）+ K

デバッグモードでの変数確認

クイックサーチを開いた状態で、デバッグモードが有効になっているときに #（シャープ）を入力すると、現在のページで読み込まれているV2モジュールの変数一覧（変数表）が表示されます。

Twigを拡張し、タッチモジュールを呼び出すa-blog cms独自の関数を追加しています。関数で呼び出すことで真偽値が返却されるので、if記法と併用して出し分けます。

{% if touch('Touch_Login') %}
  <p>
    ログイン中です
  </p>
{% endif %}

Twigの記法では、変数の中にパイプ（|）で区切りフィルターを指定します {{ 変数|フィルター1|フィルター2 }} （Twig標準の仕様に従います）

{% set content = '今日の天気は\n晴れです' %}

<p>{{ content|nl2br|safe_html }}</p>

使用できる校正オプションの種類

• 従来の標準校正オプション

• Hook.php で拡張した校正オプション

• Twig標準のフィルター

従来の標準校正オプションは利用できますが、Twig標準のフィルターと名前がかぶるものもあります。この場合Twigのフィルターが優先されるので、従来の標準校正オプションを指定したい場合は、プレフィックス acms_ を付与して指定ください。

名前が校正オプション・フィルター例

date escape nl2br trim number_format split など

従来の校正オプションを使用する

{{ entry.datetime|acms_date('Y年m月d日') }}

従来のa-blog cmsの校正オプションに加え、Twig標準のフィルターも全く同じ記法で指定することができます。

{% set sizes = [34, 36, 38, 40, 42] %}

{{ sizes|filter(v => v > 38)|join(', ') }}
{# output 40, 42 #}

引数に変数を指定

従来の校正オプションでは、一部校正オプションのみ引数に変数を利用できましたが、Twig記法だと全てのフィルターに変数が利用できます。

{% set content = '文書を途中で切ります' %}
{% set length = 4 %}
{% set ellipsis = '...' %}

<p>
  {{ content|mb_trim(length, ellipsis) }}
</p>

フィルターを使用したデフォルト値

変数の値がなかった場合に、デフォルト値を出力することができます。

<p>{{ nickname | default("ゲスト") }}</p>

本CMSでは、/themes/テーマ/ がドキュメントルート相当として扱われます。
そのため、静的サイトをそのまま themes 内に置いても動作するよう、テンプレート内のパスを自動で書き換える機能があります。

書き換え対象

パスの書き換えには、次の2種類があります。

1. ファイル指定の書き換え

対象となるのは以下の要素や属性です。

• {{ include('xxx') }} インクルードパス

• img / input / script / frame / iframe 要素の src属性

• srcset属性

• link 要素

• object / applet 要素

• background属性

書き換え仕様（ファイル指定）

1. スキーマ（http:// 等）から始まる場合 → 書き換えない

2. / のみの場合 → 書き換えない

3. / から始まり、ドキュメントルートから探索して見つかった場合 → 書き換えない

4. / から始まり、a-blog cms設置ディレクトリから探索して見つかった場合 → 書き換える

5. / から始まらない場合で、テンプレートからの相対パスとして探索して見つかった場合 → 書き換える

6. 上記に当てはまらず、継承テーマから探索して見つかった場合 → 書き換える

2. アンカー類の書き換え

対象となるのは以下の属性です。

• a 要素の href属性

• form 要素の action属性

書き換え仕様（アンカー類）

1. 空の場合 → 書き換えない

2. スキーマ（http:// 等）から始まる場合 → 書き換えない

3. # から始まる場合 → 書き換えない

4. / から始まらない場合 → 書き換えない

5. a-blog cms設置ディレクトリのパスから始まっている場合 → 書き換えない

6. 上記に当てはまらない場合 → ブログコードからのパスに書き換える

書き換えを行わない設定

このパス書き換えは便利ですが、全ブログで共通するリンクやグローバルナビなどでは、書き換えを行いたくない場合があります。

<a href="/">HOME</a>

このコードが子ブログ内にあると、
http://ドメイン/子ブログコード/ のトップページへのリンクに書き換わってしまいます。

書き換えを防ぐ方法

アンカー類のパス書き換えを行いたくない場合は、要素に acms_no_rewrite 属性を付与します。

<a href="/" class="acms_no_rewrite">HOME</a>

• class以外にも、独自データ属性などで指定可能です。

• 識別子 acms_no_rewrite は、config.system.yaml で変更できます。

acms_no_rewrite: custom_identifier

Twigでのインクルードの書き方について解説します。（Twig標準の仕様に従います）

基本的なインクルード

include関数を使ってテンプレートをインクルードします。

{{ include('/path/to/parts.twig') }}

変数を渡す

インクルードするテンプレートに変数を渡したい場合は、第2引数として変数を渡します。

{{ include('/path/to/parts.twig', { title: 'タイトルです' }) }}

このように書くことで、/path/to/parts.twig 内で title 変数が使えるようになります。

ファイルが存在しない場合のエラー回避

従来のインクルード文だと、インクルードするファイルがない場合でもエラーは発生しませんでしたが、Twigのインクルードはファイルが存在しない場合エラーが出力されます。

インクルードするファイルが存在しない場合にエラーを回避するには、第3引数にtrueを渡してignore_missingオプションを有効にします。

{{ include(/path/to/parts.twig', {}, true) }}
or
{{ include('/path/to/parts.twig', {}, ignore_missing = true) }}

Twigでも従来テンプレートと同じようにテンプレートの継承機能が利用できます。Twig標準の仕様に従います。

継承元テンプレート

継承元テンプレートでは、シンプルなHTMLレイアウトを定義します。

<!DOCTYPE html>
<html>
  <head>
    {% block headMeta %}
      {{ include('/include/head/meta.twig') }}
    {% endblock %}
    {% block headLink %}
      {{ include('/include/head/link.twig') }}
    {% endblock %}
    {% block headJs %}
      {{ include('/include/head/js.twig') }}
    {% endblock %}
  </head>
  <body>
    <header>
      <h1>ヘッダー</h1>
    </header>
    <main>
      {% block main %}
        <p>継承してメインコンテンツを設定してください</p>
      {% endblock %}
    </main>
    <footer>
      {% block footer %}
        <p>Site Footer</p>
      {% endblock %}
    </footer>
  </body>
</html>

この例では block タグを使用して、継承（子）テンプレートが継承する5箇所のブロックを定義しています。

このblockタグが行うことは、子テンプレートがテンプレートのその部分を上書きする可能性があることをテンプレート エンジンに伝えることだけです。

継承（子）テンプレート

継承（子）テンプレートは次のようになります。

{% extends 'parent_template.twig' %}

{% block headLink %}
  {{ parent() }}
  <link rel="stylesheet" href="/include/edit/custom.css" />
{% endblock %}

{% block main %}
  <p>
    メインコンテンツを上書き
  </p>
{% endblock %}

extendsタグは、テンプレートエンジンにこのテンプレートが別のテンプレートを「拡張」していることを伝えます。このテンプレートを評価する際、まず親テンプレートを探します。extendsタグはテンプレートの最初のタグである必要があります。

ここでは headLink ブロックと main ブロックを上書きしてます。子テンプレートは、 headMeta headJs footer ブロックを定義していないため、代わりに親テンプレートの値が使用されることに注意してください。

親ブロック

親ブロックの内容をレンダリングするには、  parent 関数を使用します。これにより、親ブロックの結果が返されます。

{% block headLink %}
  {{ parent() }}
  <link rel="stylesheet" href="/include/edit/custom.css" />
{% endblock %}

名前付きブロック

Twig では、読みやすさを向上させるために、終了タグの後にブロック名を置くことができます。

{% block main %}
  <p>
    メインコンテンツ...
  </p>
{% endblock main %}

a-blog cms での Twig の基本的な使い方について学んできましたが、他にも便利なTwigの機能がありますので、ぜひ目を通してみてください。

Twigのドキュメント

以下一部便利な機能を紹介します。

macro（マクロ）機能

Twigには、テンプレート内で関数のように使える macro（マクロ）機能 があります。
複雑なHTML構造や繰り返し処理をひとつの関数としてまとめられるため、特に階層構造のデータを扱うときに便利です。

階層データの例

たとえば「V2_Category_Tree」モジュールは、カテゴリが入れ子になった階層構造のデータを返します。

{
  categories:
    [
      {
        id: 1,
        name: "お知らせ",
      },
      {
        id: 2,
        name: "製品",
        children:
          [
            {
              id: 3,
              name: "家庭用製品",
            },
            {
              id: 4,
              name: "業務用製品",
              children:
                [
                  {
                    id: 6,
                    name: "業務用製品のお知らせ",
                  },
                ],
            },
          ],
      },
    ]
}

for文のみで書く場合

階層をすべて表示しようとすると、階層分だけfor文をネストする必要があり、コードが深く複雑になります。

{% set tree = module('V2_Category_Tree') %}

<ul>
  {% for category in tree.categories %}
    <li>
      {{ category.name }}
      {% if category.children is not empty %}
        <ul>
          {% for child in category.children %}
            <li>
              {{ child.name }}
              {% if child.children is not empty %}
                <ul>
                  {% for child2 in child.children %}
                    <li>{{ child2.name }}</li>
                  {% endfor %}
                </ul>
              {% endif %}
            </li>
          {% endfor %}
        </ul>
      {% endif %}
    </li>
  {% endfor %}
</ul>

macroを使ってシンプルに書く

macroを使えば、階層構造の処理を再帰的に呼び出せる関数としてまとめられるため、コードがすっきりします。

{% set tree = module('V2_Category_Tree') %}

{% macro renderCategories(categories) %}
  <ul>
    {% for category in categories %}
      <li>
        {{ category.name }}
        {% if category.children is not empty %}
          {{ _self.renderCategories(category.children) }}
        {% endif %}
      </li>
    {% endfor %}
  </ul>
{% endmacro %}

{{ _self.renderCategories(tree.categories) }}

• macroはテンプレート内で定義できる関数のような構文。

• 上記例ではrenderCategoriesというマクロを作成し、カテゴリをリスト表示。

• 子カテゴリ（children）が存在すれば同じマクロを再帰的に呼び出し、階層の深さに制限なく対応可能。

• 呼び出しは_self.マクロ名()で行います。

Twig記法をそのまま出力する

{{ ... }} や {% ... %} など、テンプレートとして解釈されてほしくない場合は verbatim タグを使用することで、そのまま出力することができます。

たとえば、他のテンプレートエンジン（Vue.js や Angular など）と併用し、{{ }} がTwigに解釈されないようにしたい場合などに便利です。

{% verbatim %}
  Twigの構文 {{ variable }} も
  そのまま出力されます。
{% endverbatim %}

Vite（ヴィート）は、モダンなWeb開発のための高速ビルドツールです。本CMSのTwigテンプレートには、Viteでビルドしたファイルを簡単に読み込むための補助機能が組み込まれています。

使い方

a-blog cms で Vite を利用してバンドルしたファイルを読み込むためには、バックエンドとの統合で記載されている仕様に合わせて、script タグや link タグを出力する必要があります。

Twigテンプレート補助機能を使用することで、Vite の仕様に合わせてタグを出力することができるようになり、a-blog cms のテンプレート内で簡単に Vite を利用することができます。

Vite の設定

Vite の設定は vite.config.js に記述します。詳細は Vite のドキュメント を参照してください。

build.manifest を true に設定し、rollupOptions.input でエントリーポイントとなるファイルを指定します。 以下のサンプルは、themes/利用テーマ/src/js/main.js をエントリーポイントとして指定しています。

import { defineConfig } from 'vite';

export default defineConfig({
    // ...
    build: {
        manifest: true,
        rollupOptions: {
            input: {
                bundle: resolve(__dirname, 'src/js/main.js'),
            },
        },
    },
});

この設定をすることで、manifest.json にビルドされたアセットのパスが出力されるようになります。

スクリプトとスタイルの読み込み

Vite の設定が完了したら、a-blog cms のテンプレート内にスクリプトとスタイルを読み込むための記述を追加します。 head タグ内 @vite() を追加します。

<!DOCTYPE html>
<head>
  @vite('src/js/main.js')
</head>

複数のエントリーポイントを指定する場合は、配列で指定します。

<!DOCTYPE html>
<head>
  @vite(['src/js/main.js', 'src/js/main.css'])
</head>

これで、Vite の開発サーバーからビルドされたアセットが読み込まれるようになります。

本番環境での利用

Vite で本番環境用ビルドしたアセットを読み込めるようにするためには、a-blog cms 設置ディレクトリにある .env ファイルを編集します。

以下のように VITE_ENVIRONMENT に production を指定します。

# Vite
VITE_ENVIRONMENT=production # development | production

これで、Vite で本番環境用ビルドしたアセットが読み込まれるようになります。

設定

@vite() の第2引数にJSON形式でオプションを指定することができます。

出力ディレクトリの設定

例えば、Vite の設定で build.outDir を bundle に設定している場合、以下のように記述します。

import { defineConfig } from 'vite';

export default defineConfig({
    // ...
    build: {
        outDir: 'bundle',
    },
});

@vite() の第2引数に出力ディレクトリを指定します。

<!DOCTYPE html>
<head>
  @vite('src/js/main.js', {
    outDir: 'bundle'
  })
</head>

タグの属性をカスタマイズする

タグの属性をカスタマイズすることができます。

以下の例では、エントリーポイントから出力された script タグに async 属性を追加しています。

<!DOCTYPE html>
<head>
  @vite('src/js/main.js', {
    "scriptTagAttributes": {
      "async": true
    }
  })
</head>

また、link タグの属性もカスタマイズすることができます。 以下の例では、エントリーポイントから出力された link タグに type="text/css" 属性を追加しています。

<!DOCTYPE html>
<head>
  @vite('src/styles/main.css', {
    "linkTagAttributes": {
      "type": "text/css"
    }
  })
</head>

React の利用

React と @vitejs/plugin-react を利用する場合、既存の @vite と一緒に、追加で @viteReactRefresh を追加する必要があります。

<!DOCTYPE html>
<head>
  @viteReactRefresh
  @vite('src/js/main.jsx')
</head>

@viteReactRefresh は、React の Hot Module Replacement を有効にするためのスクリプトを出力します。

<script type="module">
  import RefreshRuntime from 'http://localhost:5173/@react-refresh'
  RefreshRuntime.injectIntoGlobalHook(window)
  window.$RefreshReg$ = () => {}
  window.$RefreshSig$ = () => (type) => type
  window.__vite_plugin_react_preamble_installed__ = true
</script>

グローバル変数

本拡張アプリをインストールすることで、以下のグローバル変数が利用できるようになります。

高度なカスタマイズ

環境変数を利用して、Vite の設定をカスタマイズすることができます。

a-blog cms設置ディレクトリにある .env ファイルを編集することで環境変数を設定します。

# Vite
VITE_ENVIRONMENT=production # development | production
VITE_MANIFEST_PATH=dist/.vite/manifest.json
VITE_DEV_SERVER_URL=http://localhost:5173

以下、環境変数の説明です。