フィルタ ¶

フィルタを使用する
フィルタを作成する
コアのフィルタ

フィルタは、コントローラ・アクションの前および/または後に走るオブジェクトです。例えば、アクセス・コントロール・フィルタはアクションの前に走って、アクションが特定のエンド・ユーザだけにアクセスを許可するものであることを保証します。また、コンテント圧縮フィルタはアクションの後に走って、レスポンスのコンテントをエンド・ユーザに送出する前に圧縮します。

一つのフィルタは、前フィルタ (アクションの前に適用されるフィルタのロジック) および/または後フィルタ (アクションの後に適用されるロジック) から構成することが出来ます。

フィルタを使用する ¶

フィルタは、本質的には特別な種類のビヘイビアです。したがって、フィルタを使うことはビヘイビアを使うことと同じです。下記のように、behaviors() メソッドをオーバーライドすることによって、コントローラの中でフィルタを宣言することが出来ます。

public function behaviors()
{
    return [
        [
            'class' => 'yii\filters\HttpCache',
            'only' => ['index', 'view'],
            'lastModified' => function ($action, $params) {
                $q = new \yii\db\Query();
                return $q->from('user')->max('updated_at');
            },
        ],
    ];
}

デフォルトでは、コントローラ・クラスの中で宣言されたフィルタは、そのコントローラの全てのアクションに適用されます。しかし、only プロパティを構成することによって、フィルタがどのアクションに適用されるべきかを明示的に指定することも出来ます。上記の例では、 HttpCache フィルタは、index と view のアクションに対してのみ適用されています。また、except プロパティを構成して、いくつかのアクションをフィルタされないように除外することも可能です。

コントローラのほかに、モジュールまたはアプリケーションでもフィルタを宣言することが出来ます。そのようにした場合、only と except のプロパティを上で説明したように構成しない限り、そのフィルタは、モジュールまたはアプリケーションに属する全てのコントローラ・アクションに適用されます。

Note: モジュールやアプリケーションでフィルタを宣言する場合、only と except のプロパティでは、アクション ID ではなく、ルートを使わなければなりません。なぜなら、モジュールやアプリケーションのスコープでは、アクション ID だけでは完全にアクションを指定することが出来ないからです。

一つのアクションに複数のフィルタが構成されている場合、フィルタは下記で説明されている規則に従って適用されます。

前フィルタ
- アプリケーションで宣言されたフィルタを behaviors() にリストされた順に適用する。
- モジュールで宣言されたフィルタを behaviors() にリストされた順に適用する。
- コントローラで宣言されたフィルタを behaviors() にリストされた順に適用する。
- フィルタのどれかがアクションをキャンセルすると、そのフィルタの後のフィルタ (前フィルタと後フィルタの両方) は適用されない。
前フィルタを通過したら、アクションを走らせる。
後フィルタ
- コントローラで宣言されたフィルタを behaviors() にリストされた逆順で適用する。
- モジュールで宣言されたフィルタを behaviors() にリストされた逆順で適用する。
- アプリケーションで宣言されたフィルタを behaviors() にリストされた逆順で適用する。

フィルタを作成する ¶

新しいアクション・フィルタを作成するためには、yii\base\ActionFilter を拡張して、 beforeAction() および/または afterAction() メソッドをオーバーライドします。前者はアクションが走る前に実行され、後者は走った後に実行されます。 beforeAction() の返り値が、アクションが実行されるべきか否かを決定します。返り値が false である場合、このフィルタの後に続くフィルタはスキップされ、アクションは実行を中止されます。

次の例は、アクションの実行時間をログに記録するフィルタを示すものです。

namespace app\components;

use Yii;
use yii\base\ActionFilter;

class ActionTimeFilter extends ActionFilter
{
    private $_startTime;

    public function beforeAction($action)
    {
        $this->_startTime = microtime(true);
        return parent::beforeAction($action);
    }

    public function afterAction($action, $result)
    {
        $time = microtime(true) - $this->_startTime;
        Yii::debug("アクション '{$action->uniqueId}' は $time 秒を消費。");
        return parent::afterAction($action, $result);
    }
}

コアのフィルタ ¶

Yii はよく使われる一連のフィルタを提供しており、それらは、主として yii\filters 名前空間の下にあります。以下では、それらのフィルタを簡単に紹介します。

AccessControl ¶

AccessControl は、一組の規則に基づいて、シンプルなアクセス・コントロールを提供するものです。具体的に言うと、アクションが実行される前に、AccessControl はリストされた規則を調べて、現在のコンテキスト変数 (例えば、ユーザの IP アドレスや、ユーザのログイン状態など) に最初に合致するものを見つけます。そして、合致した規則によって、リクエストされたアクションの実行を許可するか拒否するかを決定します。合致する規則がなかった場合は、アクセスは拒否されます。

