TwigのHTMLエスケープとrawフィルタの使い方を完全解説！初心者にもわかるテンプレート表示のコツ

1. Twigの「自動エスケープ」とは？仕組みをわかりやすく解説

1. Twigの「自動エスケープ」とは？仕組みをわかりやすく解説

SymfonyなどのPHPフレームワークで使われるテンプレートエンジン「Twig」には、「自動エスケープ（Auto-escaping）」という非常に重要な機能が備わっています。

プログラミング未経験の方には少し難しく聞こえるかもしれませんが、エスケープとは、「HTMLタグとして特別な意味を持つ文字を、ただの文字として表示されるように変換すること」を指します。これにより、意図しないレイアウト崩れや、悪意のあるプログラムの実行を防いでいます。

具体的な変換の例

例えば、変数の中に <b>こんにちは</b> というHTML（太字にする命令）が入っていた場合、Twigは裏側で以下のように変換して出力しています。

• <（小なり） → <
• >（大なり） → >

もしエスケープがなければ、ブラウザはこれを「太字にする命令」と受け取りますが、Twigが変換してくれるおかげで、画面上には以下のようにタグそのものが文字として表示されます。

<b>こんにちは</b>

なぜ自動でエスケープされるのか？

これは、「クロスサイトスクリプティング（XSS）」というサイバー攻撃からウェブサイトを守るためです。ユーザーがフォームから入力したデータに、もし勝手に画面を書き換えるような危険なコード（JavaScriptなど）が含まれていても、Twigが自動で無害な文字列に変えてくれるので、安全性が保たれるのです。

初心者のうちは、「HTMLを書いても勝手に文字になっちゃう！」と困ることもあるかもしれませんが、これはTwigがあなたのサイトを全力で守ってくれている証拠なのです。

2. HTMLとして表示したいときは「|raw」フィルタ

2. HTMLとして表示したいときは「|raw」フィルタ

Twigにはセキュリティを守るために「HTMLタグを自動で無効化する（エスケープ）」という非常に賢い機能が備わっています。しかし、ブログの記事本文や、装飾を含めたお知らせを表示したいときなど、「HTMLタグをそのままブラウザに認識させたい」場面もありますよね。

そんなときに活躍するのが、Twigの|rawフィルタです。このフィルタを通すことで、安全ロックを解除し、中身を「生のデータ（raw）」として出力することができます。

使い方はとてもシンプルです。出力したい変数の後ろに、パイプ記号（|）とrawを書き加えるだけです。

{{ message|raw }}

具体的な仕組みを、プログラムに慣れていない方でも分かりやすいサンプルで見ていきましょう。

例えば、PHP（コントローラ）側で「文字を赤く太くする」という命令を含んだデータを用意したとします。

// コントローラ（PHP）からデータを送る
$message = '<strong style="color: red;">重要なお知らせ！</strong>';

return $this->render('sample.html.twig', [
    'message' => $message
]);

もし、このデータを|rawを使わずに普通に表示しようとすると、Google Chromeなどのブラウザは「これは単なる文字だな」と判断して、記号をそのまま画面に出してしまいます。

<strong style="color: red;">重要なお知らせ！</strong>

これでは、せっかくの装飾が台無しですね。そこで、Twig側で|rawを適用してみます。すると、ブラウザは「あ、これはHTMLタグだ！赤色で表示しよう」と正しく解釈してくれるようになります。

重要なお知らせ！（※ここが赤色の太字で表示されます）

このように、Webサイトでリッチな表現（文字の色付け、リンク、改行など）を自由に行いたいときには欠かせない機能です。ただし、何でもかんでも解除してしまうとセキュリティのリスクも出てくるため、「信頼できる中身」だと分かっているときだけ使うのが、プロの使いこなし術です。

3. |rawを使うときの注意点とセキュリティ対策

3. |rawを使うときの注意点とセキュリティ対策

|rawフィルターは非常に強力で便利ですが、使い方を誤るとWebサイトの安全性を脅かす重大なリスクになります。使用する際は、「そのデータはどこから来たものか？」を常に意識することが重要です。

最大の禁忌：ユーザー入力値への使用

最も注意すべき点は、お問い合わせフォームやコメント欄など、ユーザーが自由に入力できるデータには絶対に|rawを使わないということです。

もし悪意のある第三者が、入力欄に以下のような「スクリプト（命令）」を紛れ込ませた場合を考えてみましょう。

<script>alert('あなたのパスワードを盗みました');</script>

これを|rawでそのまま出力してしまうと、ブラウザがこれを「表示すべき文字」ではなく「実行すべき命令」と判断してしまいます。これがクロスサイトスクリプティング（XSS）と呼ばれる脆弱性です。自分だけでなく、サイトを訪れた他のユーザーにも被害が及ぶ可能性があります。

安全な使い方の具体例

プログラミング未経験の方でも分かりやすい、安全なケースと危険なケースの比較です。

// 【安全】自分で作成した固定のHTMLタグ
$my_bio = "<strong>エンジニア</strong>として活動中";

// 【危険】ユーザーが入力したニックネーム
$user_name = $_POST['user_name']; // <script>等が仕込まれている可能性アリ

この場合、$my_bioには|rawを使っても問題ありませんが、$user_nameには絶対に使わず、自動エスケープ（そのまま表示）に任せるのが鉄則です。

