ディスパッチャー・フィルター

Added in version 2.2

コントローラーのコードが実行される前、もしくはクライアントにレスポンスを送ろうとする直前に、なにがしかのコードを動かしたいというケースがあります。たとえば、レスポンスのキャッシングやヘッダーのチューニング、特殊な認証、もしくは単に、リクエストを処理するサイクルに要する時間より短時間のうちにミッションクリティカルな API レスポンスにアクセスさせたい、といったケースが挙げられます。

CakePHP では、このようなケースについて、実行サイクルに対してフィルターを適用するための、クリーンで拡張可能なインターフェースを備えています。ちょうど、リクエスト毎のスタッカブルなサービスやルーチンを提供する、ミドルウェアのレイヤーのようなものです。私たちはこれを Dispatcher Filters と呼んでいます。

フィルターを設定する

フィルターは通常 config/bootstrap.php ファイルの中で設定されますが、リクエストがディスパッチされる（制御が移る）前であれば、どの設定ファイルからでも気軽にロードして構いません。フィルターの追加や削除は、 Configure クラスの中で特別な Dispatcher.filters キーを使って行われます。 CakePHP にはデフォルトで２つのフィルタークラスが備わっており、すべてのリクエストですでに有効になっています。ここでは、それらがどのように追加されているのかを見てみましょう。:

// config/bootstrap.php
Configure::write('Dispatcher.filters', [
    'AssetDispatcher',
    'CacheDispatcher',
]);

これらの配列の値は、それぞれディスパッチャーのレベルで生成されたイベントのためのリスナーとしてインスタンス化および追加されたクラスの名前です。ひとつ目の AssetDispatcher は、プラグインの webroot フォルダーや、テーマに対応するフォルダーに格納されている CSS、JavaScript、画像といったテーマやプラグインの静的(asset)ファイルを参照しているリクエストなのかどうかをチェックするためのものです。これは、その実行結果として、それらのファイルがあればそれらを提供し、それ以上のディスパッチサイクルを中止します。 CacheDispatcher フィルターは、 Cache.check 設定変数が有効の場合、レスポンスがすでにファイルシステムの中で似たようなリクエストのためにキャッシュされているかどうかをチェックし、もしあればそのキャッシュコードを即座に提供します。

これでわかるように、いずれの提供されたフィルターも、後続のコードの実行を打ち切ってクライアントに即座にレスポンスを返す責任を負っています。しかし後述のように、フィルターの役割はこれだけではありません。

フィルターのリストにあなた自身のクラス名を追加すると、それらは定義された順番に実行されます。さらに、特殊な DispatcherFilter クラスとは関係ないフィルターを接続するための別の方法もあります。:

Configure::write('Dispatcher.filters', [
    'my-filter' => [
        'callable' => [$classInstance, 'methodName'],
        'on' => 'after',
    ],
]);

これに示されるように、PHP で有効な callback であれば、何でも渡すことができます。覚えていると思いますが、 callback は PHP が call_user_func で実行することのできるものすべでです。ただ小さな例外があります。もし文字列が渡されると、それは関数名としては見てもらえず、クラス名として扱われます。無名関数もフィルターとして指定できます。:

Configure::write('Dispatcher.filters', [
    'my-filter' => [
        'callable' => function ($event) {
            // ...
        },
        'on' => 'before',
    ],
    // さらにフィルターを記載可能
]);

on キーに有効な値は before と after のみです。これは文字通り、コントローラーのコードが実行される前にそのフィルターを実行するのかそれとも後なのかを指定します。フィルターには callable キーを指定できますが、さらにあなたのフィルターの優先度を指定することも可能です。もし何も指定されなければ、デフォルトの 10 が選ばれます。

すべてのフィルターはデフォルトで 10 の優先度を持っているため、他のすべてのフィルータの実行より前に実行させたければ、必要に応じてより小さな数値を指定してください。:

Configure::write('Dispatcher.filters', [
    'my-filter' => [
        'callable' => function ($event) {
            // ...
        },
        'on' => 'before',
        'priority' => 5,
    ],
    'other-filter' => [
        'callable' => [$class, 'method'],
        'on' => 'after',
        'priority' => 1,
    ],
    // さらなるフィルター定義
]);

優先度を指定した場合、宣言の順序が意味を持つのは同じ優先度のフィルター同士だけです。フィルターをクラス名として定義する場合は、ここで優先度を指定することはできません。これについては後ほど説明します。最後に、CakePHP のプラグイン記法を使って、プラグインの中にあるフィルターを指定することもできます。フィルタークラスはプラグインの Routing/Filter ディレクトリ、たとえば plugins/MyPlugin/Routing/Filter/MyFilter.php から読み込まれます。:

Configure::write('Dispatcher.filters', [
    'MyPlugin.MyFilter',
]);

テーマやプラグインの静的ファイルを提供するための、より先進的で速い手段を選ぶためとか、ビルトインの完全なページキャッシング機能を使いたくないとか、あるいは自分で実装したいなどの理由があれば、デフォルトで接続されたフィルターを外しても特に問題ありません。

あなたが作成したディスパッチフィルタークラスのコンストラクターにパラメーターや設定を渡す必要がある場合、設定を配列として渡します。:

Configure::write('Dispatcher.filters', [
    'MyAssetFilter' => ['service' => 'google.com'],
]);

フィルターのキーが有効なクラス名の場合、その値としてディスパッチフィルターに渡すパラメーターの配列を指定することも可能です。デフォルトでは、ベースクラスの中でこれらの設定がデフォルト値とマージされ、その後それらの値が $settings プロパティにセットされます。ディスパッチャーはこの書き方を class_exists() で判定するため、フィルタークラスがすでにオートロード可能でなければなりません。src/ にクラスを追加したら composer dump-autoload を実行してください。