次の例は、認証されたユーザに対しては create と update のアクションへのアクセスを許可し、その他のすべてのユーザにはこれら二つのアクションに対するアクセスを拒否する仕方を示すものです。

use yii\filters\AccessControl;

public function behaviors()
{
    return [
        'access' => [
            'class' => AccessControl::className(),
            'only' => ['create', 'update'],
            'rules' => [
                // 認証されたユーザに許可する
                [
                    'allow' => true,
                    'roles' => ['@'],
                ],
                // その他はすべてデフォルトにより拒否される
            ],
        ],
    ];
}

アクセス・コントロール一般についての詳細は権限のセクションを参照してください。

認証メソッド・フィルタ ¶

認証メソッド・フィルタは、HTTP Basic 認証、 OAuth 2 など、様々なメソッドを使ってユーザを認証するために使われるものです。これらのフィルタ・クラスはすべて yii\filters\auth 名前空間の下にあります。

次の例は、yii\filters\auth\HttpBasicAuth の使い方を示すもので、HTTP Basic 認証に基づくアクセス・トークンを使ってユーザを認証しています。これを動作させるためには、あなたのユーザ・アイデンティティ・クラスが findIdentityByAccessToken() メソッドを実装していなければならないことに注意してください。

use yii\filters\auth\HttpBasicAuth;

public function behaviors()
{
    return [
        'basicAuth' => [
            'class' => HttpBasicAuth::className(),
        ],
    ];
}

認証メソッド・フィルタは RESTful API を実装するときに使われるのが通例です。詳細については、RESTful の認証のセクションを参照してください。

ContentNegotiator ¶

ContentNegotiator は、レスポンス形式のネゴシエーションとアプリケーション言語のネゴシエーションをサポートします。このフィルタは GET パラメータと Accept HTTP ヘッダを調べることによって、レスポンス形式および/または言語を決定しようとします。

次の例では、ContentNegotiator はレスポンス形式として JSON と XML をサポートし、 (合衆国の)英語とドイツ語を言語としてサポートするように構成されています。

use yii\filters\ContentNegotiator;
use yii\web\Response;

public function behaviors()
{
    return [
        [
            'class' => ContentNegotiator::className(),
            'formats' => [
                'application/json' => Response::FORMAT_JSON,
                'application/xml' => Response::FORMAT_XML,
            ],
            'languages' => [
                'en-US',
                'de',
            ],
        ],
    ];
}

レスポンス形式と言語はアプリケーションのライフサイクルのもっと早い段階で決定される必要があることがよくあります。このため、ContentNegotiator はフィルタの他に、ブートストラップ・コンポーネントとしても使うことができるように設計されています。例えば、次のように、ContentNegotiator をアプリケーションの構成情報の中で構成することが出来ます。

use yii\filters\ContentNegotiator;
use yii\web\Response;

[
    'bootstrap' => [
        [
            'class' => ContentNegotiator::className(),
            'formats' => [
                'application/json' => Response::FORMAT_JSON,
                'application/xml' => Response::FORMAT_XML,
            ],
            'languages' => [
                'en-US',
                'de',
            ],
        ],
    ],
];

Info: 望ましいコンテント・タイプと言語がリクエストから決定できない場合は、 formats および languages に挙げられている最初の形式と言語が使用されます。

HttpCache ¶

HttpCache は Last-Modified および Etag の HTTP ヘッダを利用して、クライアント・サイドのキャッシュを実装するものです。例えば、

use yii\filters\HttpCache;

public function behaviors()
{
    return [
        [
            'class' => HttpCache::className(),
            'only' => ['index'],
            'lastModified' => function ($action, $params) {
                $q = new \yii\db\Query();
                return $q->from('user')->max('updated_at');
            },
        ],
    ];
}

HttpCache に関する詳細は HTTP キャッシュのセクションを参照してください。

PageCache ¶

PageCache はサーバ・サイドにおけるページ全体のキャッシュを実装するものです。次の例では、PageCache が index アクションに適用されて、最大 60 秒間、または、post テーブルのエントリ数が変化するまでの間、ページ全体をキャッシュしています。さらに、このページ・キャッシュは、選択されたアプリケーションの言語に従って、違うバージョンのページを保存するようにしています。

use yii\filters\PageCache;
use yii\caching\DbDependency;

public function behaviors()
{
    return [
        'pageCache' => [
            'class' => PageCache::className(),
            'only' => ['index'],
            'duration' => 60,
            'dependency' => [
                'class' => DbDependency::className(),
                'sql' => 'SELECT COUNT(*) FROM post',
            ],
            'variations' => [
                \Yii::$app->language,
            ]
        ],
    ];
}