4. TwigでHTMLをそのまま表示する「|raw」の具体的な使い方

4. TwigでHTMLをそのまま表示する「|raw」の具体的な使い方

プログラミング初心者の方でも分かりやすいように、「コントローラーで用意したHTMLタグ付きのメッセージを、画面上で装飾して表示させる」という具体的な流れを解説します。

例えば、ユーザーがフォームを送信した後に「保存が完了しました！」というメッセージを、BootstrapなどのCSSクラス（text-success）を使って緑色で強調したい場合があります。

ステップ1：コントローラー側の記述

PHP側（Controller）では、変数にHTMLタグを含めた文字列を代入してテンプレートへ渡します。

// PHP側でHTMLタグを含んだ文字列を用意する
$notice = '<p class="text-success"><strong>チェック！</strong> 保存が正常に完了しました！</p>';

return $this->render('page.html.twig', [
    'notice' => $notice
]);

ステップ2：Twigテンプレートでの記述

通常、TwigはセキュリティのためにHTMLタグを無効化（エスケープ）しますが、ここで|rawフィルターを適用することで、プログラムに「このHTMLは安全だからそのまま実行して」と伝えます。

{# そのまま表示させたい変数に「|raw」をつなげるだけ！ #}
{{ notice|raw }}

実際の実行結果

ブラウザで確認すると、<p>タグや<strong>タグが正しく解釈され、文字が太字になったり色がついて表示されます。

<strong>チェック！</strong> 保存が正常に完了しました！（※実際には緑色の文字で表示されます）

5. TwigとHTMLの関係を理解しよう

5. TwigとHTMLの関係を理解しよう

HTMLはウェブページを構成するための言語で、TwigテンプレートはそのHTMLをより動的に作るための仕組みです。Twigでは変数を簡単に表示できますが、セキュリティを守るために、表示される内容はHTMLとして解釈されず、文字列として安全に出力されます。

HTMLを意図的に表示したいときだけ、|rawを使い、その他はTwigの自動エスケープに任せるのがベストプラクティスです。

まとめ

まとめ

ここまで、Symfonyなどのフレームワークで標準採用されているテンプレートエンジン「Twig」における、HTMLエスケープの仕組みとrawフィルタの活用方法について詳しく解説してきました。Web開発において、動的にコンテンツを表示させることは欠かせませんが、そこには常にセキュリティのリスクが隣り合わせであることを忘れてはいけません。

Twigの自動エスケープが私たちを守っている

Twigがデフォルトで有効にしている「自動エスケープ」は、クロスサイトスクリプティング（XSS）などの攻撃からアプリケーションを守るための非常に強力な防壁です。特別な指定をしない限り、すべての変数は安全な形式に変換されて出力されます。例えば、ユーザーがコメント欄にスクリプトを仕込もうとしても、Twigはそれをただの文字列として無害化してくれるのです。

rawフィルタが必要になる具体的なシーン

一方で、CMS（コンテンツ管理システム）からHTMLタグ付きのリッチテキストを出力したい場合や、管理画面で作成した整形済みのHTMLをそのまま反映させたい場合には、この自動エスケープが邪魔になってしまいます。そこで登場するのが |raw フィルタです。このフィルタを適用することで、Twigに対して「この変数は安全だと私が保証するので、そのままHTMLとしてレンダリングしてほしい」と命令することができます。

実装例のおさらい

改めて、PHP側（Controller）とTwig側での記述方法を確認しておきましょう。以下のサンプルコードでは、信頼できるソースから生成されたHTMLメッセージを表示する際の実装を示しています。

// PHP側の実装（Controller）
// 信頼できる内部処理から生成されたHTML文字列
$htmlContent = '<div class="alert alert-info"><strong>お知らせ：</strong>システムメンテナンスを本日22時より実施いたします。</div>';

return $this->render('info/notice.html.twig', [
    'maintenance_info' => $htmlContent
]);

この maintenance_info 変数をそのままTwigで表示しようとすると、タグが文字として画面に出てしまいます。そのため、以下のように記述します。

{# Twigテンプレート側の記述 #}
<div class="container">
    <h1>インフォメーション</h1>
    {# rawフィルタを適用してHTMLとして出力 #}
    {{ maintenance_info|raw }}
</div>

このコードの実行結果は、以下のようになります。

インフォメーション
お知らせ：システムメンテナンスを本日22時より実施いたします。（青色の枠線付きで表示）

開発者が守るべきセキュリティの鉄則

プログラミングにおいて「便利さ」と「安全性」はトレードオフの関係になりがちですが、|raw フィルタの使用には慎重さが求められます。以下のポイントを常に意識してください。

• ユーザー投稿データには絶対に使わない： 不特定多数が入力できるフォームからのデータに |raw を使うのは非常に危険です。
• 信頼できるソースのみに適用： データベースに保存された自社スタッフ作成のデータや、プログラム内部で組み立てたHTMLに限って使用しましょう。
• エスケープの意図を理解する： なぜエスケープが必要なのか、その背景にあるセキュリティ知識を深めることが、一流のエンジニアへの近道です。

テンプレートエンジンの特性を正しく理解することで、安全でかつ表現力の豊かなWebサイトを構築することが可能になります。今回の内容を参考に、適切なエスケープ処理を心がけてみてください。