Merge pull request #5964 from softark/docs-guide-ja-2014-11-07

docs/guide-ja/structure-filters.md added [ci skip]
2025-11-03 22:32:40 +08:00 · 2014-11-07 16:18:52 +03:00
parent ef2bb4c7ea 01850733bb
commit 438a169110
5 changed files with 405 additions and 4 deletions
--- a/docs/guide-ja/README.md
+++ b/docs/guide-ja/README.md
@ -136,7 +136,7 @@ RESTful ウェブサービス
 * [ルーティング](rest-routing.md)
 * [レスポンスの書式設定](rest-response-formatting.md)
 * [認証](rest-authentication.md)
-* [速度制限](rest-rate-limiting.md)
+* [転送レート制限](rest-rate-limiting.md)
 * [バージョン管理](rest-versioning.md)
 * [エラー処理](rest-error-handling.md)
--- a/docs/guide-ja/images/request-lifecycle.png
+++ b/docs/guide-ja/images/request-lifecycle.png
--- a/docs/guide-ja/start-installation.md
+++ b/docs/guide-ja/start-installation.md
@ -35,9 +35,9 @@ Composer がインストールされたら、ウェブからアクセスでき
 必要なら別のディレクトリ名を選ぶことも出来ます。
 > Note|注意: インストール実行中に Composer が あなたの Github アカウントの認証情報を尋ねてくることがあるかも知れません。
-> これは、Comoser が Github API の帯域制限にひっかかったためです。
+> これは、Comoser が Github API の転送レート制限にひっかかったためです。
 > Composer は全てのパッケージのための大量の情報を Github から読み出さなければならないので、こうなるのは普通のことです。
-> Github にログインすると API の帯域制限が緩和され、Composer が仕事を続けることが出来るようになります。
+> Github にログインすると API の転送レート制限が緩和され、Composer が仕事を続けることが出来るようになります。
 > 更なる詳細については、[Composer documentation](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) を参照してください。
 > Tip|ヒント: Yii の最新の開発バージョンをインストールしたい場合は、[stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability) を追加した次のコマンドを代りに使うことが出来ます:
