Twigのカスタム関数・フィルターの作り方を徹底解説！初心者向けSymfonyテンプレート講座

1. Twigのカスタム関数・フィルターとは？

1. Twigのカスタム関数・フィルターとは？

Twigには、表示を便利にするための「関数（Functions）」と「フィルター（Filters）」という2つの強力な武器があります。これらを使いこなすと、PHP側で複雑なロジックを組まなくても、テンプレート側で直感的にデータを整形できるようになります。

{{ get_current_time() }}

{{ name|upper }}

プログラミングが初めての方でも安心してください。例えば「商品価格に自動で『円』を付ける」「長すぎるタイトルを『...』で省略する」といった、かゆいところに手が届く機能を自分で作れるのがカスタム拡張の魅力です。標準機能に縛られず、あなたのWebサイト専用の便利なショートカットを定義していきましょう。

2. カスタムTwig拡張クラスの作成

2. カスタムTwig拡張クラスの作成

Symfonyで独自の関数やフィルターを追加するには、「Twig拡張（Extension）クラス」を作成します。これは、PHP側で書いたプログラムを、HTMLテンプレート（Twig）の中で簡単に呼び出せるようにするための橋渡し役になります。

プログラミングが初めての方でも大丈夫です。まずは、src/Twigというフォルダの中に、AppExtension.phpという名前でファイルを作成し、以下のコードを書いてみましょう。

namespace App\Twig;

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

/**
 * Symfonyのテンプレートエンジン「Twig」を拡張するためのクラス
 */
class AppExtension extends AbstractExtension
{
    /**
     * getFunctionsメソッド：Twig内で使える「独自の関数」を登録します
     */
    public function getFunctions(): array
    {
        return [
            // 第一引数：Twig側で使う名前、第二引数：実行するPHPのメソッド名
            new TwigFunction('greeting', [$this, 'greetingFunction']),
        ];
    }

    /**
     * getFiltersメソッド：Twig内で使える「独自のフィルター」を登録します
     */
    public function getFilters(): array
    {
        return [
            // パイプ記号「|」の後に使うフィルター名を定義
            new TwigFilter('reverse_text', [$this, 'reverseFilter']),
        ];
    }

    /**
     * あいさつを表示する関数の実体
     */
    public function greetingFunction(string $name): string
    {
        return 'こんにちは、' . $name . 'さん！本日も学習お疲れ様です。';
    }

    /**
     * 文字列を逆さまにするフィルターの実体
     */
    public function reverseFilter(string $text): string
    {
        // PHP標準のstrrev関数を使って文字を反転させます
        return strrev($text);
    }
}

このコードでは、以下の2つの機能を定義しています。

• greeting関数： 渡した名前にメッセージを添えて返します。
• reverse_textフィルター： 入力した文字を「あいうえお」→「おえういあ」のように逆さまにします。

例えば、この関数をTwig側で呼び出すと、ブラウザには次のように表示されます。

こんにちは、太郎さん！本日も学習お疲れ様です。

Symfonyでは、このクラスを作成するだけで自動的にサービスとして認識されるため、難しい設定なしでテンプレートから呼び出せるようになります。次は実際にこれらの機能をテンプレート（HTML）でどのように使うかを見ていきましょう。

3. サービスとして登録しよう（自動登録）

3. サービスとして登録しよう（自動登録）

Symfony 4以降では、自動的にTwigにサービスが登録されるため、特別な設定は不要です。ただし、サービスファイルにあるservices.yamlで自動登録が有効になっていることは確認しましょう。

# config/services.yaml
services:
    App\Twig\:
        resource: '../src/Twig'
        tags: ['twig.extension']

これで、Twig内から自作した関数・フィルターが使えるようになります。

4. Twigテンプレートでカスタム関数を使う

4. Twigテンプレートでカスタム関数を使う

では、先ほど作成したgreeting関数をTwigで実際に使ってみましょう。

<p>{{ greeting('太郎') }}</p>

これは「こんにちは、太郎さん！」というメッセージを出力します。独自の挨拶機能など、表示内容を自由に変えたいときに便利です。

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

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

次に、reverseというフィルターを使って、文字列を逆さに表示する例です。

<p>{{ 'Symfony'|reverse }}</p>

このように書くと、ymonfSのように文字が反転して表示されます。文章や文字列の加工処理を入れたいときに非常に便利です。

6. カスタムTwig機能の活用例

6. カスタムTwig機能の活用例