Changed in version 2.5

2.5 から、コンストラクタの設定をディスパッチフィルターに渡すことができるようになりました。

フィルタークラス

ディスパッチフィルターが設定の中でクラス名として定義されている場合、それは CakePHP ディレクトリの Routing の中で DispatcherFilter を継承している必要があります。ここで特定の URL に対して 'Hello World' を返すようなシンプルなフィルターを作ってみましょう。:

// src/Routing/Filter/HelloWorldFilter.php
class HelloWorldFilter extends DispatcherFilter
{
    public $priority = 9;

    public function beforeDispatch(CakeEvent $event)
    {
        $request = $event->data['request'];
        $response = $event->data['response'];

        if ($request->url === 'hello-world') {
            $response->body('Hello World');
            $event->stopPropagation();

            return $response;
        }
    }
}

このクラスを src/Routing/Filter/HelloWorldFilter.php ファイルとして保存し、前節で説明したような要領で config/bootstrap.php の中で設定する必要があります。 src/ 以下のアプリケーションクラスは Composer の classmap でオートロードされるので、ファイルを追加したら composer dump-autoload を実行してください。ここで説明すべきことはたくさんあるのですが、まずは $priority 値から見てみましょう。

前述のように、フィルタークラスを使う場合は、そのクラスの中で $priority プロパティを使って実行順序を定義することしかできません。このプロパティが宣言されている場合、そのデフォルト値は 10 なので、Router クラスがリクエストをパースした後に実行されるということになります。直前の例では、これは望ましくない動作です。なぜなら、この URL に答えるようなコントローラーを用意していることは、まずありえないからです。そのため、私たちは優先度として 9 を選ぶことになります。

DispatcherFilter には、サブクラスでオーバーライドするべき２つのメソッド beforeDispatch と afterDispatch があります。これらは順に、コントローラーが実行される『前』と『後』に実行されます。いずれのメソッドも CakeEvent イベントを受け取りますが、この中には request と response オブジェクト（CakeRequest と CakeResponse インスタンス）が含まれており、さらに data プロパティの中に additionalParams 配列が入っています。後者には requestAction をコールする際の内部ディスパッチングで使われる情報も入っています。

私たちの例では、結果として条件付きで $response オブジェクトを返します。これは、ディスパッチャーに対して、コントローラーのインスタンスは作らずに、即座にクライアントにそのようなオブジェクトをレスポンスとして返すよう指示します。さらに、私たちは $event->stopPropagation() を追加することで、この後に別のフィルターが起動されることを防ぎます。

次は、何らかの公開ページにおいて代替のレスポンスヘッダーを返すための新たなフィルターを作ってみましょう。このケースでは、 PagesController から提供されるものであれば何でも構いません。:

// src/Routing/Filter/HttpCacheFilter.php
class HttpCacheFilter extends DispatcherFilter
{
    public function afterDispatch(CakeEvent $event)
    {
        $request = $event->data['request'];
        $response = $event->data['response'];

        if ($request->params['controller'] !== 'pages') {
            return;
        }
        if ($response->statusCode() === 200) {
            $response->sharable(true);
            $response->expires(strtotime('+1 day'));
        }
    }
}

このフィルターは、ページコントローラーによって生成されるすべてのレスポンスについて、１日後に期限切れとなるヘッダーを送信します。もちろん、これと同様の処理をコントローラーの中で行っても構いませんが、これは単にフィルターを使って何ができるのかの例に過ぎません。たとえば、代替のヘッダーを返す代わりに、Cache クラスを使ってそれをキャッシュすることもできますし、 beforeDispatch コールバックからレスポンスを返すことも可能です。

インラインフィルター

最後にお見せする例では、無名関数を使って JSON フォーマットでポストされたデータの一覧を返します。これは本来コントローラーと JsonView クラスを使って行なうべきですが、たとえばミッションクリティカルな API のエンドポイントで、なんとか数 ms でも節約しなければならないようなケースを想像してみてください。:

// config/bootstrap.php
$postsList = function ($event) {
    if ($event->data['request']->url !== 'posts/recent.json') {
        return;
    }
    $postModel = ClassRegistry::init('Post');
    $event->data['response']->body(json_encode($postModel->find('recent')));
    $event->stopPropagation();

    return $event->data['response'];
};

Configure::write('Dispatcher.filters', [
    'AssetDispatcher',
    'CacheDispatcher',
    'recent-posts' => [
        'callable' => $postsList,
        'priority' => 9,
        'on' => 'before',
    ],
]);

直前の例では、私たちは自身のフィルターについて 9 の優先度を選びました。そのため、カスタムで用意したその他のロジックや、CakePHP の内部ルーティングシステムなどのコアフィルターをスキップすることができました。しかしながら、それは本来必要なことではなく、単にある種のリクエストに対する肥大化した処理を削減する必要がある場合に、あなたの重要なコードを最初に実行させる方法を示すためのものです。

これを実装すると、あなたのアプリケーションの保守性が著しく低下することは自明です。フィルターは上手に使うと非常にパワフルなツールですが、あなたのアプリケーションでそれぞれの URL のレスポンスハンドラーを追加することは、決して好ましいことではありません。しかしながら、本当にそれが必要な状況であれば、身近にあるクリーンな解決策です。すべてのケースをフィルターにする必要がないことだけは覚えておいてください。あなたのアプリケーションにリクエストハンドラーを追加する場合、通常は Controllers と Components が正しい選択であるはずです。

ディスパッチャー・フィルター ​

フィルターを設定する ​

フィルタークラス ​

インラインフィルター ​

ディスパッチャー・フィルター

フィルターを設定する

フィルタークラス

インラインフィルター