--- a/docs/guide-ja/structure-filters.md
+++ b/docs/guide-ja/structure-filters.md
@ -0,0 +1,401 @@
 フィルタ
 ========
 フィルタは、[コントローラアクション](structure-controllers.md#actions) の前 および/または 後に走るオブジェクトです。
 例えば、アクセスコントロールフィルタはアクションの前に走って、アクションが特定のエンドユーザだけにアクセスを許可するものであることを保証します。
 また、コンテンツ圧縮フィルタはアクションの後に走って、レスポンスのコンテンツをエンドユーザに送出する前に圧縮します。
 フィルタは、前フィルタ (アクションの *前* に適用されるフィルタのロジック) および/または 後フィルタ (アクションの *後*
 に適用されるフィルタ) から構成されます。
 ## フィルタを使用する <a name="using-filters"></a>
 フィルタは、本質的には特別な種類の [ビヘイビア](concept-behaviors.md) です。したがって、フィルタを使うことは
 [ビヘイビアを使う](concept-behaviors.md#attaching-behaviors) ことと同じです。下記のように、
 [[yii\base\Controller::behaviors()|behaviors()]] メソッドをオーバーライドすることによって、コントローラの中で
 フィルタを宣言することが出来ます:
 ```php
 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');
            },
        ],
    ];
 }
 ```
 既定では、コントローラクラスの中で宣言されたフィルタは、そのコントローラの *全て* のアクションに適用されます。
 しかし、[[yii\base\ActionFilter::only|only]] プロパティを構成することによって、フィルタがどのアクションに適用されるべきかを
 明示的に指定することも出来ます。上記の例では、 `HttpCache` フィルタは、`index` と `view` のアクションに対してのみ適用されています。
 また、[[yii\base\ActionFilter::except|except]] プロパティを構成して、いくつかのアクションをフィルタされないように除外することも可能です。
 コントローラのほかに、[モジュール](structure-modules.md) または [アプリケーション](structure-applications.md)
 でもフィルタを宣言することが出来ます。
 そのようにした場合、[[yii\base\ActionFilter::only|only]] と [[yii\base\ActionFilter::except|except]] のプロパティを
 上で説明したように構成しない限り、そのフィルタは、モジュールまたはアプリケーションに属する *全て* のコントローラアクションに適用されます。
 > Note|注意: モジュールやアプリケーションでフィルタを宣言する場合、[[yii\base\ActionFilter::only|only]] と
  [[yii\base\ActionFilter::except|except]] のプロパティでは、アクション ID ではなく、[ルート](structure-controllers.md#routes)
  を使うべきです。なぜなら、モジュールやアプリケーションのスコープでは、アクション ID だけでは完全にアクションを指定することが
  出来ないからです。
 一つのアクションに複数のフィルタが構成されている場合、フィルタは下記で説明されている規則に従って適用されます。
 * 前フィルタ
    - アプリケーションで宣言されたフィルタを `behaviors()` にリストされた順に適用する。
    - モジュールで宣言されたフィルタを `behaviors()` にリストされた順に適用する。
    - コントローラで宣言されたフィルタを `behaviors()` にリストされた順に適用する。
    - フィルタのどれかがアクションをキャンセルすると、そのフィルタの後のフィルタ (前フィルタと後フィルタの両方) は適用されない。
 * 前フィルタを通過したら、アクションを走らせる。
 * 後フィルタ
    - コントローラで宣言されたフィルタを `behaviors()` にリストされた逆順で適用する。
    - モジュールで宣言されたフィルタを `behaviors()` にリストされた逆順で適用する。
    - アプリケーションで宣言されたフィルタを `behaviors()` にリストされた逆順で適用する。
 ## フィルタを作成する <a name="creating-filters"></a>
 新しいアクションフィルタを作成するためには、[[yii\base\ActionFilter]] を拡張して、
 [[yii\base\ActionFilter::beforeAction()|beforeAction()]] および/または [[yii\base\ActionFilter::afterAction()|afterAction()]]
 メソッドをオーバーライドします。前者はアクションが走る前に実行され、後者は走った後に実行されます。
 [[yii\base\ActionFilter::beforeAction()|beforeAction()]] の返り値が、アクションが実行されるべきか否かを決定します。
 返り値が false である場合、このフィルタの後に続くフィルタはスキップされ、アクションは実行を中止されます。
 次の例は、アクションの実行時間をログに記録するフィルタを示すものです:
 ```php
 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::trace("アクション '{$action->uniqueId}' は $time 秒を消費。");
        return parent::afterAction($action, $result);
    }
 }
 ```
 ## コアのフィルタ <a name="core-filters"></a>
 Yii はよく使われる一連のフィルタを提供しており、それらは、主として `yii\filters` 名前空間の下にあります。以下では、
 それらのフィルタを簡単に紹介します。
 ### [[yii\filters\AccessControl|AccessControl]] <a name="access-control"></a>
 AccessControl は、一組の [[yii\filters\AccessControl::rules|規則]] に基づいて、シンプルなアクセスコントロールを提供するものです。
 具体的に言うと、アクションが実行される前に、AccessControl はリストされた規則を調べて、現在のコンテキスト変数 (例えば、ユーザの IP アドレスや、ユーザのログイン状態など) に最初に合致するものを見つけます。
 そして、合致した規則によって、リクエストされたアクションの実行を許可するか拒否するかを決定します。
 合致する規則がなかった場合は、アクセスは拒否されます。
 次の例は、認証されたユーザに対しては `create` と `update` のアクションへのアクセスを許可し、
 その他のすべてのユーザにはこれら二つのアクションに対するアクセスを拒否する仕方を示すものです。
 ```php
 use yii\filters\AccessControl;
 public function behaviors()
 {
    return [
        'access' => [
            'class' => AccessControl::className(),
            'only' => ['create', 'update'],
            'rules' => [
                // 認証されたユーザに許可する
                [
                    'allow' => true,
                    'roles' => ['@'],
                ],
                // その他は、既定により拒否される
            ],
        ],
    ];
 }
 ```
 アクセスコントロール一般について、更なる詳細は [権限](security-authorization.md) の節を参照してください。
 ### 認証メソッドフィルタ <a name="auth-method-filters"></a>
 認証メソッドフィルタは、[HTTP Basic 認証](http://ja.wikipedia.org/wiki/Basic%E8%AA%8D%E8%A8%BC)、
 [OAuth 2](http://oauth.net/2/) など、様々なメソッドを使ってユーザを認証するために使われるものです。
 これらのフィルタクラスはすべて `yii\filters\auth` 名前空間の下にあります。
 次の例は、[[yii\filters\auth\HttpBasicAuth]] の使い方を示すもので、HTTP Basic 認証に基づくアクセストークンを使ってユーザを認証しています。
 これを動作させるためには、あなたの [[yii\web\User::identityClass|ユーザアイデンティティクラス]] が
 [[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]] 
 メソッドを実装していなければならないことに注意してください。
 ```php
 use yii\filters\auth\HttpBasicAuth;
 public function behaviors()
 {
    return [
        'basicAuth' => [
            'class' => HttpBasicAuth::className(),
        ],
    ];
 }
 ```
 認証メソッドフィルタは RESTful API を実装するときに使われるのが通例です。詳細については、
 RESTful の [認証](rest-authentication.md) の節を参照してください。
 ### [[yii\filters\ContentNegotiator|ContentNegotiator]] <a name="content-negotiator"></a>
 ContentNegotiator は、レスポンス形式のネゴシエーションとアプリケーション言語のネゴシエーションをサポートします。
 このフィルタは `GET` パラメータと `Accept` HTTP ヘッダを調べることによって、レスポンス形式 および/または
 言語を決定しようとします。
 次の例では、ContentNegotiator はレスポンス形式として JSON と XML をサポートし、(合衆国の)英語とドイツ語を
 言語としてサポートするように構成されています。
 ```php
 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',
            ],
        ],
    ];
 }
 ```
 レスポンス形式と言語は [アプリケーションのライフサイクル](structure-applications.md#application-lifecycle)
 のもっと早い段階で決定される必要があることがよくあります。このため、ContentNegotiator はフィルタの他に、
 [ブートストラップコンポーネント](structure-applications.md#bootstrap) としても使うことができるように設計されています。
 例えば、次のように、ContentNegotiator を [アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) の中で構成することが出来ます。
 ```php
 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]]
 に挙げられている最初の形式と言語が使用されます。
 ### [[yii\filters\HttpCache|HttpCache]] <a name="http-cache"></a>
 HttpCache は `Last-Modified` および `Etag` の HTTP ヘッダを利用して、クライアントサイドのキャッシュを実装するものです。
 ```php
 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 キャッシュ](caching-http.md) の節を参照してください。
 ### [[yii\filters\PageCache|PageCache]] <a name="page-cache"></a>
 PageCache はサーバサイドにおけるページ全体のキャッシュを実装するものです。次の例では、PageCache が
 `index` アクションに適用されて、最大 60 秒間、または、`post` テーブルのエントリ数が変化するまでの間、
 ページ全体をキャッシュしています。さらに、このページキャッシュは、選択されたアプリケーションの言語に従って、
 違うバージョンのページを保存するようにしています。
 ```php
 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 の使用に関する更なる詳細は [ページキャッシュ](caching-page.md) の節を参照してください。
 ### [[yii\filters\RateLimiter|RateLimiter]] <a name="rate-limiter"></a>
 RateLimiter は [リーキーバケットアルゴリズム](http://ja.wikipedia.org/wiki/%E3%83%AA%E3%83%BC%E3%82%AD%E3%83%BC%E3%83%90%E3%82%B1%E3%83%83%E3%83%88)
 に基づいて転送レート制限のアルゴリズムを実装するものです。主として RESTful API を実装するときに使用されます。
 このフィルタの使用に関する詳細は [転送レート制限](rest-rate-limiting.md) の節を参照してください。
 ### [[yii\filters\VerbFilter|VerbFilter]] <a name="verb-filter"></a>
 VerbFilter は、HTTP リクエストメソッドがリクエストされたアクションによって許可されているかどうかをチェックするものです。
 許可されていない場合は、HTTP 405 例外を投げます。次の例では、VerbFilter が宣言されて、
 CRUD アクションに対して許可されるメソッドの典型的なセットを規定しています。
 ```php
 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'],
            ],
        ],
    ];
 }
 ```
 ### [[yii\filters\Cors|Cors]] <a name="cors"></a>
 クロスオリジンリソース共有 [CORS](https://developer.mozilla.org/ja/docs/HTTP_access_control) とは、
 ウェブページにおいて、さまざまなリソース (例えば、フォントや JavaScript など) を、
 それを生成するドメイン以外のドメインからリクエストすることを可能にするメカニズムです。
 特に言えば、JavaScript の AJAX 呼出しが使用することが出来る XMLHttpRequest メカニズムです。
 このような「クロスドメイン｣のリクエストは、このメカニズムに拠らなければ、
 同一生成元のセキュリティポリシーによって、ウェブブラウザから禁止されるはずのものです。
 CORS は、ブラウザとサーバが交信して、クロスドメインのリクエストを許可するか否かを決定する方法を定義するものです。
 [[yii\filters\Cors|Cors フィルタ]] は、CORS ヘッダが常に送信されることを保証するために、Authentication / Authorization のフィルタよりも前に定義されなければなりません。
 ```php
 use yii\filters\Cors;
 use yii\helpers\ArrayHelper;
 public function behaviors()
 {
    return ArrayHelper::merge([
        [
            'class' => Cors::className(),
        ],
    ], parent::behaviors());
 }
 ```
 Cors のフィルタリングは `cors` プロパティを使ってチューニングすることが出来ます。
 * `cors['Origin']`: 許可される生成元を定義するのに使われる配列。`['*']` (すべて) または `['http://www.myserver.net'、'http://www.myotherserver.com']` などが設定可能。デフォルトは `['*']`。
 * `cors['Access-Control-Request-Method']`: 許可されるメソッドの配列。たとえば、`['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 を許可するものです:
 ```php
 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` を追加することは、次のようにすれば出来ます:
 ```php
 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());
 }
 ```
--- a/docs/guide-ja/structure-models.md
+++ b/docs/guide-ja/structure-models.md
@ -402,7 +402,7 @@ $array = $post->attributes;
 しかしながら、このメソッドを使うと、どのデータ項目 (*フィールド* と呼ばれます) を結果の配列に入れるか、
 そして、その項目にどのような書式を適用するかを選ぶことが出来ます。
 実際、[レスポンスの書式設定](rest-response-formatting.md) で説明されているように、
-RESTFul ウェブサービスの開発においては、これがモデルをエクスポートする既定の方法となっています。
+RESTful ウェブサービスの開発においては、これがモデルをエクスポートする既定の方法となっています。
 ### フィールド<a name="fields"></a>