カスタム関数やフィルターを使うことで、次のような場面でTwigテンプレートをより便利にできます。

• 会員名の敬称付け（例：「様」「さん」など）
• 郵便番号や電話番号のフォーマット処理
• 改行文字をHTMLの<br>に変換
• 特定キーワードのハイライト表示

複雑な処理はPHP側で書いて、Twigではシンプルに表示に集中できるように設計できます。

7. Twigでの命名と注意点

7. Twigでの命名と注意点

カスタム関数・フィルターを作るときは、次のような点に注意しましょう。

• 関数名・フィルター名はわかりやすく：処理の内容が伝わる名前にすること。
• 変数の型に注意：文字列だけでなく配列などを扱うときは型チェックをしましょう。
• 共通ロジックの再利用：同じ処理が何度もあるならTwig拡張で一元化すると便利です。

まとめ

まとめ

今回の記事では、PHPのフレームワークであるSymfonyで採用されている強力なテンプレートエンジン「Twig」を自分好みにカスタマイズする方法について詳しく解説してきました。標準で用意されているフィルターや関数だけでも十分に強力ですが、実際のプロジェクト開発では、業務固有の計算ロジックや特定の表示フォーマットが必要になる場面が多々あります。そうした際に、自作のカスタム関数やカスタムフィルターを導入することで、テンプレート側（HTML側）のコードを劇的にスッキリさせ、可読性とメンテナンス性を向上させることができます。

Twig拡張のメリットと設計のコツ

カスタム拡張を導入する最大のメリットは、「ロジックとデザインの分離」を徹底できる点にあります。例えば、複雑なif文や文字列操作をテンプレート内に直接書き込んでしまうと、後からデザインを修正する際にプログラムコードが邪魔になり、ミスを誘発しやすくなります。これをPHPクラス側のメソッドとして定義しておけば、Twig内では「{{ format_id(user.id) }}」のように一行書くだけで済みます。

また、複数のページで同じ表示ルール（日付のフォーマット、金額のカンマ区切り、特定のキーワードのカラーリングなど）を適用する場合も、拡張機能として一つ作っておけば、修正が必要になった際に一箇所を直すだけで全てのページに反映されます。これは大規模なWeb開発において、変更に強いシステムを作るための重要なテクニックです。

さらに高度なカスタム関数の実装例

ここでは、学んだことを応用して、実務でよく使われる「会員ランクに応じたバッジ表示」を生成するような、少し実践的なカスタム関数の例を見てみましょう。

namespace App\Twig;

use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class UserAppExtension extends AbstractExtension
{
    public function getFunctions(): array
    {
        return [
            // HTMLを出力する場合は 'is_safe' オプションが重要です
            new TwigFunction('render_rank_badge', [$this, 'renderRankBadge'], ['is_safe' => ['html']]),
        ];
    }

    public function renderRankBadge(string $rank): string
    {
        $color = 'secondary';
        $label = '一般会員';

        if ($rank === 'gold') {
            $color = 'warning';
            $label = 'ゴールド会員';
        } elseif ($rank === 'premium') {
            $color = 'danger';
            $label = 'プレミアム会員';
        }

        // HTMLタグを動的に生成して返す例
        return sprintf('<span class="badge bg-%s">%s</span>', $color, $label);
    }
}

この関数をTwigテンプレート側で呼び出すときは、以下のようになります。

{# ユーザーのランクが 'gold' の場合 #}
<div class="user-profile">
    ユーザー名：{{ user.name }}
    ランク：{{ render_rank_badge(user.rank) }}
</div>

実行結果は以下のようになります。

<div class="user-profile">
    ユーザー名：山田太郎
    ランク：<span class="badge bg-warning">ゴールド会員</span>
</div>

開発時のデバッグと注意点

カスタム機能を実装する際、もし反映されない場合は Symfony のキャッシュが原因であることがあります。開発環境であれば自動で反映されることが多いですが、`bin/console cache:clear` コマンドを実行してキャッシュをクリアする習慣をつけておくと安心です。また、`services.yaml` でのタグ設定（`twig.extension`）が正しく行われているかも、不具合が生じた際のチェックポイントになります。

Twigは非常に自由度が高いツールですが、何でもかんでもカスタム関数にするのではなく、まずは標準のフィルターで対応できないか検討することも大切です。標準機能を使いこなしつつ、どうしても手が届かない痒いところに「カスタム拡張」という強力な武器を差し込むのが、プロのエンジニアへの近道と言えるでしょう。