Symfony入門｜Twigのカスタムフィルターを自作する方法をやさしく解説

Twigのカスタムフィルターを自作する方法

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

生徒

「Symfonyで画面を作っていたら、Twigっていうものが出てきたんですが、何をしているんですか？」

先生

「Twigは、画面に文字やデータを表示するための仕組みです。PHPの値を、見やすい形に変えて表示できます。」

生徒

「文字を大文字にしたり、加工したりもできますか？」

先生

「できます。そのときに使うのがフィルターです。しかも、自分でオリジナルのフィルターも作れます。」

生徒

「自分で作れるんですか？難しそうです……」

先生

「順番に見ていけば大丈夫です。ゆっくり理解していきましょう。」

1. Twigとは何かをやさしく理解しよう

Twigは、Symfonyで使われるテンプレートエンジンです。テンプレートエンジンとは、画面に表示する文章やレイアウトを作るための仕組みのことです。難しく聞こえますが、例えるなら「完成した文章に、あとから名前や数字をはめ込む型紙」のようなものです。 PHPのコードをそのまま画面に書くのではなく、Twigを使うことで、見た目と処理を分けて整理できます。

2. Twigフィルターとは何をするものか

Twigのフィルターは、文字や数字の形を変える道具です。料理で言えば、食材を切ったり味付けしたりする工程に似ています。例えば、文字を大文字にしたり、日付の表示形式を変えたりできます。Twigには最初から用意されているフィルターもありますが、「こういう変換が欲しい」と思ったときに、自分で作れるのがカスタムフィルターです。

3. カスタムフィルターを作る全体の流れ

SymfonyでTwigのカスタムフィルターを自作する流れは、とてもシンプルです。 PHPのクラスを一つ作り、その中で「この名前のフィルターは、この処理をします」と登録します。難しい設定は少なく、Symfonyが自動で読み込んでくれるため、初心者でも安心して進められます。

4. PHPでTwig拡張クラスを作成する

まずは、Twig用の拡張クラスを作ります。これは「Twigに新しい機能を教える箱」のようなものです。通常は src/Twig フォルダを作り、その中にクラスを置きます。


namespace App\Twig;

use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;

class SampleFilterExtension extends AbstractExtension
{
    public function getFilters()
    {
        return [
            new TwigFilter('hello', [$this, 'helloFilter']),
        ];
    }

    public function helloFilter(string $value): string
    {
        return 'こんにちは ' . $value;
    }
}

5. Twigテンプレートでカスタムフィルターを使う

作成したカスタムフィルターは、Twigファイルですぐに使えます。パイプ記号は「この値に、この加工をする」という意味を持っています。


<p>{{ '太郎' | hello }}</p>


こんにちは 太郎

6. 数字を加工する別パターンのフィルター

文字だけでなく、数字を加工するフィルターも作れます。例えば、数字に「円」を付けて表示するフィルターは、金額表示でよく使われます。


public function priceFilter(int $number): string
{
    return $number . '円';
}

7. Twigでの表示例を確認する

上のフィルターをTwigで使うと、数字が自然な日本語表現になります。表示のルールをTwig側にまとめることで、PHPの処理がすっきりします。


<p>{{ 1000 | price }}</p>


1000円

8. カスタムフィルターを使うメリット

Twigのカスタムフィルターを使う最大のメリットは、表示ルールを一か所にまとめられる点です。同じ処理を何度も書かずに済み、画面のコードも読みやすくなります。初心者のうちは「表示の加工はTwigで行う」と覚えておくと、Symfonyの理解が深まります。

まとめ

Symfonyの開発において、Twigのカスタムフィルターを自作する方法を学ぶことは、保守性の高いきれいなコードを書くための第一歩です。これまでの内容を振り返ると、Twigは単なるテンプレートエンジンではなく、PHP側で処理したデータをユーザーにとって最も見やすい形に整える「プレゼンテーション層」の要であることがわかります。標準で用意されている upper や date フィルターだけでも十分に強力ですが、業務システムや特定のWebサービスを開発していると、どうしてもプロジェクト固有の表示ルールが出てくるものです。例えば、特定のステータスコードを日本語の名称に変換したり、ユーザーの権限に応じて表示を切り替えたり、あるいは独自の計算ロジックを通したあとに単位を付与したりといったケースです。

カスタムフィルター作成のポイント再確認

