Twigのテンプレート分割と再利用を完全解説！初心者向けinclude・embedの使い方

Twigのテンプレート分割と再利用（include, embed）

先生と生徒の会話形式で理解しよう

生徒

「Twigのテンプレートが長くなってきたので、整理したいんですけど、どうすればいいですか？」

先生

「そんな時は、テンプレートの分割と再利用が便利ですよ。Twigにはincludeやembedという便利な機能があります。」

生徒

「それってHTMLの部品を分けるみたいな感じですか？」

先生

「まさにそのとおり！では、Twigでテンプレートを分割して再利用する方法を一緒に見ていきましょう。」

1. Twigでテンプレートを分割する理由とは？管理効率と保守性を高めるメリット

Symfonyなどの開発で使われるTwigは非常に強力ですが、多機能なWebサイトを作ろうとすると、1つのHTMLファイルが数百行、数千行と膨れ上がってしまうことがあります。これをプログラミングの世界では「スパゲッティコード」と呼び、どこに何が書いてあるか分からず、修正ミス（バグ）の原因になってしまいます。

そこで重要なのが「テンプレートの分割（コンポーネント化）」です。料理に例えると、カレーを作る際に「野菜を切る工程」「肉を炒める工程」を別々に準備しておくようなものです。Twigのincludeやembedを使えば、ヘッダー、フッター、ボタンといった部品を独立したファイルとして管理できます。

未経験者でもわかる！分割のメリット

修正が楽：共通のヘッダーを1箇所直せば、全ページに反映される。
読みやすい：1ファイルのコード量が減り、構造がひと目でわかる。
再利用：一度作った「お問い合わせボタン」などを他のページでも使い回せる。

例えば、分割せずに全て1つのファイルに書くと、以下のように管理が大変になります。


<html>
  <body>
    <header><h1>サイト名</h1><nav>...</nav></header> <main>
        <p>ここはトップページの内容です。</p>
    </main>
    <footer><p>&copy; 2026 Sample Site</p></footer> </body>
</html>

このように「同じパーツを何度も書く手間」を省き、Googleの検索エンジンにとっても構造が最適化されやすい（保守性の高い）コードを書くために、テンプレート分割は必須のテクニックなのです。

2. includeの使い方：テンプレートを読み込む基本

includeは、別のテンプレートファイルをその場に読み込んで表示するための構文です。たとえば、ヘッダー部分だけを別ファイルにしておき、必要なところで読み込むことができます。

次のように使います。


{% include 'partials/header.html.twig' %}

このコードは、partials/header.html.twigというテンプレートを現在の位置に挿入するという意味です。

3. 実際にテンプレートを分割してみよう

たとえば、ヘッダー・フッター・ナビゲーションを分割する場合、以下のような構成になります。


<!-- layout.html.twig -->
<html>
  <body>
    {% include 'partials/header.html.twig' %}
    {% include 'partials/nav.html.twig' %}
    
    <main>
      {% block content %}{% endblock %}
    </main>
    
    {% include 'partials/footer.html.twig' %}
  </body>
</html>

これで、共通部分を一か所にまとめて管理できるようになります。

4. embedとは？includeより少し便利な構文

embedはincludeに似ていますが、読み込んだテンプレートの中のblockを上書きしてカスタマイズできる点が特徴です。

つまり、「元の部品の構造は使いつつ、一部だけ変えたい」という場合に便利です。

次のように使います。


{% embed 'components/card.html.twig' %}
    {% block title %}お知らせ{% endblock %}
    {% block content %}新機能をリリースしました。{% endblock %}
{% endembed %}

このように書くと、card.html.twigの中に定義されたblock titleとblock contentの内容を、上書きして使うことができます。

5. embedを使ったカスタマイズ可能なパーツの例

例えば、components/card.html.twigが次のように書かれているとします。


<div class="card mb-3">
    <div class="card-header">
        {% block title %}デフォルトタイトル{% endblock %}
    </div>
    <div class="card-body">
        {% block content %}デフォルト内容{% endblock %}
    </div>
</div>

この構成をベースにしつつ、表示内容だけを差し替えられるので、共通パーツを大量に使う場合でも非常に便利です。

6. includeとembedの使い分け

簡単にまとめると次のように使い分けるのがおすすめです。

include：そのまま表示すればOKな部品（ヘッダー、フッターなど）
embed：内容を一部だけ変更したい部品（カード、通知ボックスなど）

特に大規模なWebアプリでは、共通パーツの再利用が重要になるので、この2つの使い分けはしっかり覚えておきましょう。

7. Twigで再利用可能なデザインを作るメリット

Twigでテンプレートを分割して再利用することで、次のようなメリットがあります。

テンプレートの見通しがよくなる
修正が一箇所で済む（再利用されているため）
開発スピードが上がる
HTMLの重複を減らせる

これはまさに「部品化」された設計で、初心者でも扱いやすく、プロジェクトが大きくなっても崩れにくいのが魅力です。

まとめ

今回の記事では、PHPのモダンな開発現場で欠かせないテンプレートエンジン「Twig」における、テンプレートの分割と再利用について詳しく解説してきました。Webアプリケーションの開発が進むにつれて、フロントエンドのコード量は膨大になりがちです。一つのファイルにすべてのHTMLを記述してしまうと、修正が必要になった際にどこを触ればいいのか分からなくなり、予期せぬバグを引き起こす原因にもなります。そこで重要になるのが、今回学んだ「コンポーネント化」の考え方です。

効率的なテンプレート設計のポイント