PageCache の使用に関する詳細はページ・キャッシュのセクションを参照してください。

RateLimiter ¶

RateLimiter はリーキー・バケット・アルゴリズムに基づいてレート制限のアルゴリズムを実装するものです。主として RESTful API を実装するときに使用されます。このフィルタの使用に関する詳細はレート制限のセクションを参照してください。

VerbFilter ¶

VerbFilter は、HTTP リクエスト・メソッド (HTTP 動詞) がリクエストされたアクションによって許可されているかどうかをチェックするものです。許可されていない場合は、HTTP 405 例外を投げます。次の例では、VerbFilter が宣言されて、CRUD アクションに対して許可されるメソッドの典型的なセットを指定しています。

use yii\filters\VerbFilter;

public function behaviors()
{
    return [
        'verbs' => [
            'class' => VerbFilter::className(),
            'actions' => [
                'index'  => ['get'],
                'view'   => ['get'],
                'create' => ['get', 'post'],
                'update' => ['get', 'put', 'post'],
                'delete' => ['post', 'delete'],
            ],
        ],
    ];
}

Cors ¶

クロス・オリジン・リソース共有 CORS とは、ウェブ・ページにおいて、さまざまなリソース (例えば、フォントや JavaScript など) を、それを生成するドメイン以外のドメインからリクエストすることを可能にするメカニズムです。特に言えば、JavaScript の AJAX 呼出しが使用することが出来る XMLHttpRequest メカニズムです。このような「クロス・ドメイン｣のリクエストは、このメカニズムに拠らなければ、同一生成元のセキュリティ・ポリシーによって、ウェブ・ブラウザから禁止されるはずのものです。 CORS は、ブラウザとサーバが交信して、クロス・ドメインのリクエストを許可するか否かを決定する方法を定義するものです。

Cors フィルタは、CORS ヘッダが常に送信されることを保証するために、 Authentication / Authorization のフィルタよりも前に定義されなければなりません。

use yii\filters\Cors;
use yii\helpers\ArrayHelper;

public function behaviors()
{
    return ArrayHelper::merge([
        [
            'class' => Cors::className(),
        ],
    ], parent::behaviors());
}

あなたの API の yii\rest\ActiveController クラスに CORS フィルタを追加したい場合は、 REST コントローラのセクションも参照して下さい。

Cors のフィルタリングは $cors プロパティを使ってチューニングすることが出来ます。

cors['Origin']: 許可される生成元を定義するのに使われる配列。['*'] (すべて) または ['http://www.myserver.net'、'http://www.myotherserver.com'] などが設定可能。デフォルトは ['*']。
cors['Access-Control-Request-Method']: 許可される HTTP 動詞の配列。たとえば、['GET', 'OPTIONS', 'HEAD']。デフォルトは ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']。
cors['Access-Control-Request-Headers']: 許可されるヘッダの配列。全てのヘッダを意味する ['*'] または特定のヘッダを示す ['X-Request-With'] が設定可能。デフォルトは ['*']。
cors['Access-Control-Allow-Credentials']: 現在のリクエストをクレデンシャルを使ってすることが出来るかどうかを定義。true、false または null (設定なし) が設定可能。デフォルトは null。
cors['Access-Control-Max-Age']: プリフライト・リクエストの寿命を定義。デフォルトは 86400。

次の例は、生成元 http://www.myserver.net に対する GET、HEAD および OPTIONS のメソッドによる CORS を許可するものです。

use yii\filters\Cors;
use yii\helpers\ArrayHelper;

public function behaviors()
{
    return ArrayHelper::merge([
        [
            'class' => Cors::className(),
            'cors' => [
                'Origin' => ['http://www.myserver.net'],
                'Access-Control-Request-Method' => ['GET', 'HEAD', 'OPTIONS'],
            ],
        ],
    ], parent::behaviors());
}

デフォルトのパラメータをアクション単位でオーバーライドして CORS ヘッダをチューニングすることも可能です。例えば、login アクションに Access-Control-Allow-Credentials を追加することは、次のようにすれば出来ます。

use yii\filters\Cors;
use yii\helpers\ArrayHelper;

public function behaviors()
{
    return ArrayHelper::merge([
        [
            'class' => Cors::className(),
            'cors' => [
                'Origin' => ['http://www.myserver.net'],
                'Access-Control-Request-Method' => ['GET', 'HEAD', 'OPTIONS'],
            ],
            'actions' => [
                'login' => [
                    'Access-Control-Allow-Credentials' => true,
                ]
            ]
        ],
    ], parent::behaviors());
}