自作フィルターを作る際の肝となるのは、AbstractExtension クラスを継承することと、getFilters メソッド内で TwigFilter インスタンスを配列として返すことです。これにより、Symfonyのサービスコンテナが自動的にあなたの作った拡張機能を検知し、テンプレート内で即座に利用可能にしてくれます。 PHPの関数としてロジックを切り出すことで、同じ変換処理を複数のテンプレートファイルにコピー＆ペーストする必要がなくなります。これは、後から「表示形式を少し変更したい」となったときに、一箇所のPHPファイルを修正するだけで全画面に反映されるという、大きなメリットに繋がります。

実戦で役立つ！応用的なカスタムフィルターの例

ここでは、もう少し実践的な例として、テキストが長すぎる場合に省略して三点リーダー（...）を付与する「要約フィルター」のコードを見てみましょう。こうした処理をTwig側で共通化しておくと、ブログの一覧画面やニュース更新情報などのレイアウトが崩れるのを防ぐことができます。

PHP側：省略フィルターの定義


namespace App\Twig;

use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;

class TextExtension extends AbstractExtension
{
    public function getFilters()
    {
        return [
            // 第一引数がTwigで使う名前、第二引数が呼び出す関数
            new TwigFilter('truncate_ja', [$this, 'truncateJapanese']),
        ];
    }

    /**
     * 日本語文字列を指定した長さでカットするフィルター
     */
    public function truncateJapanese(string $value, int $length = 20): string
    {
        if (mb_strlen($value) > $length) {
            return mb_substr($value, 0, $length) . '...';
        }
        return $value;
    }
}

Twig側：フィルターの呼び出し


<div class="content-summary">
    {# 30文字でカットする設定で呼び出し #}
    <p>{{ long_text | truncate_ja(30) }}</p>
</div>

出力結果（実行例）


Symfonyは非常に強力なフレームワークで、Twigを使うことで画面制作が...

このように、引数を渡せるように設計することで、フィルターの汎用性はさらに高まります。 Symfonyは「設定より規約」を重視するフレームワークですが、Twigの拡張に関しては非常に自由度が高く、開発者の意図を反映しやすい設計になっています。初心者のうちは、PHP側で str_replace や number_format を駆使して変数を作ってからTwigに渡してしまいがちですが、「これは表示のための加工かな？」と思ったら、ぜひカスタムフィルター化を検討してみてください。それが、Symfonyらしい、そしてプロフェッショナルなコードへの近道です。

最後に、Twigテンプレートをより効率的に活用するために、Bootstrap5のクラスと組み合わせることも忘れないでください。カスタムフィルターで加工した清潔なデータに、Bootstrapのスタイルを適用することで、ユーザーにとって使いやすく、開発者にとってメンテナンスしやすい完璧なWebアプリケーションが完成します。今回の学習を活かして、あなただけの便利なフィルターライブラリを構築していきましょう。

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

生徒

「先生、ありがとうございました！カスタムフィルターって、要するに『自分専用の変換ボタン』をTwigに追加するようなイメージですね。」

先生

「その通りです！良い例えですね。PHP側で重たい処理を済ませて、Twig側ではその結果をどう見せるかに集中する。この役割分担が、Symfonyを使いこなすコツなんです。」

生徒

「さっきの truncate_ja みたいなフィルターがあれば、ニュースの見出しとか、至る所で使い回せそうです。でも、これってどこに保存しても動くんですか？」

先生

「基本的には src/Twig/ というディレクトリを作って配置するのが一般的です。Symfonyのオートワイヤリングという機能のおかげで、配置して AbstractExtension を継承するだけで、特別な設定ファイルを書かなくても自動で認識してくれるんですよ。」

生徒

「それは便利ですね！設定で苦戦することが多いので助かります。あ、そういえば、フィルターの中で他のサービス、例えばデータベースから何かを読み込んで変換に使うこともできるんですか？」

先生

「鋭い質問ですね。可能です。クラスのコンストラクタで必要なサービスを注入（インジェクション）すれば、フィルターの中で複雑なロジックを組むこともできます。ただ、あまりに複雑にしすぎるとテンプレートの表示が遅くなるので、そこはバランスが大事ですよ。」

生徒

「なるほど、あくまで『表示のための加工』という役割を忘れないようにします。自分で作ったフィルターが画面で動くと、プログラミングがもっと楽しくなりそうです！」

先生

「その意気です。まずは簡単な文字の置き換えから始めて、少しずつ便利な道具を増やしていってください。SymfonyとTwigの世界がどんどん広がっていきますよ。」

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

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

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

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

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

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

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

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

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