Twigが提供する include と embed は、どちらも外部ファイルを読み込むための機能ですが、その性質は大きく異なります。include は「静的な部品」をそのまま差し込むのに適しており、サイト全体のヘッダーやフッター、サイドバーなどの共通パーツに最適です。一方で embed は「動的な枠組み」として機能します。枠組みとしての構造（スケルトン）は維持しつつ、中身のコンテンツを呼び出し側で自由に差し替えられるため、デザインの統一感を保ちながら柔軟なコンテンツ配置が可能になります。

実践的な実装例：動的なカードコンポーネント

それでは、学んだ内容を復習するために、もう少し実践的なPHPとTwigの組み合わせ例を見てみましょう。例えば、ブログの記事一覧を表示する場合、ループ処理の中で embed を活用すると、非常にスッキリとしたコードになります。


// コントローラー側でのデータ準備例
$articles = [
    ['title' => 'Twigの基礎', 'description' => 'テンプレートエンジンの基本を学びます。', 'category' => 'PHP'],
    ['title' => 'Symfony入門', 'description' => 'フレームワークの使い方を解説します。', 'category' => 'Framework'],
];

echo $twig->render('index.html.twig', ['articles' => $articles]);

上記のデータを表示するための index.html.twig は、以下のように embed を使って記述できます。


<div class="container">
    {% for article in articles %}
        {% embed 'components/item-card.html.twig' %}
            {% block card_title %}
                <h3>{{ article.title }}</h3>
            {% endblock %}
            
            {% block card_body %}
                <p>{{ article.description }}</p>
                <span class="badge">{{ article.category }}</span>
            {% endblock %}
        {% endembed %}
    {% endfor %}
</div>

この際、ベースとなる components/item-card.html.twig は、以下のようにブロックを定義しておく必要があります。


<div class="item-card shadow-sm p-3 mb-4 bg-white rounded">
    <div class="item-header border-bottom pb-2">
        {% block card_title %}デフォルトタイトル{% endblock %}
    </div>
    <div class="item-content pt-3">
        {% block card_body %}デフォルトの本文です。{% endblock %}
    </div>
</div>

保守性とSEOの観点から見たメリット

このようにテンプレートを細分化することは、単に「見た目が綺麗になる」だけではありません。検索エンジン最適化（SEO）の観点からも間接的なメリットがあります。コードが整理されることで、構造化データのマークアップが容易になり、クローラーにとっても理解しやすいセマンティックなHTMLを出力しやすくなります。また、修正が一箇所で済むため、サイト全体のデザイン変更やメタタグの更新なども迅速に行えるようになり、常に最新で正確な情報をユーザーに届けることができます。

さらに、表示速度の改善にも寄与します。Twigは内部的にPHPへコンパイルされるため、非常に高速に動作します。分割されたテンプレートはキャッシュ効率も高く、サーバー負荷を抑えつつ高速なページ遷移を実現できます。ユーザー体験（UX）の向上は、近年の検索アルゴリズムにおいて非常に重視されているポイントです。

先生と生徒の振り返り会話

生徒

「先生、include と embed の違いがやっとハッキリわかりました！単にパーツを置くだけなら include、中身をカスタマイズしたいなら embed を使えばいいんですね。」

先生

「その通りです。素晴らしい理解ですね。実際の現場では、これに加えて extends によるレイアウト継承も組み合わせて使うことがほとんどですよ。」

生徒

「なるほど。さっきのカードの例みたいに、ループの中で embed を使うと、HTML構造を崩さずに中身だけ変えられるから、デザインの修正がめちゃくちゃ楽になりそうです。」

先生

「そうなんです。例えば『カードの枠線を全部赤色にしたい』と思ったとき、一つのコンポーネントファイルを直すだけで全ページに反映されますからね。これが『DRY（Don't Repeat Yourself）』、つまり同じことを繰り返さないというプログラミングの鉄則に繋がるんです。」

生徒

「DRYの原則ですね、覚えました！あと、PHP側で配列を作ってTwigに渡す流れも、実際の開発っぽくてイメージが湧きました。」

先生

「良かったです。テンプレート分割をマスターすれば、大規模なプロジェクトでも迷子にならずに開発できるようになります。次は、マクロ（macro）を使った関数のような再利用方法にも挑戦してみましょうか。」

生徒

「はい！もっと便利な機能があるなんてワクワクします。どんどん使いこなせるようになりたいです！」

公的機関での指導実績【Symfony大規模設計実践セミナー】

エンタープライズSymfony実践講座：大規模DX基盤を支える疎結合設計とドメイン駆動開発

#商用設計 #APIアーキテクチャ #市場価値最大化

ハローワーク職業訓練講師の実績を持つプロが監修。商用PHP開発の「現場の作法」を完全伝授。

「大規模システムの秩序」を設計する。SymfonyでエンタープライズLOD（設計の質）を極める。

本講座では、単なるWeb機能の構築ではなく、「再利用性とテスト容易性を追求した疎結合設計」という高度な技術を学びます。世界標準の堅牢性を誇るSymfonyを通じて、大規模開発やマイクロサービス化で必須となるDI（依存性の注入）やイベント駆動設計を最短距離で身につけます。

具体的なワークショップ内容と環境

【つくるもの】
エンタープライズ環境の標準となる「疎結合なバックエンド基盤」を構築します。Service Containerの高度な設定、Doctrine ORMによる複雑なデータマッピング、Bundle構造の理解など、「数年先もメンテナンス可能な商用コード」をゼロから体験してください。

【開発環境】
高度なリファクタリングを可能にするPHPStormの機能をフル活用。Docker環境での開発はもちろん、静的解析ツール（PHPStan）やCI/CDを意識した自動テスト環境まで、大規模プロジェクトの標準フローを再現します。