From 7196d32644d6e8d9af24d6ac5601ca4a2b38830f Mon Sep 17 00:00:00 2001 From: Nobuo Kihara Date: Mon, 23 Apr 2018 17:23:33 +0900 Subject: [PATCH] guide-ja/runtime revised [ci skip] (#16150) * guide-ja/runtime revised [ci skip] * guide-ja/runtime revised [ci skip] --- docs/guide-ja/runtime-bootstrapping.md | 25 +++-- docs/guide-ja/runtime-handling-errors.md | 39 +++++--- docs/guide-ja/runtime-logging.md | 95 ++++++++++++------ docs/guide-ja/runtime-overview.md | 6 +- docs/guide-ja/runtime-requests.md | 55 ++++++---- docs/guide-ja/runtime-responses.md | 28 +++--- docs/guide-ja/runtime-routing.md | 161 +++++++++++++++++++----------- docs/guide-ja/runtime-sessions-cookies.md | 48 ++++++--- 8 files changed, 292 insertions(+), 165 deletions(-) diff --git a/docs/guide-ja/runtime-bootstrapping.md b/docs/guide-ja/runtime-bootstrapping.md index 2d70842..9064cb5 100644 --- a/docs/guide-ja/runtime-bootstrapping.md +++ b/docs/guide-ja/runtime-bootstrapping.md @@ -2,11 +2,13 @@ ================ ブートストラップとは、アプリケーションが、入ってくるリクエストの解決と処理を開始する前に、環境を準備する過程を指すものです。 -ブートストラップは二つの場所、すなわち、[エントリ・スクリプト](structure-entry-scripts.md) と [アプリケーション](structure-applications.md)で行われます。 +ブートストラップは二つの場所、すなわち、[エントリ・スクリプト](structure-entry-scripts.md) と +[アプリケーション](structure-applications.md)で行われます。 [エントリ・スクリプト](structure-entry-scripts.md) では、さまざまなライブラリのためのクラス・オートローダが登録されます。 この中には、Composer の `autoload.php` によるオートローダと、Yii の `Yii` クラス・ファイルによるオートローダが含まれます。 -エントリ・スクリプトは、次に、アプリケーションの [構成情報](concept-configurations.md) をロードして、[アプリケーション](structure-applications.md) のインスタンスを作成します。 +エントリ・スクリプトは、次に、アプリケーションの [構成情報](concept-configurations.md) をロードして、 +[アプリケーション](structure-applications.md) のインスタンスを作成します。 アプリケーションのコンストラクタでは、次のようなブートストラップの仕事が行われます。 @@ -17,21 +19,28 @@ 4. [[yii\base\Application::init()|init()]] が呼ばれます。 そして `init()` が [[yii\base\Application::bootstrap()|bootstrap()]] を呼んで、ブートストラップ・コンポーネントを走らせます。 - エクステンション・マニフェスト・ファイル `vendor/yiisoft/extensions.php` をインクルードします。 - - エクステンションによって宣言された [ブートストラップ・コンポーネント](structure-extensions.md#bootstrapping-classes) を作成して実行します。 - - アプリケーションの [bootstrap プロパティ](structure-applications.md#bootstrap) に宣言されている [アプリケーション・コンポーネント](structure-application-components.md) および/または [モジュール](structure-modules.md) を作成して実行します。 + - エクステンションによって宣言された [ブートストラップ・コンポーネント](structure-extensions.md#bootstrapping-classes) + を作成して実行します。 + - アプリケーションの [bootstrap プロパティ](structure-applications.md#bootstrap) に宣言されている + [アプリケーション・コンポーネント](structure-application-components.md) および/または [モジュール](structure-modules.md) + を作成して実行します。 -ブートストラップの仕事は *全て* のリクエストを処理する前に、毎回しなければなりませんので、この過程を軽いものに保って可能な限り最適化することは非常に重要なことです。 +ブートストラップの仕事は *全て* のリクエストを処理する前に、毎回しなければなりませんので、 +この過程を軽いものに保って可能な限り最適化することは非常に重要なことです。 あまりに多くのブートストラップ・コンポーネントを登録しないように努めてください。 ブートストラップ・コンポーネントが必要になるのは、リクエスト処理のライフサイクル全体に関与する必要がある場合だけです。 -例えば、モジュールが追加の URL 解析規則を登録する必要がある場合は、モジュールを [bootstrap プロパティ](structure-applications.md#bootstrap) のリストに挙げなければなりません。 +例えば、モジュールが追加の URL 解析規則を登録する必要がある場合は、モジュールを [bootstrap プロパティ](structure-applications.md#bootstrap) +のリストに挙げなければなりません。 なぜなら、URL 規則を使ってリクエストが解決される前に、新しい URL 規則を有効にしなければならないからです。 -本番運用モードにおいては、[PHP OPCache] や [APC] など、バイトコード・キャッシュを有効にして、PHP ファイルをインクルードして解析するのに要する時間を最小化してください。 +本番運用モードにおいては、[PHP OPCache] や [APC] など、バイトコード・キャッシュを有効にして、 +PHP ファイルをインクルードして解析するのに要する時間を最小化してください。 [PHP OPcache]: http://php.net/manual/ja/book.opcache.php [APC]: http://php.net/manual/ja/book.apc.php 大規模なアプリケーションには、多数の小さな構成情報ファイルに分割された、非常に複雑なアプリケーション [構成情報](concept-configurations.md) を持つものがあります。 そのような場合には、構成情報配列全体をキャッシュするという方法を考慮して下さい。 -エントリ・スクリプトでアプリケーションのインスタンスを作成する前に構成情報をロードするときには、配列全体を直接にキャッシュからロードするのです。 +エントリ・スクリプトでアプリケーションのインスタンスを作成する前に構成情報をロードするときには、 +配列全体を直接にキャッシュからロードするのです。 diff --git a/docs/guide-ja/runtime-handling-errors.md b/docs/guide-ja/runtime-handling-errors.md index eeecb0b..5d39ec1 100644 --- a/docs/guide-ja/runtime-handling-errors.md +++ b/docs/guide-ja/runtime-handling-errors.md @@ -5,7 +5,8 @@ Yii が内蔵している [[yii\web\ErrorHandler|エラー・ハンドラ]] は 具体的には、Yii のエラー・ハンドラはエラー処理をより良くするために、次のことを行います。 * 致命的でない全ての PHP エラー (警告や通知) は捕捉可能な例外に変換されます。 -* 例外および致命的 PHP エラーは、デバッグ・モードでは、詳細なコール・スタック情報とソース・コード行とともに表示されます。 +* 例外および致命的 PHP エラーは、デバッグ・モードでは、 + 詳細なコール・スタック情報とソース・コード行とともに表示されます。 * エラーを表示するために専用の [コントローラ・アクション](structure-controllers.md#actions) を使うことがサポートされています。 * さまざまなエラー・レスポンス形式をサポートしています。 @@ -46,8 +47,10 @@ try { // 実行を継続 ... ``` -リクエストが無効または予期しないものであることをユーザに知らせるエラー・ページを表示したい場合は、単に [[yii\web\NotFoundHttpException]] のような [[yii\web\HttpException|HTTP 例外]] を投げるだけで済ませることが出来ます。 -そうすれば、エラー・ハンドラがレスポンスの HTTP ステータス・コードを正しく設定し、適切なエラー・ビューを使ってエラー・メッセージを表示してくれます。 +リクエストが無効または予期しないものであることをユーザに知らせるエラー・ページを表示したい場合は、 +単に [[yii\web\NotFoundHttpException]] のような [[yii\web\HttpException|HTTP 例外]] を投げるだけで済ませることが出来ます。 +そうすれば、エラー・ハンドラがレスポンスの HTTP ステータス・コードを正しく設定し、 +適切なエラー・ビューを使ってエラー・メッセージを表示してくれます。 ```php use yii\web\NotFoundHttpException; @@ -59,11 +62,13 @@ throw new NotFoundHttpException(); ## エラー表示をカスタマイズする [[yii\web\ErrorHandler|エラー・ハンドラ]] は、定数 `YII_DEBUG` の値に従って、エラー表示を調整します。 -`YII_DEBUG` が `true` である (デバッグ・モードである) 場合は、エラー・ハンドラは、デバッグがより容易になるように、例外とともに、詳細なコール・スタック情報とソース・コード行を表示します。 +`YII_DEBUG` が `true` である (デバッグ・モードである) 場合は、エラー・ハンドラは、デバッグがより容易になるように、 +例外とともに、詳細なコール・スタック情報とソース・コード行を表示します。 そして、`YII_DEBUG` が `false` のときは、アプリケーションに関する公開できない情報の開示を防ぐために、エラー・メッセージだけが表示されます。 > Info: 例外が [[yii\base\UserException]] の子孫である場合は、`YII_DEBUG` の値の如何にかかわらず、コール・スタックは表示されません。 -これは、この種の例外はユーザの誤操作によって引き起こされるものであり、開発者は何も修正する必要がないと考えられるからです。 +これは、この種の例外はユーザの誤操作によって引き起こされるものであり、 +開発者は何も修正する必要がないと考えられるからです。 デフォルトでは、[[yii\web\ErrorHandler|エラー・ハンドラ]] は二つの [ビュー](structure-views.md) を使ってエラーを表示します。 @@ -71,13 +76,15 @@ throw new NotFoundHttpException(); `YII_DEBUG` が `false` の場合、これが表示される唯一のビューとなります。 * `@yii/views/errorHandler/exception.php`: エラーがコール・スタック情報と共に表示されるべき場合に使用されます。 -エラー表示をカスタマイズするために、エラー・ハンドラの [[yii\web\ErrorHandler::errorView|errorView]] および [[yii\web\ErrorHandler::exceptionView|exceptionView]] プロパティを構成して、自分自身のビューを使用することが出来ます。 +エラー表示をカスタマイズするために、エラー・ハンドラの [[yii\web\ErrorHandler::errorView|errorView]] および [[yii\web\ErrorHandler::exceptionView|exceptionView]] プロパティを構成して、 +自分自身のビューを使用することが出来ます。 ### エラー・アクションを使う エラー表示をカスタマイズするためのもっと良い方法は、専用のエラー [アクション](structure-controllers.md) を使うことです。 -そうするためには、まず、`errorHandler` コンポーネントの [[yii\web\ErrorHandler::errorAction|errorAction]] プロパティを次のように構成します。 +そうするためには、まず、`errorHandler` コンポーネントの [[yii\web\ErrorHandler::errorAction|errorAction]] +プロパティを次のように構成します。 ```php return [ @@ -90,7 +97,8 @@ return [ ``` [[yii\web\ErrorHandler::errorAction|errorAction]] プロパティは、アクションへの [ルート](structure-controllers.md#routes) を値として取ります。 -上記の構成は、エラーをコール・スタック情報なしで表示する必要がある場合は、`site/error` アクションが実行されるべきことを記述しています。 +上記の構成は、エラーをコール・スタック情報なしで表示する必要がある場合は、 +`site/error` アクションが実行されるべきことを記述しています。 `site/error` アクションは次のようにして作成することが出来ます。 @@ -133,9 +141,11 @@ public function actionError() * `name`: エラーの名前。 * `message`: エラー・メッセージ。 -* `exception`: 例外オブジェクト。これを通じて、更に有用な情報、例えば、HTTP ステータス・コード、エラー・コード、エラー・コール・スタックなどにアクセスすることが出来ます。 +* `exception`: 例外オブジェクト。これを通じて、更に有用な情報、例えば、HTTP ステータス・コード、エラー・コード、 + エラー・コール・スタックなどにアクセスすることが出来ます。 -> Info: あなたが [ベーシック・プロジェクト・テンプレート](start-installation.md) または [アドバンスト・プロジェクト・テンプレート](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide-ja/README.md) を使っている場合は、エラー・アクションとエラー・ビューは、既にあなたのために定義されています。 +> Info: あなたが [ベーシック・プロジェクト・テンプレート](start-installation.md) または [アドバンスト・プロジェクト・テンプレート](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide-ja/README.md) を使っている場合は、 + エラー・アクションとエラー・ビューは、既にあなたのために定義されています。 > Note: エラー・ハンドラの中でリダイレクトする必要がある場合は、次のようにしてください。 > @@ -148,8 +158,10 @@ public function actionError() ### エラーのレスポンス形式をカスタマイズする エラー・ハンドラは、[レスポンス](runtime-responses.md) 形式の設定に従ってエラーを表示します。 -[[yii\web\Response::format|レスポンス形式]] が `html` である場合は、直前の項で説明したように、エラービューまたは例外ビューを使ってエラーを表示します。 -その他のレスポンス形式の場合は、エラー・ハンドラは例外の配列表現を [[yii\web\Response::data]] プロパティに代入し、次に `data` プロパティをレスポンス形式に応じて様々な形式に変換します。 +[[yii\web\Response::format|レスポンス形式]] が `html` である場合は、直前の項で説明したように、 +エラー・ビューまたは例外ビューを使ってエラーを表示します。 +その他のレスポンス形式の場合は、エラー・ハンドラは例外の配列表現を [[yii\web\Response::data]] プロパティに代入し、 +次に `data` プロパティを様々な形式に変換します。 例えば、レスポンス形式が `json` である場合は、次のようなレスポンスになります。 ``` @@ -167,7 +179,8 @@ Content-Type: application/json; charset=UTF-8 } ``` -エラーのレスポンス形式をカスタマイズするために、アプリケーションの構成情報の中で、`response` コンポーネントの `beforeSend` イベントに反応するハンドラを構成することが出来ます。 +エラーのレスポンス形式をカスタマイズするために、アプリケーションの構成情報の中で、 +`response` コンポーネントの `beforeSend` イベントに反応するハンドラを構成することが出来ます。 ```php return [ diff --git a/docs/guide-ja/runtime-logging.md b/docs/guide-ja/runtime-logging.md index 7c77db4..ebcd341 100644 --- a/docs/guide-ja/runtime-logging.md +++ b/docs/guide-ja/runtime-logging.md @@ -2,7 +2,8 @@ ======== Yii は高度なカスタマイズ性と拡張性を持った強力なロギング・フレームワークを提供しています。 -このフレームワークを使用すると、さまざまな種類のメッセージを記録し、それをフィルタして、ファイル、データベース、メールなど、さまざまなターゲットに収集することが簡単に出来ます。 +このフレームワークを使用すると、さまざまな種類のメッセージを記録し、それをフィルタして、ファイル、データベース、メールなど、 +さまざまなターゲットに収集することが簡単に出来ます。 Yii のロギング・フレームワークを使うためには、下記のステップを踏みます。 @@ -23,7 +24,8 @@ Yii のロギング・フレームワークを使うためには、下記のス * [[Yii::error()]]: 出来るだけ早急に調査すべき致命的なエラーを記録します。 これらのログ記録メソッドは、ログ・メッセージをさまざまな *重大性レベル* と *カテゴリ* で記録するものです。 -これらのメソッドは `function ($message, $category = 'application')` という関数シグニチャを共有しており、`$message` は記録されるログ・メッセージを示し、`$category` はログ・メッセージのカテゴリを示します。 +これらのメソッドは `function ($message, $category = 'application')` という関数シグニチャを共有しており、 +`$message` は記録されるログ・メッセージを示し、`$category` はログ・メッセージのカテゴリを示します。 次のコード・サンプルは、トレース・メッセージをデフォルトのカテゴリである `application` の下に記録するものです。 ```php @@ -37,25 +39,29 @@ Yii::debug('平均収益の計算を開始'); ログ・メッセージを上手に編成しフィルタするために、すべてのログ・メッセージにそれぞれ適切なカテゴリを指定することが推奨されます。 カテゴリに階層的な命名方法を採用すると、[ログ・ターゲット](#log-targets) がカテゴリに基づいてメッセージをフィルタすることが容易になります。 簡単でしかも効果的な命名方法は、カテゴリ名に PHP のマジック定数 `__METHOD__` を使用することです。 -これは、Yii フレームワークのコアコードでも使われている方法です。例えば、 +これは、Yii フレームワークのコアコードでも使われている方法です。 +例えば、 ```php Yii::debug('平均収益の計算を開始', __METHOD__); ``` `__METHOD__` という定数は、それが出現する場所のメソッド名 (完全修飾のクラス名が前置されます) として評価されます。 -例えば、上記のコードが `app\controllers\RevenueController::calculate` というメソッドの中で呼ばれている場合は、`__METHOD__` は `'app\controllers\RevenueController::calculate'` という文字列と同じになります。 +例えば、上記のコードが `app\controllers\RevenueController::calculate` というメソッドの中で呼ばれている場合は、 +`__METHOD__` は `'app\controllers\RevenueController::calculate'` という文字列と同じになります。 > Info: 上記で説明したメソッドは、実際には、[[yii\log\Logger|ロガー・オブジェクト]] の [[yii\log\Logger::log()|log()]] メソッドへのショートカットです。 [[yii\log\Logger|ロガー・オブジェクト]] は `Yii::getLogger()` という式でアクセス可能なシングルトンです。 -ロガー・オブジェクトは、十分な量のメッセージが記録されたとき、または、アプリケーションが終了するときに、[[yii\log\Dispatcher|メッセージ・ディスパッチャ]] を呼んで、登録された [ログ・ターゲット](#log-targets) に記録されたログ・メッセージを送信します。 +ロガー・オブジェクトは、十分な量のメッセージが記録されたとき、または、アプリケーションが終了するときに、 +[[yii\log\Dispatcher|メッセージ・ディスパッチャ]] を呼んで、登録された [ログ・ターゲット](#log-targets) に記録されたログ・メッセージを送信します。 ## ログ・ターゲット ログ・ターゲットは [[yii\log\Target]] クラスまたはその子クラスのインスタンスです。 ログ・ターゲットは、ログ・メッセージを重大性レベルとカテゴリによってフィルタして、何らかの媒体にエクスポートします。 -例えば、[[yii\log\DbTarget|データベース・ターゲット]] は、フィルタされたログ・メッセージをデータベース・テーブルにエクスポートし、[[yii\log\EmailTarget|メール・ターゲット]] は、ログ・メッセージを指定されたメール・アドレスにエクスポートします。 +例えば、[[yii\log\DbTarget|データベース・ターゲット]] は、フィルタされたログ・メッセージをデータベース・テーブルにエクスポートし、 +[[yii\log\EmailTarget|メール・ターゲット]] は、ログ・メッセージを指定されたメール・アドレスにエクスポートします。 一つのアプリケーションの中で複数のログ・ターゲットを登録することが出来ます。 そのためには、次のように、アプリケーションの構成情報の中で、`log` [アプリケーション・コンポーネント](structure-application-components.md) によってログ・ターゲットを構成します。 @@ -64,7 +70,8 @@ Yii::debug('平均収益の計算を開始', __METHOD__); return [ // "log" コンポーネントはブートストラップ時にロードされなければならない 'bootstrap' => ['log'], - + // "log" コンポーネントはタイムスタンプを持つメッセージを処理するので、正しいタイムスタンプを出力するように PHP タイムゾーンを設定 + 'timeZone' => 'America/Los_Angeles', 'components' => [ 'log' => [ 'targets' => [ @@ -89,12 +96,13 @@ return [ ``` > Note: `log` コンポーネントは、ログ・メッセージをターゲットに即座に送付することが出来るように、[ブートストラップ](runtime-bootstrapping.md) 時にロードされなければなりません。 -この理由により、上記の例で示されているように、`bootstrap` の配列に `log` をリストアップしています。 +上記の例で `bootstrap` の配列に `log` がリストアップされているのは、そのためです。 上記のコードでは、二つのログ・ターゲットが [[yii\log\Dispatcher::targets]] プロパティに登録されています。 * 最初のターゲットは、エラーと警告のメッセージを選択して、データベース・テーブルに保存します。 -* 第二のターゲットは、名前が `yii\db\` で始まるカテゴリのエラー・メッセージを選んで、`admin@example.com` と `developer@example.com` の両方にメールで送信します。 +* 第二のターゲットは、名前が `yii\db\` で始まるカテゴリのエラー・メッセージを選んで、`admin@example.com` と `developer@example.com` + の両方にメールで送信します。 Yii は下記のログ・ターゲットをあらかじめ内蔵しています。 その構成方法と使用方法を学ぶためには、これらのクラスの API ドキュメントを参照してください。 @@ -109,7 +117,8 @@ Yii は下記のログ・ターゲットをあらかじめ内蔵しています ### メッセージのフィルタリング -全てのログ・ターゲットについて、それぞれ、[[yii\log\Target::levels|levels]] と [[yii\log\Target::categories|categories]] のプロパティを構成して、ターゲットが処理すべきメッセージの重要性レベルとカテゴリを指定することが出来ます。 +全てのログ・ターゲットについて、それぞれ、[[yii\log\Target::levels|levels]] と [[yii\log\Target::categories|categories]] のプロパティを構成して、 +ターゲットが処理すべきメッセージの重要性レベルとカテゴリを指定することが出来ます。 [[yii\log\Target::levels|levels]] プロパティは、次のレベルの一つまたは複数からなる配列を値として取ります。 @@ -120,20 +129,25 @@ Yii は下記のログ・ターゲットをあらかじめ内蔵しています * `profile`: [[Yii::beginProfile()]] と [[Yii::endProfile()]] によって記録されたメッセージに対応。 これについては、[プロファイリング](#performance-profiling) の項で詳細に説明します。 -[[yii\log\Target::levels|levels]] プロパティを指定しない場合は、ターゲットが *全ての* 重大性レベルのメッセージを処理することを意味します。 +[[yii\log\Target::levels|levels]] プロパティを指定しない場合は、 +ターゲットが *全ての* 重大性レベルのメッセージを処理することを意味します。 [[yii\log\Target::categories|categories]] プロパティは、メッセージ・カテゴリの名前またはパターンからなる配列を値として取ります。 ターゲットは、カテゴリの名前がこの配列にあるか、または配列にあるパターンに合致する場合にだけ、メッセージを処理します。 -カテゴリパターンというのは、最後にアスタリスク `*` を持つカテゴリ名接頭辞です。カテゴリ名は、パターンと同じ接頭辞で始まる場合に、カテゴリ・パターンに合致します。 +カテゴリ・パターンというのは、最後にアスタリスク `*` を持つカテゴリ名接頭辞です。 +カテゴリ名は、パターンと同じ接頭辞で始まる場合に、カテゴリ・パターンに合致します。 例えば、`yii\db\Command::execute` と `yii\db\Command::query` は、[[yii\db\Command]] クラスで記録されるログ・メッセージのためのカテゴリ名です。 そして、両者は共に `yii\db\*` というパターンに合致します。 -[[yii\log\Target::categories|categories]] プロパティを指定しない場合は、ターゲットが *全ての* カテゴリのメッセージを処理することを意味します。 +[[yii\log\Target::categories|categories]] プロパティを指定しない場合は、 +ターゲットが *全ての* カテゴリのメッセージを処理することを意味します。 -カテゴリを [[yii\log\Target::categories|categories]] プロパティでホワイト・リストとして登録する以外に、一定のカテゴリを [[yii\log\Target::except|except]] プロパティによってブラック・リストとして登録することも可能です。 +カテゴリを [[yii\log\Target::categories|categories]] プロパティでホワイト・リストとして登録する以外に、 +一定のカテゴリを [[yii\log\Target::except|except]] プロパティによってブラック・リストとして登録することも可能です。 カテゴリの名前がこの配列にあるか、または配列にあるパターンに合致する場合は、メッセージはターゲットによって処理されません。 -次のターゲットの構成は、ターゲットが、`yii\db\*` または `yii\web\HttpException:*` に合致するカテゴリ名を持つエラーおよび警告のメッセージだけを処理すべきこと、ただし、`yii\web\HttpException:404` は除外すべきことを指定するものです。 +次のターゲットの構成は、ターゲットが、`yii\db\*` または `yii\web\HttpException:*` に合致するカテゴリ名を持つエラーおよび警告のメッセージだけを処理すべきこと、 +ただし、`yii\web\HttpException:404` は除外すべきことを指定するものです。 ```php [ @@ -149,14 +163,16 @@ Yii は下記のログ・ターゲットをあらかじめ内蔵しています ] ``` -> Info: HTTP 例外が [エラー・ハンドラ](runtime-handling-errors.md) によって捕捉されたときは、`yii\web\HttpException:ErrorCode` という書式のカテゴリ名でエラー・メッセージがログに記録されます。 +> Info: HTTP 例外が [エラー・ハンドラ](runtime-handling-errors.md) によって捕捉されたときは、 + `yii\web\HttpException:ErrorCode` という書式のカテゴリ名でエラー・メッセージがログに記録されます。 例えば、[[yii\web\NotFoundHttpException]] は、`yii\web\HttpException:404` というカテゴリのエラー・メッセージを発生させます。 ### メッセージの書式設定 ログ・ターゲットはフィルタされたログ・メッセージを一定の書式でエクスポートします。 -例えば、[[yii\log\FileTarget]] クラスのログ・ターゲットをインストールした場合は、`runtime/log/app.log` ファイルに、下記と同様なログ・メッセージが書き込まれます。 +例えば、[[yii\log\FileTarget]] クラスのログ・ターゲットをインストールした場合は、 +`runtime/log/app.log` ファイルに、下記と同様なログ・メッセージが書き込まれます。 ``` 2014-10-04 18:10:15 [::1][][-][trace][yii\base\Module::getModule] Loading module: debug @@ -170,8 +186,7 @@ Yii は下記のログ・ターゲットをあらかじめ内蔵しています この書式は、[[yii\log\Target::prefix]] プロパティを構成することでカスタマイズすることが出来ます。 [[yii\log\Target::prefix]] プロパティは、カスタマイズされたメッセージ前置情報を返す PHP コーラブルを値として取ります。 -例えば、次のコードは、ログ・ターゲットが全てのログ・メッセージの前にカレント・ユーザの ID を置くようにさせるものです -(IP アドレスとセッション ID はプライバシー上の理由から削除されています)。 +例えば、次のコードは、ログ・ターゲットが全てのログ・メッセージの前にカレント・ユーザの ID を置くようにさせるものです(IP アドレスとセッション ID はプライバシー上の理由から削除されています)。 ```php [ @@ -186,7 +201,8 @@ Yii は下記のログ・ターゲットをあらかじめ内蔵しています メッセージ前置情報以外にも、ログ・ターゲットは、一群のログ・メッセージごとに一定のコンテキスト情報を追加します。 デフォルトでは、その情報には、次のグローバル PHP 変数、すなわち、`$_GET`、`$_POST`、`$_FILES`、`$_COOKIE`、`$_SESSION` および `$_SERVER` の値が含まれます。 -ログ・ターゲットに含ませたいグローバル変数の名前を [[yii\log\Target::logVars]] プロパティに設定することによって、この動作を調整することが出来ます。 +ログ・ターゲットに含ませたいグローバル変数の名前を [[yii\log\Target::logVars]] プロパティに設定することによって、 +この動作を調整することが出来ます。 例えば、次のログ・ターゲットの構成は、`$_SERVER` の値だけをログ・メッセージに追加するように指定するものです。 ```php @@ -197,7 +213,8 @@ Yii は下記のログ・ターゲットをあらかじめ内蔵しています ``` `logVars` を空の配列として構成して、コンテキスト情報をまったく含ませないようにすることも出来ます。 -あるいは、また、コンテキスト情報の提供方法を自分で実装したい場合は、[[yii\log\Target::getContextMessage()]] メソッドをオーバーライドすることも出来ます。 +あるいは、また、コンテキスト情報の提供方法を自分で実装したい場合は、 +[[yii\log\Target::getContextMessage()]] メソッドをオーバーライドすることも出来ます。 ### メッセージのトレース・レベル @@ -218,15 +235,19 @@ return [ ``` 上記のアプリケーションの構成は、[[yii\log\Dispatcher::traceLevel|traceLevel]] を `YII_DEBUG` が on のときは 3、`YII_DEBUG` が off のときは 0 に設定します。 -これは、`YII_DEBUG` が on のときは、各ログ・メッセージに対して、ログ・メッセージが記録されたときのコール・スタックを最大 3 レベルまで追加し、`YII_DEBUG` が 0 のときはコール・スタックを含めない、ということを意味します。 +これは、`YII_DEBUG` が on のときは、各ログ・メッセージに対して、ログ・メッセージが記録されたときのコール・スタックを最大 3 レベルまで追加し、 +`YII_DEBUG` が 0 のときはコール・スタックを含めない、 +ということを意味します。 -> Info: コール・スタック情報の取得は軽微な処理ではありません。従って、この機能は開発時またはアプリケーションをデバッグするときに限って使用するべきです。 +> Info: コール・スタック情報の取得は軽微な処理ではありません。 + 従って、この機能は開発時またはアプリケーションをデバッグするときに限って使用するべきです。 ### メッセージの吐き出しとエクスポート 既に述べたように、ログ・メッセージは [[yii\log\Logger|ロガー・オブジェクト]] によって配列の中に保持されます。 -この配列のメモリ消費を制限するために、この配列に一定数のログ・メッセージが蓄積されるたびに、ロガーは記録されたメッセージを [ログ・ターゲット](#log-targets) に吐き出します。 +この配列のメモリ消費を制限するために、この配列に一定数のログ・メッセージが蓄積されるたびに、 +ロガーは記録されたメッセージを [ログ・ターゲット](#log-targets) に吐き出します。 この数は、`log` コンポーネントの [[yii\log\Dispatcher::flushInterval|flushInterval]] プロパティを構成することによってカスタマイズすることが出来ます。 @@ -246,7 +267,8 @@ return [ [[yii\log\Logger|ロガー・オブジェクト]] が [ログ・ターゲット](#log-targets) にログ・メッセージを吐き出しても、ログ・メッセージはただちにはエクスポートされません。 そうではなく、ログ・ターゲットが一定数のフィルタされたメッセージを蓄積して初めて、メッセージのエクスポートが発生します。 -この数は、下記のように、個々の [ログ・ターゲット](#log-targets) の [[yii\log\Target::exportInterval|exportInterval]] プロパティを構成することによってカスタマイズすることが出来ます。 +この数は、下記のように、個々の [ログ・ターゲット](#log-targets) の [[yii\log\Target::exportInterval|exportInterval]] +プロパティを構成することによってカスタマイズすることが出来ます。 ```php [ @@ -255,9 +277,11 @@ return [ ] ``` -デフォルトの状態では、吐き出しとエクスポートの間隔の設定のために、`Yii::debug()` やその他のログ記録メソッドを呼んでも、ただちには、ログ・メッセージはログ・ターゲットに出現しません。 +デフォルトの状態では、吐き出しとエクスポートの間隔の設定のために、`Yii::debug()` やその他のログ記録メソッドを呼んでも、 +ただちには、ログ・メッセージはログ・ターゲットに出現しません。 このことは、長時間にわたって走るコンソール・アプリケーションでは、問題になる場合もあります。 -各ログ・メッセージがただちにログ・ターゲットに出現するようにするためには、下記のように、[[yii\log\Dispatcher::flushInterval|flushInterval]] と [[yii\log\Target::exportInterval|exportInterval]] の両方を 1 に設定しなければなりません。 +各ログ・メッセージがただちにログ・ターゲットに出現するようにするためには、下記のように、[[yii\log\Dispatcher::flushInterval|flushInterval]] と +[[yii\log\Target::exportInterval|exportInterval]] の両方を 1 に設定しなければなりません。 ```php return [ @@ -309,21 +333,29 @@ return [ ]; ``` +バージョン 2.0.13 以降は、[[yii\log\Target::enabled|enabled]] を設定するのに、 +ログ・ターゲットを有効にすべきか否かの動的な条件を定義するコーラブルを指定することが可能です。 +[[yii\log\Target::setEnabled()]] のドキュメントに一例がありますので参照して下さい。 ### 新しいターゲットを作る -新しいログ・ターゲットを作ることは非常に簡単です。 +新しいログ・ターゲット・クラスを作ることは非常に簡単です。 必要なことは、主として、[[yii\log\Target::messages]] 配列の中身を指定された媒体に送出する [[yii\log\Target::export()]] メソッドを実装することです。 各メッセージに書式を設定するためには、[[yii\log\Target::formatMessage()]] を呼ぶことが出来ます。 詳細については、Yii リリースに含まれているログ・ターゲット・クラスのどれか一つを参照してください。 +> Tip: あなた自身のロガーを書く代りに、[PSR ログ・ターゲット・エクステンション](https://github.com/samdark/yii2-psr-log-target) によって、 + [Monolog](https://github.com/Seldaek/monolog) のような + PSR-3 互換ロガーのどれかを使ってみるのも良いでしょう。 ## パフォーマンス・プロファイリング -パフォーマンス・プロファイリングは、特定のコード・ブロックに要した時間を測定してパフォーマンスのボトルネックになっている所を見つけ出すために使われる、特殊なタイプのメッセージ・ロギングです。 +パフォーマンス・プロファイリングは、特定のコード・ブロックに要した時間を測定してパフォーマンスのボトルネックになっている所を見つけ出すために使われる、 +特殊なタイプのメッセージ・ロギングです。 例えば、[[yii\db\Command]] クラスは、各 DB クエリに要した時間を知るために、パフォーマンス・プロファイリングを使用しています。 -パフォーマンス・プロファイリングを使用するためには、最初に、プロファイリングが必要なコード・ブロックを特定します。そして、各コード・ブロックを次のように囲みます。 +パフォーマンス・プロファイリングを使用するためには、最初に、プロファイリングが必要なコード・ブロックを特定します。 +そして、各コード・ブロックを次のように囲みます。 ```php \Yii::beginProfile('myBenchmark'); @@ -351,7 +383,8 @@ return [ \Yii::endProfile('block1'); ``` -`\Yii::endProfile('block1')` を忘れたり、`\Yii::endProfile('block1')` と `\Yii::endProfile('block2')` の順序を入れ替えたりすると、パフォーマンス・プロファイリングは機能しません。 +`\Yii::endProfile('block1')` を忘れたり、`\Yii::endProfile('block1')` と `\Yii::endProfile('block2')` の順序を入れ替えたりすると、 +パフォーマンス・プロファイリングは機能しません。 プロファイルされるコード・ブロックの全てについて、おのおの、重大性レベルが `profile` であるログ・メッセージが記録されます。 そのようなメッセージを集めてエクスポートする [ログ・ターゲット](#log-targets) を構成してください。 diff --git a/docs/guide-ja/runtime-overview.md b/docs/guide-ja/runtime-overview.md index e35d946..da1dba4 100644 --- a/docs/guide-ja/runtime-overview.md +++ b/docs/guide-ja/runtime-overview.md @@ -4,8 +4,10 @@ Yii のアプリケーションがリクエストを処理するときは、毎回、同じようなワーク・フローになります。 1. ユーザが [エントリ・スクリプト](structure-entry-scripts.md) `web/index.php` にリクエストをします。 -2. エントリ・スクリプトは、アプリケーションの [構成情報](concept-configurations.md) をロードして、リクエストを処理するための [アプリケーション](structure-applications.md) のインスタンスを作成します。 -3. アプリケーションは、[リクエスト](runtime-requests.md) アプリケーション・コンポーネントの助けを借りて、リクエストされた [ルート](runtime-routing.md) を解決します。 +2. エントリ・スクリプトは、アプリケーションの [構成情報](concept-configurations.md) をロードして、 + リクエストを処理するための [アプリケーション](structure-applications.md) のインスタンスを作成します。 +3. アプリケーションは、[リクエスト](runtime-requests.md) アプリケーション・コンポーネントの助けを借りて、 + リクエストされた [ルート](runtime-routing.md) を解決します。 4. アプリケーションはリクエストを処理するための [コントローラ](structure-controllers.md) のインスタンスを作成します。 5. コントローラは [アクション](structure-controllers.md) のインスタンスを作成して、アクションのためのフィルタを実行します。 6. [フィルタ](structure-filters.md)のどれかが失敗すると、アクションはキャンセルされます。 diff --git a/docs/guide-ja/runtime-requests.md b/docs/guide-ja/runtime-requests.md index 2658b7f..a74830d 100644 --- a/docs/guide-ja/runtime-requests.md +++ b/docs/guide-ja/runtime-requests.md @@ -2,7 +2,8 @@ ========== アプリケーションに対するリクエストは、リクエストのパラメータ、HTTP ヘッダ、クッキーなどの情報を提供する [[yii\web\Request]] オブジェクトの形で表されます。 -与えられたリクエストに対応するリクエスト・オブジェクトには、デフォルトでは [[yii\web\Request]] のインスタンスである `request` [アプリケーション・コンポーネント](structure-application-components.md) を通じてアクセスすることが出来ます。 +与えられたリクエストに対応するリクエスト・オブジェクトには、デフォルトでは [[yii\web\Request]] のインスタンスである `request` [アプリケーション・コンポーネント](structure-application-components.md) +を通じてアクセスすることが出来ます。 このセクションでは、アプリケーションの中でこのコンポーネントをどのように利用できるかを説明します。 @@ -33,7 +34,8 @@ $name = $request->post('name', ''); // $name = isset($_POST['name']) ? $_POST['name'] : ''; と同等 ``` -> Info: 直接に `$_GET` と `$_POST` にアクセスしてリクエストのパラメータを読み出す代りに、上記に示されているように、`request` コンポーネントを通じてそれらを取得することが推奨されます。 +> Info: 直接に `$_GET` と `$_POST` にアクセスしてリクエストのパラメータを読み出す代りに、上記に示されているように、 +`request` コンポーネントを通じてそれらを取得することが推奨されます。 このようにすると、ダミーのリクエスト・データを持った模擬リクエスト・コンポーネントを作ることが出来るため、テストを書くことがより容易になります。 [RESTful API](rest-quick-start.md) を実装するときは、PUT、PATCH またはその他の [リクエスト・メソッド](#request-methods) によって送信されたパラメータを読み出さなければならないことがよくあります。 @@ -74,15 +76,18 @@ if ($request->isPut) { /* リクエスト・メソッドは PUT */ } `request` コンポーネントは現在リクエストされている URL を調べるための方法を数多く提供しています。 -リクエストされた URL が `http://example.com/admin/index.php/product?id=100` であると仮定したとき、次にまとめたように、この URL のさまざまな部分を取得することが出来ます。 +リクエストされた URL が `http://example.com/admin/index.php/product?id=100` であると仮定したとき、 +次にまとめたように、この URL のさまざまな部分を取得することが出来ます。 * [[yii\web\Request::url|url]]: `/admin/index.php/product?id=100` を返します。ホスト情報の部分を省略した URL です。 * [[yii\web\Request::absoluteUrl|absoluteUrl]]: `http://example.com/admin/index.php/product?id=100` を返します。 ホスト情報の部分を含んだ URL です。 * [[yii\web\Request::hostInfo|hostInfo]]: `http://example.com` を返します。URL のホスト情報の部分です。 -* [[yii\web\Request::pathInfo|pathInfo]]: `/product` を返します。エントリ・スクリプトの後、疑問符 (クエリ文字列) の前の部分です。 +* [[yii\web\Request::pathInfo|pathInfo]]: `/product` を返します。 + エントリ・スクリプトの後、疑問符 (クエリ文字列) の前の部分です。 * [[yii\web\Request::queryString|queryString]]: `id=100` を返します。疑問符の後の部分です。 -* [[yii\web\Request::baseUrl|baseUrl]]: `/admin` を返します。ホスト情報の後、かつ、エントリ・スクリプトの前の部分です。 +* [[yii\web\Request::baseUrl|baseUrl]]: `/admin` を返します。ホスト情報の後、かつ、 + エントリ・スクリプトの前の部分です。 * [[yii\web\Request::scriptUrl|scriptUrl]]: `/admin/index.php` を返します。パス情報とクエリ文字列を省略した URL です。 * [[yii\web\Request::serverName|serverName]]: `example.com` を返します。URL の中のホスト名です。 * [[yii\web\Request::serverPort|serverPort]]: 80 を返します。ウェブ・サーバによって使用されているポートです。 @@ -90,7 +95,8 @@ if ($request->isPut) { /* リクエスト・メソッドは PUT */ } ## HTTP ヘッダ -[[yii\web\Request::headers]] プロパティによって返される [[yii\web\HeaderCollection|header コレクション]] を通じて、HTTP ヘッダ情報を取得することが出来ます。例えば、 +[[yii\web\Request::headers]] プロパティによって返される [[yii\web\HeaderCollection|header コレクション]] を通じて、 +HTTP ヘッダ情報を取得することが出来ます。例えば、 ```php // $headers は yii\web\HeaderCollection のオブジェクト @@ -102,26 +108,31 @@ $accept = $headers->get('Accept'); if ($headers->has('User-Agent')) { /* User-Agent ヘッダが在る */ } ``` -`request` コンポーネントは、よく使用されるいくつかのヘッダにすばやくアクセスする方法を提供しています。 -その中には下記のものが含まれます。 +`request` コンポーネントは、よく使用されるいくつかのヘッダにすばやくアクセスする方法を提供しています。その中には下記のものが含まれます。 * [[yii\web\Request::userAgent|userAgent]]: `User-Agent` ヘッダの値を返します。 -* [[yii\web\Request::contentType|contentType]]: リクエスト・ボディのデータの MIME タイプを示す `Content-Type` ヘッダの値を返します。 +* [[yii\web\Request::contentType|contentType]]: リクエスト・ボディのデータの MIME タイプを示す + `Content-Type` ヘッダの値を返します。 * [[yii\web\Request::acceptableContentTypes|acceptableContentTypes]]: ユーザが受け入れ可能なコンテントの MIME タイプを返します。 -返されるタイプは品質スコアによって順序付けられます。最もスコアの高いタイプが最初に返されます。 + 返されるタイプは品質スコアによって順序付けられます。最もスコアの高いタイプが最初に返されます。 * [[yii\web\Request::acceptableLanguages|acceptableLanguages]]: ユーザが受け入れ可能な言語を返します。 -返される言語は優先レベルによって順序付けられます。最初の要素が最も優先度の高い言語を表します。 + 返される言語は優先レベルによって順序付けられます。最初の要素が最も優先度の高い言語を表します。 -あなたのアプリケーションが複数の言語をサポートしており、エンド・ユーザが最も優先する言語でページを表示したいと思う場合は、言語ネゴシエーション・メソッド [[yii\web\Request::getPreferredLanguage()]] を使うことが出来ます。 -このメソッドはアプリケーションによってサポートされている言語のリストを引数として取り、 [[yii\web\Request::acceptableLanguages|acceptableLanguages]] と比較して、最も適切な言語を返します。 +あなたのアプリケーションが複数の言語をサポートしており、エンド・ユーザが最も優先する言語でページを表示したいと思う場合は、 +言語ネゴシエーション・メソッド [[yii\web\Request::getPreferredLanguage()]] を使うことが出来ます。 +このメソッドはアプリケーションによってサポートされている言語のリストを引数として取り、 +[[yii\web\Request::acceptableLanguages|acceptableLanguages]] と比較して、最も適切な言語を返します。 -> Tip: [[yii\filters\ContentNegotiator|ContentNegotiator]] フィルタを使用して、レスポンスにおいてどのコンテント・タイプと言語を使うべきかを動的に決定することも出来ます。 -このフィルタは、上記で説明したプロパティとメソッドの上に、コンテント・ネゴシエーションを実装しています。 +> Tip: [[yii\filters\ContentNegotiator|ContentNegotiator]] フィルタを使用して、 + レスポンスにおいてどのコンテント・タイプと言語を使うべきかを動的に決定することも出来ます。 + このフィルタは、上記で説明したプロパティとメソッドの上に、コンテント・ネゴシエーションを実装しています。 ## クライアント情報 -クライアント・マシンのホスト名と IP アドレスを、それぞれ、[[yii\web\Request::userHost|userHost]] と [[yii\web\Request::userIP|userIP]] によって取得することが出来ます。例えば、 +クライアント・マシンのホスト名と IP アドレスを、 +それぞれ、[[yii\web\Request::userHost|userHost]] と [[yii\web\Request::userIP|userIP]] によって取得することが出来ます。 +例えば、 ```php $userHost = Yii::$app->request->userHost; @@ -133,10 +144,12 @@ $userIP = Yii::$app->request->userIP; 前のセクションでホストや IP アドレスなどのユーザ情報を取得する方法を説明しました。 単一のウェブ・サーバがウェブ・サイトをホストしている通常の環境では、このままで動作します。 しかし、Yii アプリケーションがリバース・プロキシの背後で動作している場合は、この情報を読み出すために構成情報を追加する必要があります。 -なぜなら、その場合、直接のクライアントはプロキシになっており、ユーザの IP アドレスはプロキシがセットするヘッダによって Yii アプリケーションに渡されるからです。 +なぜなら、その場合、直接のクライアントはプロキシになっており、ユーザの IP アドレスはプロキシがセットするヘッダによって +Yii アプリケーションに渡されるからです。 明示的に信頼したプロキシ以外は、プロキシによって提供されるヘッダを盲目的に信頼してはいけません。 -2.0.13 以降、Yii は `request` コンポーネントの以下のプロパティによって、信頼できるプロキシの情報を構成することが出来るようになっています。 +2.0.13 以降、Yii は `request` コンポーネントの以下のプロパティによって、 +信頼できるプロキシの情報を構成することが出来るようになっています。 [[yii\web\Request::trustedHosts|trustedHosts]]、 [[yii\web\Request::secureHeaders|secureHeaders]]、 [[yii\web\Request::ipHeaders|ipHeaders]] および @@ -154,11 +167,9 @@ $userIP = Yii::$app->request->userIP; ], ``` -プロキシは、デフォルトでは、IP を `X-Forwarded-For` ヘッダで送信し、 -プロトコル (`http` または `https`) を `X-Forwarded-Proto` で送信します。 +プロキシは、デフォルトでは、IP を `X-Forwarded-For` ヘッダで送信し、プロトコル (`http` または `https`) を `X-Forwarded-Proto` で送信します。 -あなたのプロキシが異なるヘッダを使っている場合は、request の構成情報を使って調整することが出来ます。 -例えば、 +あなたのプロキシが異なるヘッダを使っている場合は、request の構成情報を使って調整することが出来ます。例えば、 ```php 'request' => [ diff --git a/docs/guide-ja/runtime-responses.md b/docs/guide-ja/runtime-responses.md index 6b5112c..cbbc10e 100644 --- a/docs/guide-ja/runtime-responses.md +++ b/docs/guide-ja/runtime-responses.md @@ -5,7 +5,8 @@ レスポンス・オブジェクトは、HTTP ステータス・コード、HTTP ヘッダ、HTTP ボディなどの情報を含みます。 ウェブ・アプリケーション開発の最終的な目的は、本質的には、さまざまなリクエストに対してそのようなレスポンス・オブジェクトを作成することにあります。 -ほとんどの場合は、主として、デフォルトでは [[yii\web\Response]] のインスタンスである `response` [アプリケーション・コンポーネント](structure-application-components.md) を使用すべきです。 +ほとんどの場合は、主として、デフォルトでは [[yii\web\Response]] のインスタンスである `response` +[アプリケーション・コンポーネント](structure-application-components.md) を使用すべきです。 しかしながら、Yii は、以下で説明するように、あなた自身のレスポンス・オブジェクトを作成してエンド・ユーザに送信することも許容しています。 このセクションでは、レスポンスを構成してエンド・ユーザに送信する方法を説明します。 @@ -14,7 +15,8 @@ ## ステータス・コード レスポンスを作成するときに最初にすることの一つは、リクエストが成功裡に処理されたかどうかを記述することです。 -そのためには、[[yii\web\Response::statusCode]] プロパティに有効な [HTTP ステータス・コード](https://tools.ietf.org/html/rfc2616#section-10) の一つを設定します。 +そのためには、[[yii\web\Response::statusCode]] プロパティに有効な +[HTTP ステータス・コード](https://tools.ietf.org/html/rfc2616#section-10) の一つを設定します。 例えば、下記のように、リクエストの処理が成功したことを示すために、ステータス・コードを 200 に設定します。 ```php @@ -46,8 +48,7 @@ throw new \yii\web\NotFoundHttpException; * [[yii\web\UnsupportedMediaTypeHttpException]]: ステータス・コード 415 投げたい例外が上記のリストに無い場合は、[[yii\web\HttpException]] から拡張したものを作成することが出来ます。 -あるいは、ステータス・コードを指定して [[yii\web\HttpException]] を直接に投げることも出来ます。 -例えば、 +あるいは、ステータス・コードを指定して [[yii\web\HttpException]] を直接に投げることも出来ます。例えば、 ```php throw new \yii\web\HttpException(402); @@ -97,8 +98,7 @@ $response->format = \yii\web\Response::FORMAT_JSON; $response->data = ['message' => 'hello world']; ``` -Yii は下記の形式を初めからサポートしています。 -それぞれ、[[yii\web\ResponseFormatterInterface|フォーマッタ]] クラスとして実装されています。 +Yii は下記の形式を初めからサポートしています。それぞれ、[[yii\web\ResponseFormatterInterface|フォーマッタ]] クラスとして実装されています。 [[yii\web\Response::formatters]] プロパティを構成することで、これらのフォーマッタをカスタマイズしたり、新しいフォーマッタを追加したりすることが出来ます。 * [[yii\web\Response::FORMAT_HTML|HTML]]: [[yii\web\HtmlResponseFormatter]] によって実装 @@ -152,7 +152,8 @@ public function actionInfo() } ``` -> Note: 自分自身のレスポンス・オブジェクトを作成しようとする場合は、アプリケーションの構成情報で `response` コンポーネントのために設定した構成情報を利用することは出来ません。 +> Note: 自分自身のレスポンス・オブジェクトを作成しようとする場合は、アプリケーションの構成情報で + `response` コンポーネントのために設定した構成情報を利用することは出来ません。 しかし、 [依存の注入](concept-di-container.md) を使えば、 共通の構成情報をあなたの新しいレスポンス・オブジェクトに適用することが出来ます。 @@ -163,8 +164,7 @@ public function actionInfo() [[yii\web\Response::redirect()]] メソッドを呼ぶことによって、ユーザのブラウザをある URL にリダイレクトすることが出来ます。 このメソッドは与えられた URL を持つ適切な `Location` ヘッダを設定して、レスポンス・オブジェクトそのものを返します。 -アクション・メソッドの中では、そのショートカット版である [[yii\web\Controller::redirect()]] を呼ぶことが出来ます。 -例えば、 +アクション・メソッドの中では、そのショートカット版である [[yii\web\Controller::redirect()]] を呼ぶことが出来ます。例えば、 ```php public function actionOld() @@ -176,7 +176,8 @@ public function actionOld() 上記のコードでは、アクション・メソッドが `redirect()` メソッドの結果を返しています。 前に説明したように、アクション・メソッドによって返されるレスポンス・オブジェクトが、エンド・ユーザに送信されるレスポンスとして使用されることになります。 -アクション・メソッド以外の場所では、[[yii\web\Response::redirect()]] を直接に呼び出し、メソッド・チェーンで [[yii\web\Response::send()]] メソッドを呼んで、レスポンスに余計なコンテントが追加されないことを保証しなければなりません。 +アクション・メソッド以外の場所では、[[yii\web\Response::redirect()]] を直接に呼び出し、 +メソッド・チェーンで [[yii\web\Response::send()]] メソッドを呼んで、レスポンスに余計なコンテントが追加されないことを保証しなければなりません。 ```php \Yii::$app->response->redirect('http://example.com/new', 301)->send(); @@ -188,14 +189,14 @@ public function actionOld() 現在のリクエストが AJAX リクエストである場合は、`Location` ヘッダを送っても自動的にブラウザをリダイレクトすることにはなりません。 この問題を解決するために、[[yii\web\Response::redirect()]] メソッドは `X-Redirect` ヘッダにリダイレクト先 URL を値としてセットします。 -そして、クライアント・サイドで、このヘッダの値を読み、それに応じてブラウザをリダイレクトする JavaScript を書くことが出来ます。 +そして、クライアント・サイドで、このヘッダの値を読み、 +それに応じてブラウザをリダイレクトする JavaScript を書くことが出来ます。 > Info: Yii には `yii.js` という JavaScript ファイルが付属しています。 これは、よく使われる一連の JavaScript 機能を提供するもので、その中には `X-Redirect` ヘッダに基づくブラウザのリダイレクトも含まれています。 従って、あなたが ([[yii\web\YiiAsset]] アセット・バンドルを登録して) この JavaScript ファイルを使うつもりなら、AJAX のリダイレクトをサポートするためには、何も書く必要がなくなります。 `yii.js` に関する更なる情報は [クライアント・スクリプトのセクション](output-client-scripts.md#yii.js) にあります。 - ## ファイルを送信する ブラウザのリダイレクトと同じように、ファイルの送信という機能も特定の HTTP ヘッダに依存しています。 @@ -216,7 +217,8 @@ public function actionDownload() } ``` -ファイル送信メソッドをアクション・メソッド以外の場所で呼ぶ場合は、その後で [[yii\web\Response::send()]] メソッドも呼んで、レスポンスに余計なコンテントが追加されないことを保証しなければなりません。 +ファイル送信メソッドをアクション・メソッド以外の場所で呼ぶ場合は、その後で [[yii\web\Response::send()]] メソッドも呼んで、 +レスポンスに余計なコンテントが追加されないことを保証しなければなりません。 ```php \Yii::$app->response->sendFile('path/to/file.txt')->send(); diff --git a/docs/guide-ja/runtime-routing.md b/docs/guide-ja/runtime-routing.md index 3b21f83..67e8776 100644 --- a/docs/guide-ja/runtime-routing.md +++ b/docs/guide-ja/runtime-routing.md @@ -9,10 +9,14 @@ Yii のアプリケーションがリクエストされた URL の処理を開 これは、与えられたルートとそれに結び付けられたクエリ・パラメータから URL を生成するものです。 生成された URL が後でリクエストされたときには、ルーティングのプロセスがその URL を解決して元のルートとクエリ・パラメータに戻すことが出来ます。 -ルーティングと URL 生成について主たる役割を果たすのが `urlManager` [アプリケーション・コンポーネント](structure-application-components.md) として登録されている [[yii\web\UrlManager|URL マネージャ]] です。 -[[yii\web\UrlManager|URL マネージャ]] は、入ってくるリクエストをルートとそれに結び付けられたクエリ・パラメータとして解析するための [[yii\web\UrlManager::parseRequest()|parseRequest()]] メソッドと、与えられたルートとそれに結び付けられたクエリ・パラメータから URL を生成するための [[yii\web\UrlManager::createUrl()|createUrl()]] メソッドを提供します。 - -アプリケーション構成情報の `urlManager` コンポーネントを構成することによって、既存のアプリケーション・コードを修正することなく、任意の URL 形式をアプリケーションに認識させることが出来ます。 +ルーティングと URL 生成について主たる役割を果たすのが `urlManager` [アプリケーション・コンポーネント](structure-application-components.md) として登録されている +[[yii\web\UrlManager|URL マネージャ]] です。 +[[yii\web\UrlManager|URL マネージャ]] は、入ってくるリクエストをルートとそれに結び付けられたクエリ・パラメータとして解析するための [[yii\web\UrlManager::parseRequest()|parseRequest()]] メソッドと、 +与えられたルートとそれに結び付けられたクエリ・パラメータから URL を生成するための [[yii\web\UrlManager::createUrl()|createUrl()]] +メソッドを提供します。 + +アプリケーション構成情報の `urlManager` コンポーネントを構成することによって、既存のアプリケーション・コードを修正することなく、 +任意の URL 形式をアプリケーションに認識させることが出来ます。 例えば、`post/view` アクションのための URL を生成するためには、次のコードを使うことが出来ます。 ```php @@ -22,7 +26,7 @@ use yii\helpers\Url; $url = Url::to(['post/view', 'id' => 100]); ``` -このコードによって生成される URL は、`urlManager` の構成に応じて、下記のどれか (またはその他) になります。 +このコードによって生成される URL は、`urlManager` の構成に応じて、下記のどれか (またはその他) の形式になります。 そして、こうして生成された URL が後でリクエストされた場合には、解析されて元のルートとクエリ・パラメータの値に戻されます。 ``` @@ -39,15 +43,19 @@ $url = Url::to(['post/view', 'id' => 100]); - デフォルトの URL 形式と、 - 綺麗な URL (プリティ URL) の 形式。 -デフォルトの URL 形式は、`r` という [[yii\web\UrlManager::$routeParam|クエリ・パラメータ]] を使用してルートを表し、通常のクエリ・パラメータを使用してルートに結び付けられたクエリ・パラメータを表します。 +デフォルトの URL 形式は、`r` という [[yii\web\UrlManager::$routeParam|クエリ・パラメータ]] を使用してルートを表し、 +通常のクエリ・パラメータを使用してルートに結び付けられたクエリ・パラメータを表します。 例えば、`/index.php?r=post/view&id=100` という URL は、`post/view` というルートと、`id` というクエリ・パラメータが 100 であることを表します。 デフォルトの URL 形式は、[[yii\web\UrlManager|URL マネージャ]] についての構成を何も必要とせず、ウェブ・サーバの設定がどのようなものでも動作します。 綺麗な URL 形式は、エントリ・スクリプトの名前に続く追加のパスを使用して、ルートとそれに結び付けられたクエリ・パラメータを表します。 -例えば、`/index.php/post/100` という URL の追加のパスは `/post/100` ですが、適切な [[yii\web\UrlManager::rules|URL 規則]] があれば、この追加のパスが `post/view` というルートと `id` のクエリ・パラメータ `100` を表すものとすることが出来ます。 -綺麗な URL 形式を使用するためには、URL をどのように表現すべきかという実際の要求に従って、一連の [[yii\web\UrlManager::rules|URL 規則]] を設計する必要があります。 +例えば、`/index.php/post/100` という URL の追加のパスは `/post/100` ですが、 +適切な [[yii\web\UrlManager::rules|URL 規則]] があれば、この追加のパスが `post/view` というルートと `id` のクエリ・パラメータ `100` を表すものとすることが出来ます。 +綺麗な URL 形式を使用するためには、URL をどのように表現すべきかという実際の要求に従って、 +一連の [[yii\web\UrlManager::rules|URL 規則]] を設計する必要があります。 -この二つの URL 形式は、[[yii\web\UrlManager|URL マネージャ]] の [[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] プロパティを ON/OFF することによって、他のアプリケーション・コードを少しも変えることなく、切り替えることが出来ます。 +この二つの URL 形式は、[[yii\web\UrlManager|URL マネージャ]] の [[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] プロパティを ON/OFF することによって、 +他のアプリケーション・コードを少しも変えることなく、切り替えることが出来ます。 ## ルーティング @@ -55,9 +63,11 @@ $url = Url::to(['post/view', 'id' => 100]); ルーティングは二つのステップを含みます。 - まず、入ってくるリクエストが解析されて、ルートとそれに結び付けられたクエリ・パラメータに分解されます。 -- そして、解析されたルートに対応する [コントローラ・アクション](structure-controllers.md#actions) がリクエストを処理するために生成されます。 +- そして、解析されたルートに対応する [コントローラ・アクション](structure-controllers.md#actions) +がリクエストを処理するために生成されます。 -デフォルトの URL 形式を使っている場合は、リクエストからルートを解析することは、`r` という名前の `GET` クエリ・パラメータを取得するだけの簡単なことです。 +デフォルトの URL 形式を使っている場合は、リクエストからルートを解析することは、 +`r` という名前の `GET` クエリ・パラメータを取得するだけの簡単なことです。 綺麗な URL 形式を使っている場合は、[[yii\web\UrlManager|URL マネージャ]] が、登録されている [[yii\web\UrlManager::rules|URL 規則]] を調べます。 合致する規則が見つかれば、リクエストをルートに解決することが出来ます。 @@ -66,7 +76,8 @@ $url = Url::to(['post/view', 'id' => 100]); いったんリクエストからルートが解析されたら、今度はルートによって特定されるコントローラ・アクションを生成する番です。 ルートはその中にあるスラッシュによって複数の部分に分けられます。例えば、`site/index` は `site` と `index` に分割されます。 その各部分は、モジュール、コントローラ、または、アクションを参照する ID です。 -アプリケーションは、ルートの最初の部分の ID から始めて、下記のステップを踏んで、モジュール (もし有れば)、コントローラ、アクションを生成します。 +アプリケーションは、ルートの最初の部分の ID から始めて、下記のステップを踏んで、 +モジュール (もし有れば)、コントローラ、アクションを生成します。 1. アプリケーションをカレント・モジュールとして設定します。 2. カレント・モジュールの [[yii\base\Module::controllerMap|コントローラ・マップ]] が現在の ID を含むかどうかを調べます。 @@ -81,14 +92,16 @@ $url = Url::to(['post/view', 'id' => 100]); もし有れば、マップの中で見つかった構成情報に従ってアクションを生成します。 もし無ければ、現在の [アクション ID](structure-controllers.md#action-ids) に対応するアクション・メソッドで定義されるインライン・アクションを生成しようと試みます。 -上記のステップの中で、何かエラーが発生すると、[[yii\web\NotFoundHttpException]] が投げられて、ルーティングのプロセスが失敗したことが示されます。 +上記のステップの中で、何かエラーが発生すると、[[yii\web\NotFoundHttpException]] が投げられて、 +ルーティングのプロセスが失敗したことが示されます。 ### デフォルト・ルート リクエストから解析されたルートが空になった場合は、いわゆる *デフォルト・ルート* が代りに使用されることになります。 デフォルトでは、デフォルト・ルートは `site/index` であり、`site` コントローラの `index` アクションを指します。 -デフォルト・ルートは、次のように、アプリケーションの構成情報の中でアプリケーションの [[yii\web\Application::defaultRoute|defaultRoute]] プロパティを構成することによって、カスタマイズすることが出来ます。 +デフォルト・ルートは、次のように、アプリケーションの構成情報の中でアプリケーションの [[yii\web\Application::defaultRoute|defaultRoute]] +プロパティを構成することによって、カスタマイズすることが出来ます。 ```php [ @@ -98,18 +111,17 @@ $url = Url::to(['post/view', 'id' => 100]); ``` アプリケーションのデフォルト・ルートと同じく、モジュールにもデフォルト・ルートがあります。 -従って、例えば、`user` というモジュールがあって、リクエストの解析結果が `user` というルートになった場合、 -このモジュールの [[yii\base\Module::defaultRoute|defaultRoute]] がコントローラを決定するのに使用されます。 +従って、例えば、`user` というモジュールがあって、リクエストの解析結果が `user` というルートになった場合、このモジュールの [[yii\base\Module::defaultRoute|defaultRoute]] がコントローラを決定するのに使用されます。 デフォルトでは、このコントローラの名前は `default` となります。 -[[yii\base\Module::defaultRoute|defaultRoute]] でアクションが指定されていない場合は、 -コントローラの [[yii\base\Controller::defaultAction|defaultAction]] プロパティがアクションを決定するのに使用されます。 +[[yii\base\Module::defaultRoute|defaultRoute]] でアクションが指定されていない場合は、コントローラの [[yii\base\Controller::defaultAction|defaultAction]] プロパティがアクションを決定するのに使用されます。 この例の場合だと、完全なルートは `user/default/index` となります。 ### `catchAll` ルート たまには、ウェブ・アプリケーションを一時的にメンテナンス・モードにして、全てのリクエストに対して同じ「お知らせ」のページを表示したいことがあるでしょう。 -この目的を達する方法はたくさんありますが、最も簡単な方法の一つは、次のように、アプリケーションの構成情報の中で [[yii\web\Application::catchAll]] プロパティを構成することです。 +この目的を達する方法はたくさんありますが、最も簡単な方法の一つは、次のように、 +アプリケーションの構成情報の中で [[yii\web\Application::catchAll]] プロパティを構成することです。 ```php [ @@ -120,14 +132,17 @@ $url = Url::to(['post/view', 'id' => 100]); 上記の構成によって、入ってくる全てのリクエストを処理するために `site/offline` アクションが使われるようになります。 -`catchAll` プロパティは配列を取り、最初の要素はルートを指定し、残りの要素 (「名前-値」のペア) は [アクションのパラメータ](structure-controllers.md#action-parameters) を指定するものでなければなりません。 +`catchAll` プロパティは配列を取り、最初の要素はルートを指定し、残りの要素 (「名前-値」のペア) は +[アクションのパラメータ](structure-controllers.md#action-parameters) を指定するものでなければなりません。 -> Info: このプロパティを有効にすると、開発環境で [デバッグ・ツール・バー](https://github.com/yiisoft/yii2-debug/blob/master/docs/guide-ja/README.md)が 動作しなくなります。 +> Info: このプロパティを有効にすると、開発環境で [デバッグ・ツール・バー](https://github.com/yiisoft/yii2-debug/blob/master/docs/guide-ja/README.md)が +> 動作しなくなります。 ## URL を生成する -Yii は、与えられたルートとそれに結び付けられたクエリ・パラメータからさまざまな URL を生成する [[yii\helpers\Url::to()]] というヘルパ・メソッドを提供しています。例えば、 +Yii は、与えられたルートとそれに結び付けられたクエリ・パラメータからさまざまな URL を生成する +[[yii\helpers\Url::to()]] というヘルパ・メソッドを提供しています。例えば、 ```php use yii\helpers\Url; @@ -155,11 +170,14 @@ echo Url::to(['post/index'], 'https'); ルートは *相対* ルートか *絶対* ルートかのどちらかであり、下記の規則によって正規化されます。 - ルートが空文字列である場合は、現在リクエストされている [[yii\web\Controller::route|ルート]] が使用されます。 -- ルートがスラッシュを全く含まない場合は、カレント・コントローラのアクション ID であると見なされて、カレント・コントローラの [[\yii\web\Controller::uniqueId|uniqueId]] の値が前置されます。 -- ルートが先頭にスラッシュを含まない場合は、カレント・モジュールに対する相対ルートと見なされて、カレント・モジュールの [[\yii\base\Module::uniqueId|uniqueId]] の値が前置されます。 +- ルートがスラッシュを全く含まない場合は、カレント・コントローラのアクション ID であると見なされて、 + カレント・コントローラの [[\yii\web\Controller::uniqueId|uniqueId]] の値が前置されます。 +- ルートが先頭にスラッシュを含まない場合は、カレント・モジュールに対する相対ルートと見なされて、 + カレント・モジュールの [[\yii\base\Module::uniqueId|uniqueId]] の値が前置されます。 バージョン 2.0.2 以降では、[エイリアス](concept-aliases.md) の形式でルートを指定することが出来ます。 -その場合は、エイリアスが最初に実際のルートに変換され、そのルートが上記の規則に従って絶対ルートに変換されます。 +その場合は、エイリアスが最初に実際のルートに変換され、 +そのルートが上記の規則に従って絶対ルートに変換されます。 例えば、カレント・モジュールが `admin` であり、カレント・コントローラが `post` であると仮定すると、 @@ -182,7 +200,9 @@ echo Url::to(['/post/index']); echo Url::to(['@posts']); ``` -[[yii\helpers\Url::to()]] メソッドは、[[yii\web\UrlManager|URL マネージャ]] の [[yii\web\UrlManager::createUrl()|createUrl()]] メソッド、および、[[yii\web\UrlManager::createAbsoluteUrl()|createAbsoluteUrl()]] を呼び出すことによって実装されています。 +[[yii\helpers\Url::to()]] メソッドは、[[yii\web\UrlManager|URL マネージャ]] の +[[yii\web\UrlManager::createUrl()|createUrl()]] メソッド、および、[[yii\web\UrlManager::createAbsoluteUrl()|createAbsoluteUrl()]] +を呼び出すことによって実装されています。 次に続くいくつかの項では、[[yii\web\UrlManager|URL マネージャ]] を構成して、生成される URL の形式をカスタマイズする方法を説明します。 [[yii\helpers\Url::to()]] メソッドは、特定のルートとの関係を持た**ない** URL の生成もサポートしています。 @@ -247,16 +267,22 @@ echo Url::previous(); その他のプロパティはオプションですが、上記で示されている構成が最もよく用いられているものです。 * [[yii\web\UrlManager::showScriptName|showScriptName]]: このプロパティは、生成される URL にエントリ・スクリプトを含めるべきかどうかを決定します。 - 例えば、このプロパティを `false` にすると、`/index.php/post/100` という URL を生成する代りに、`/post/100` という URL を生成することが出来ます。 + 例えば、このプロパティを `false` にすると、`/index.php/post/100` という URL を生成する代りに、 + `/post/100` という URL を生成することが出来ます。 * [[yii\web\UrlManager::enableStrictParsing|enableStrictParsing]]: このプロパティは、厳密なリクエスト解析を有効にするかどうかを決定します。 厳密な解析が有効にされた場合、リクエストされた URL が有効なリクエストとして扱われるためには、それが [[yii\web\UrlManager::rules|rules]] の少なくとも一つに合致しなければなりません。 そうでなければ、[[yii\web\NotFoundHttpException]] が投げられます。 - 厳密な解析が無効にされた場合は、リクエストされた URL が [[yii\web\UrlManager::rules|rules]] のどれにも合致しない場合は、URL のパス情報の部分がリクエストされたルートとして扱われます。 + 厳密な解析が無効にされた場合は、リクエストされた URL が [[yii\web\UrlManager::rules|rules]] のどれにも合致しない場合は、 + URL のパス情報の部分がリクエストされたルートとして扱われます。 * [[yii\web\UrlManager::rules|rules]]: このプロパティが URL を解析および生成するための一連の規則を含みます。 - このプロパティが、アプリケーションの固有の要求を満たす形式を持つ URL を生成するために、あなたが主として使うプロパティです。 + このプロパティが、アプリケーションの固有の要求を満たす形式を持つ URL を生成するために、 + あなたが主として使うプロパティです。 -> Note: 生成された URL からエントリ・スクリプト名を隠すためには、[[yii\web\UrlManager::showScriptName|showScriptName]] を `false` に設定するだけでなく、ウェブ・サーバを構成して、リクエストされた URL が PHP スクリプトを明示的に指定していない場合でも、正しい PHP スクリプトを特定出来るようにする必要があります。 -もしあなたが Apache または nginx ウェブ・サーバを使うつもりなら、[インストール](start-installation.md#recommended-apache-configuration) のセクションで説明されている推奨設定を参照することが出来ます。 +> Note: 生成された URL からエントリ・スクリプト名を隠すためには、[[yii\web\UrlManager::showScriptName|showScriptName]] を `false` に設定するだけでなく、 + ウェブ・サーバを構成して、リクエストされた URL が PHP スクリプトを明示的に指定していない場合でも、 + 正しい PHP スクリプトを特定出来るようにする必要があります。 +もしあなたが Apache または nginx ウェブ・サーバを使うつもりなら、[インストール](start-installation.md#recommended-apache-configuration) + のセクションで説明されている推奨設定を参照することが出来ます。 ### URL 規則 @@ -266,8 +292,10 @@ URL 規則は [[yii\web\UrlRuleInterface]] を実装するクラス、通常は URL 規則は、パターンがリクエストされた URL と合致する場合に、リクエストの解析に使用することが出来ます。 また、URL 規則は、ルートとクエリ・パラメータ名が与えられたものと合致する場合に、URL の生成に使用することが出来ます。 -綺麗な URL 形式が有効にされている場合、[[yii\web\UrlManager|URL マネージャ]] は、その [[yii\web\UrlManager::rules|rules]] プロパティに宣言されている URL 規則を使って、入ってくるリクエストの解析と URL の生成を行います。 -具体的に言えば、入ってくるリクエストを解析するためには、[[yii\web\UrlManager|URL マネージャ]] は宣言されている順に規則を調べて、リクエストされた URL に合致する *最初の* 規則を探します。 +綺麗な URL 形式が有効にされている場合、[[yii\web\UrlManager|URL マネージャ]] は、その [[yii\web\UrlManager::rules|rules]] プロパティに宣言されている URL 規則を使って、 +入ってくるリクエストの解析と URL の生成を行います。 +具体的に言えば、入ってくるリクエストを解析するためには、[[yii\web\UrlManager|URL マネージャ]] は宣言されている順に規則を調べて、 +リクエストされた URL に合致する *最初の* 規則を探します。 そして、その合致する規則を使って URL を解析して、ルートとそれに結び付けられたパラメータを得ます。 同じように、URL を生成するためには、[[yii\web\UrlManager|URL マネージャ]] は、与えられたルートとパラメータに合致する最初の規則を探して、それを使って URL を生成します。 @@ -285,12 +313,12 @@ URL 規則は、パターンがリクエストされた URL と合致する場 ``` > Info: 規則のパターンは URL のパス情報の部分との照合に使用されます。 -例えば、`/index.php/post/100?source=ad` のパス情報は `post/100` であり (先頭と末尾のスラッシュは無視します)、これは `post/(\d+)` というパターンに合致します。 + 例えば、`/index.php/post/100?source=ad` のパス情報は `post/100` であり (先頭と末尾のスラッシュは無視します)、 + これは `post/(\d+)` というパターンに合致します。 URL 規則は、「パターン - ルート」のペアとして宣言する以外に、構成情報配列として宣言することも出来ます。 構成情報の一つの配列が、それぞれ、一つの URL 規則のオブジェクトを構成するために使われます。 -この形式は、URL 規則の他のプロパティを構成したい場合に、よく必要になります。 -例えば、 +この形式は、URL 規則の他のプロパティを構成したい場合に、よく必要になります。例えば、 ```php 'rules' => [ @@ -304,20 +332,23 @@ URL 規則は、「パターン - ルート」のペアとして宣言する以 ``` URL 規則の構成情報で `class` を指定しない場合は、デフォルトとして、[[yii\web\UrlRule]] が使われます。 -このクラスが、[[yii\web\UrlManager::$ruleConfig]] でデフォルト値として定義されています。 +このクラスが、[[yii\web\UrlManager::$ruleConfig]] で +デフォルト値として定義されています。 ### 名前付きパラメータ URL 規則は、パターンの中で `` の形式で指定される、名前付きクエリ・パラメータと結び付けることが出来ます。 ここで、`ParamName` はパラメータ名を指定し、`RegExp` はパラメータの値との照合に使われるオプションの正規表現を指定するものです。 -`RegExp` が指定されていない場合は、パラメータの値がスラッシュを含まない文字列であるべきことを意味します。 +`RegExp` が指定されていない場合は、 +パラメータの値がスラッシュを含まない文字列であるべきことを意味します。 > Note: 正規表現はパラメータの中でのみ使用できます。パターンの残りの部分はプレーンテキストとして解釈されます。 規則が URL の解析に使われるときには、URL の対応する部分に合致した値が、結び付けられたパラメータに入れられます。 そして、そのパラメータは、後に `request` アプリケーション・コンポーネントによって、`$_GET` に入れられて利用できるようになります。 -規則が URL の生成に使われるときは、提供されたパラメータの値を受けて、パラメータが宣言されている所にその値が挿入されます。 +規則が URL の生成に使われるときは、提供されたパラメータの値を受けて、 +パラメータが宣言されている所にその値が挿入されます。 名前付きパラメータの動作を説明するためにいくつかの例を挙げましょう。次の三つの URL 規則を宣言したと仮定してください。 @@ -332,8 +363,10 @@ URL 規則は、パターンの中で `` の形式で指定さ 規則が URL 解析に使われる場合は、 - `/index.php/posts` は、二番目の規則を使って解析され、ルート `post/index` になります。 -- `/index.php/posts/2014/php` は、最初の規則を使って解析され、ルートは `post/index`、`year` パラメータの値は 2014、そして、`category` パラメータの値は `php` となります。 -- `/index.php/post/100` は、三番目の規則を使って解析され、ルートが `post/view`、`id` パラメータの値が 100 となります。 +- `/index.php/posts/2014/php` は、最初の規則を使って解析され、ルートは `post/index`、`year` パラメータの値は 2014、 + そして、`category` パラメータの値は `php` となります。 +- `/index.php/post/100` は、三番目の規則を使って解析され、ルートが `post/view`、 + `id` パラメータの値が 100 となります。 - `/index.php/posts/php` は、どのパターンにも合致しないため、[[yii\web\UrlManager::enableStrictParsing]] が `true` の場合は、[[yii\web\NotFoundHttpException]] を引き起こします。 [[yii\web\UrlManager::enableStrictParsing]] が `false` (これがデフォルト値です) の場合は、パス情報の部分である `posts/php` がルートとして返されることになります。 こうして解析されたルートに対応するアクションがあればそれが実行され、そうでなければ [[yii\web\NotFoundHttpException]] が投げられます。 @@ -346,7 +379,8 @@ URL 規則は、パターンの中で `` の形式で指定さ - `Url::to(['post/view', 'id' => 100, 'source' => 'ad'])` も、三番目の規則を使って、`/index.php/post/100?source=ad` を生成します。 `source` パラメータは規則の中で指定されていないので、クエリ・パラメータとして、生成される URL に追加されます。 - `Url::to(['post/index', 'category' => 'php'])` は、どの規則も使わずに、`/index.php/post/index?category=php` を生成します。 - どの規則も当てはまらないため、URL は、単純に、ルートをパス情報とし、すべてのパラメータをクエリ文字列として追加して生成されます。 + どの規則も当てはまらないため、URL は、単純に、ルートをパス情報とし、 + すべてのパラメータをクエリ文字列として追加して生成されます。 ### ルートをパラメータ化する @@ -368,7 +402,8 @@ URL 規則のルートにはパラメータ名を埋め込むことが出来ま 同じように、`comment/index` というルートの URL を生成するためには、最後の規則が適用されて、`index.php/comments` という URL が生成されます。 -> Info: ルートをパラメータ化することによって、URL 規則の数を大幅に減らすことが可能になり、[[yii\web\UrlManager|URL マネージャ]] のパフォーマンスを目に見えて改善することが出来ます。 +> Info: ルートをパラメータ化することによって、URL 規則の数を大幅に減らすことが可能になり、 + [[yii\web\UrlManager|URL マネージャ]] のパフォーマンスを目に見えて改善することが出来ます。 ### デフォルトのパラメータ値 @@ -377,7 +412,8 @@ URL 規則のルートにはパラメータ名を埋め込むことが出来ま パラメータのどれかをオプション扱いにしたい場合は、規則の [[yii\web\UrlRule::defaults|defaults]] プロパティを構成することが出来ます。 このプロパティのリストに挙げられたパラメータはオプション扱いとなり、提供されなかった場合は指定された値を取るようになります。 -次の規則の宣言においては、`page` と `tag` のパラメータは両方ともオプション扱いで、提供されなかった場合は、それぞれ、1 と空文字列を取ります。 +次の規則の宣言においては、`page` と `tag` のパラメータは両方ともオプション扱いで、 +提供されなかった場合は、それぞれ、1 と空文字列を取ります。 ```php 'rules' => [ @@ -399,6 +435,9 @@ URL 規則のルートにはパラメータ名を埋め込むことが出来ま オプション扱いのパラメータを使わなければ、同じ結果を得るために 4 個の規則を作らなければならなかったところです。 +> Note: [[yii\web\UrlRule::$pattern|pattern]] がオプション扱いのパラメータとスラッシュだけを含んでいるときは、 + 最初のパラメータは、他のパラメータが省略されている場合に限り、省略することが出来ます。 + ### サーバ名を持つ規則 @@ -423,14 +462,11 @@ URL 規則のパターンには、ウェブ・サーバ名を含むことが出 ``` バージョン 2.0.11 以降は、`http` と `https` の両方に通用する、プロトコル相対パターンを使うことも出来ます。 -記法は上記と同じです、ただ、`http:` の部分を省略します。 -例えば、`'//www.example.com/login' => 'site/login'`。 +記法は上記と同じです、ただ、`http:` の部分を省略します。例えば、`'//www.example.com/login' => 'site/login'`。 > Note: サーバ名を持つ規則は、そのパターンに、エントリ・スクリプトのサブフォルダを**含まない**ようにすべきです。 -例えば、アプリケーションのエントリ・スクリプトが `http://www.example.com/sandbox/blog/index.php` である場合は、 -`http://www.example.com/sandbox/blog/posts` ではなく、`http://www.example.com/posts` というパターンを使うべきです。 -こうすれば、アプリケーションをどのようなディレクトリに配置しても、URL 規則を変更する必要がなくなります。 -Yii はアプリケーションのベース URL を自動的に検出します。 +例えば、アプリケーションのエントリ・スクリプトが `http://www.example.com/sandbox/blog/index.php` である場合は、`http://www.example.com/sandbox/blog/posts` ではなく、`http://www.example.com/posts` というパターンを使うべきです。 +こうすれば、アプリケーションをどのようなディレクトリに配置しても、URL 規則を変更する必要がなくなります。Yii はアプリケーションのベース URL を自動的に検出します。 ### URL 接尾辞 @@ -442,6 +478,7 @@ Yii はアプリケーションのベース URL を自動的に検出します ```php [ + // ... 'components' => [ 'urlManager' => [ 'enablePrettyUrl' => true, @@ -455,7 +492,8 @@ Yii はアプリケーションのベース URL を自動的に検出します ] ``` -上記の構成によって、[[yii\web\UrlManager|URL マネージャ]] は、接尾辞として `.html` の付いた URL を認識し、また、生成するようになります。 +上記の構成によって、[[yii\web\UrlManager|URL マネージャ]] は、接尾辞として `.html` の付いた URL を認識し、 +また、生成するようになります。 > Tip: URL が全てスラッシュで終るようにするためには、URL 接尾辞として `/` を設定することが出来ます。 @@ -487,7 +525,6 @@ URL 規則にこのプロパティが設定されている場合は、それが ] ``` - ### HTTP メソッド RESTful API を実装するときは、使用されている HTTP メソッドに応じて、同一の URL を異なるルートとして解析することが必要になる場合がよくあります。 @@ -517,7 +554,8 @@ RESTful API を実装するときは、使用されている HTTP メソッド URL 規則は [[yii\web\UrlManager|URL マネージャ]] に動的に追加することが出来ます。 このことは、再配布可能な [モジュール](structure-modules.md) が自分自身の URL 規則を管理する必要がある場合に、しばしば必要になります。 動的に追加された規則がルーティングのプロセスで効果を発揮するためには、その規則をアプリケーションの [ブートストラップ](runtime-bootstrapping.md) の段階で追加しなければなりません。 -これは、モジュールにとっては、次のように、[[yii\base\BootstrapInterface]] を実装して、[[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] メソッドの中で規則を追加しなければならないことを意味します。 +これは、モジュールにとっては、次のように、[[yii\base\BootstrapInterface]] を実装して、 +[[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] メソッドの中で規則を追加しなければならないことを意味します。 ```php public function bootstrap($app) @@ -528,13 +566,15 @@ public function bootstrap($app) } ``` -さらに、モジュールが [ブートストラップ](runtime-bootstrapping.md) の過程に関与できるように、それを [[yii\web\Application::bootstrap]] のリストに挙げなければならないことに注意してください。 +さらに、モジュールが [ブートストラップ](runtime-bootstrapping.md) の過程に関与できるように、 +それを [[yii\web\Application::bootstrap]] のリストに挙げなければならないことに注意してください。 ### 規則クラスを作成する デフォルトの [[yii\web\UrlRule]] クラスはほとんどのプロジェクトに対して十分に柔軟なものであるというのは事実ですが、それでも、自分自身で規則クラスを作る必要があるような状況はあります。 -例えば、自動車ディーラーのウェブ・サイトにおいて、`/Manufacturer/Model` のような URL 形式をサポートしたいけれども、`Manufacturer` と `Model` は、両方とも、データベース・テーブルに保存されている何らかのデータに合致するものでなければならない、というような場合です。 +例えば、自動車ディーラーのウェブ・サイトにおいて、`/Manufacturer/Model` のような URL 形式をサポートしたいけれども、 +`Manufacturer` と `Model` は、両方とも、データベース・テーブルに保存されている何らかのデータに合致するものでなければならない、というような場合です。 デフォルトの規則クラスは、静的に宣言されるパターンに依拠しているため、ここでは役に立ちません。 この問題を解決するために、次のような URL 規則クラスを作成することが出来ます。 @@ -549,7 +589,6 @@ use yii\base\BaseObject; class CarUrlRule extends BaseObject implements UrlRuleInterface { - public function createUrl($manager, $route, $params) { if ($route === 'car/index') { @@ -593,8 +632,7 @@ class CarUrlRule extends BaseObject implements UrlRuleInterface バージョン 2.0.10 以降、[[yii\web\UrlManager|UrlManager]] で [[yii\web\UrlNormalizer|UrlNormalizer]] を使って、 同一 URL のバリエーション (例えば、末尾のスラッシュの有無) の問題を処理する出来るようになりました。 -技術的には `http://example.com/path` と `http://example.com/path/` は別の URL ですから、 -これらの両方に同一のコンテントを提供することは SEO ランキングを低下させる可能性があります。 +技術的には `http://example.com/path` と `http://example.com/path/` は別の URL ですから、これらの両方に同一のコンテントを提供することは SEO ランキングを低下させる可能性があります。 デフォルトでは、URL ノーマライザは、連続したスラッシュを畳み、サフィックスが末尾のスラッシュを持っているかどうかに従って末尾のスラッシュを追加または削除し、 正規化された URL に [恒久的な移動](https://en.wikipedia.org/wiki/HTTP_301) を使ってリダイレクトします。 ノーマライザは、URL マネージャのためにグローバルに構成することも、各規則のために個別に構成することも出来ます。 @@ -638,14 +676,17 @@ class CarUrlRule extends BaseObject implements UrlRuleInterface URL の正規化を有効にするためには、明示的に構成する必要があります。 + ## パフォーマンスに対する考慮 -複雑なウェブ・アプリケーションを開発するときは、リクエストの解析と URL 生成に要する時間を削減するために URL 規則を最適化することが重要になります。 +複雑なウェブ・アプリケーションを開発するときは、リクエストの解析と URL 生成に要する時間を削減するために +URL 規則を最適化することが重要になります。 パラメータ化したルートを使うことによって、URL 規則の数を減らして、パフォーマンスを著しく向上させることが出来ます。 URL を解析または生成するときに、[[yii\web\UrlManager|URL マネージャ]] は、宣言された順序で URL 規則を調べます。 従って、より多く使われる規則がより少なく使われる規則より前に来るように順序を調整することを検討してください。 -パターンまたはルートに共通の先頭部分を持つ URL 規則がある場合は、[[yii\web\UrlManager|URL マネージャ]] がそれらをグループ化して効率的に調べることが出来るように、[[yii\web\GroupUrlRule]] を使うことを検討してください。 +パターンまたはルートに共通の先頭部分を持つ URL 規則がある場合は、[[yii\web\UrlManager|URL マネージャ]] がそれらをグループ化して効率的に調べることが出来るように、 +[[yii\web\GroupUrlRule]] を使うことを検討してください。 あなたのアプリケーションがモジュールによって構成されており、モジュールごとに、モジュール ID を共通の先頭部分とする一群の URL 規則を持っている場合は、通常、このことが当てはまります。 diff --git a/docs/guide-ja/runtime-sessions-cookies.md b/docs/guide-ja/runtime-sessions-cookies.md index b968a87..4db9741 100644 --- a/docs/guide-ja/runtime-sessions-cookies.md +++ b/docs/guide-ja/runtime-sessions-cookies.md @@ -8,7 +8,9 @@ Yii はセッションとクッキーをオブジェクトとしてカプセル ## セッション -[リクエスト](runtime-requests.md) や [レスポンス](runtime-responses.md) と同じように、デフォルトでは [[yii\web\Session]] のインスタンスである `session` [アプリケーション・コンポーネント] によって、セッションにアクセスすることが出来ます。 +[リクエスト](runtime-requests.md) や [レスポンス](runtime-responses.md) と同じように、 +デフォルトでは [[yii\web\Session]] のインスタンスである `session` [アプリケーション・コンポーネント] によって、 +セッションにアクセスすることが出来ます。 ### セッションのオープンとクローズ @@ -67,10 +69,12 @@ foreach ($session as $name => $value) ... foreach ($_SESSION as $name => $value) ... ``` -> Info: セッション・データに `session` コンポーネントによってアクセスする場合は、まだ開かれていないときは、自動的にセッションが開かれます。 - これに対して `$_SESSION` によってセッション・データにアクセスする場合は、`session_start()` を明示的に呼び出すことが必要になります。 +> Info: `session` コンポーネントによってセッション・データにアクセスする場合は、まだ開かれていないときは、自動的にセッションが開かれます。 + これに対して `$_SESSION` によってセッション・データにアクセスする場合は、 + `session_start()` を明示的に呼び出すことが必要になります。 -配列であるセッション・データを扱う場合、`session` コンポーネントには、配列の要素を直接修正することができない、という制約があります。例えば、 +配列であるセッション・データを扱う場合、`session` コンポーネントには、配列の要素を直接修正することができない、という制約があります。 +例えば、 ```php $session = Yii::$app->session; @@ -116,7 +120,8 @@ $session['captcha.lifetime'] = 3600; ``` パフォーマンスとコードの可読性を高めるためには、最後の回避策を推奨します。 -すなわち、配列を一つのセッション変数として保存する代りに、配列の個々の要素を他の要素と同じキー接頭辞を共有する一個ずつのセッション変数として保存することです。 +すなわち、配列を一つのセッション変数として保存する代りに、配列の個々の要素を、他の配列要素と共通の接頭辞を持つ、 +個別のセッション変数として保存することです。 ### カスタム・セッション・ストレージ @@ -132,11 +137,13 @@ Yii は、また、さまざまなセッション・ストレージを実装す これらのセッション・クラスは全て一連の同じ API メソッドをサポートします。 その結果として、セッションを使用するアプリケーション・コードを修正することなしに、セッション・ストレージ・クラスを切り替えることが出来ます。 -> Note: カスタム・セッション・ストレージを使っているときに `$_SESSION` を通じてセッション・データにアクセスしたい場合は、セッションが [[yii\web\Session::open()]] によって既に開始されていることを確認しなければなりません。 +> Note: カスタム・セッション・ストレージを使っているときに `$_SESSION` を通じてセッション・データにアクセスしたい場合は、 + セッションが [[yii\web\Session::open()]] によって既に開始されていることを確認しなければなりません。 これは、カスタム・セッション・ストレージのハンドラは、この `open()` メソッドの中で登録されるからです。 これらのコンポーネント・クラスの構成方法と使用方法については、それらの API ドキュメントを参照してください。 -下記の例は、アプリケーションの構成情報において、データベース・テーブルをセッション・ストレージとして使うために [[yii\web\DbSession]] を構成する方法を示すものです。 +下記の例は、アプリケーションの構成情報において、データベース・テーブルをセッション・ストレージとして使うために [[yii\web\DbSession]] +を構成する方法を示すものです。 ```php return [ @@ -168,7 +175,8 @@ CREATE TABLE session - MSSQL: BLOB > Note: php.ini の `session.hash_function` の設定によっては、`id` カラムの長さを修正する必要があるかも知れません。 - 例えば、`session.hash_function=sha256` である場合は、40 の代りに 64 の長さを使わなければなりません。 + 例えば、`session.hash_function=sha256` である場合は + 40 の代りに 64 の長さを使わなければなりません。 別の方法として、次のマイグレーションを使ってこれを達成することも出来ます。 @@ -198,8 +206,10 @@ class m170529_050554_create_table_session extends Migration ### フラッシュ・データ -フラッシュ・データは特殊な種類のセッション・データで、あるリクエストの中で設定されると、次のリクエストの間においてのみ読み出すことが出来て、その後は自動的に削除されるものです。 -フラッシュ・データが最もよく使われるのは、エンド・ユーザに一度だけ表示されるべきメッセージ、例えば、ユーザのフォーム送信が成功した後に表示される確認メッセージなどを実装するときです。 +フラッシュ・データは特殊な種類のセッション・データで、あるリクエストの中で設定されると、 +次のリクエストの間においてのみ読み出すことが出来て、その後は自動的に削除されるものです。 +フラッシュ・データが最もよく使われるのは、エンド・ユーザに一度だけ表示されるべきメッセージ、 +例えば、ユーザのフォーム送信が成功した後に表示される確認メッセージなどを実装するときです。 `session` アプリケーション・コンポーネントによって、フラッシュ・データを設定し、アクセスすることが出来ます。例えば、 @@ -240,8 +250,10 @@ $alerts = $session->getFlash('alerts'); ``` > Note: 同じ名前のフラッシュ・データに対して、[[yii\web\Session::setFlash()]] と [[yii\web\Session::addFlash()]] を一緒に使わないようにしてください。 - これは、後者のメソッドが、同じ名前のフラッシュ・データを追加できるように、フラッシュ・データを自動的に配列に変換するからです。 - その結果、[[yii\web\Session::getFlash()]] を呼び出したとき、この二つのメソッドの呼び出し順によって、あるときは配列を受け取り、あるときは文字列を受け取るということになってしまいます。 + これは、後者のメソッドが、同じ名前のフラッシュ・データを追加できるように、 + フラッシュ・データを自動的に配列に変換するからです。 + その結果、[[yii\web\Session::getFlash()]] を呼び出したとき、この二つのメソッドを呼び出した順序に従って、 + あるときは配列を受け取り、あるときは文字列を受け取るということになります。 > Tip: フラッシュ・メッセージを表示するためには、[[yii\bootstrap\Alert|bootstrap Alert]] ウィジェットを次のように使用することが出来ます。 > @@ -257,7 +269,8 @@ $alerts = $session->getFlash('alerts'); Yii は個々のクッキーを [[yii\web\Cookie]] のオブジェクトとして表します。 [[yii\web\Request]] と [[yii\web\Response]] は、ともに、`cookies` という名前のプロパティによって、クッキーのコレクションを保持します。 -後者のクッキー・コレクションはリクエストの中で送信されてきたクッキーを表し、一方、後者のクッキー・コレクションは、これからユーザに送信されるクッキーを表します。 +前者のクッキー・コレクションはリクエストの中で送信されてきたクッキーを表し、 +一方、後者のクッキー・コレクションは、これからユーザに送信されるクッキーを表します。 アプリケーションで、リクエストとレスポンスを直接に操作する部分は、コントローラです。 従って、クッキーの読み出しと送信はコントローラで実行されるべきです。 @@ -309,17 +322,20 @@ $cookies->remove('language'); unset($cookies['language']); ``` -[[yii\web\Cookie]] クラスは、上記の例で示されている [[yii\web\Cookie::name|name]] と [[yii\web\Cookie::value|value]] のプロパティ以外にも、[[yii\web\Cookie::domain|domain]] -や [[yii\web\Cookie::expire|expire]] など、他のプロパティを定義して、利用可能なクッキー情報の全てを完全に表しています。 +[[yii\web\Cookie]] クラスは、上記の例で示されている [[yii\web\Cookie::name|name]] と [[yii\web\Cookie::value|value]] +のプロパティ以外にも、[[yii\web\Cookie::domain|domain]] や [[yii\web\Cookie::expire|expire]] など、 +他のプロパティを定義して、利用可能なクッキー情報の全てを完全に表しています。 クッキーを準備するときに必要に応じてこれらのプロパティを構成してから、レスポンスのクッキー・コレクションに追加することが出来ます。 > Note: セキュリティを向上させるために、[[yii\web\Cookie::httpOnly]] のデフォルト値は `true` に設定されています。 これは、クライアント・サイド・スクリプトが保護されたクッキーにアクセスする危険を軽減するものです (ブラウザがサポートしていれば)。 詳細については、[httpOnly wiki article](https://www.owasp.org/index.php/HttpOnly) を読んでください。 + ### クッキー検証 -最後の二つの項で示されているように、`request` と `response` のコンポーネントを通じてクッキーを読んだり送信したりする場合には、クッキーがクライアント・サイドで修正されるのを防止するクッキー検証という追加のセキュリティを享受することが出来ます。 +最後の二つの項で示されているように、`request` と `response` のコンポーネントを通じてクッキーを読んだり送信したりする場合には、 +クッキーがクライアント・サイドで修正されるのを防止するクッキー検証という追加のセキュリティを享受することが出来ます。 これは、個々のクッキーにハッシュ文字列をサインとして追加することによって達成されます。 アプリケーションは、サインを見て、クッキーがクライアント・サイドで修正されたかどうかを知ることが出来ます。 もし、修正されていれば、そのクッキーは `request` コンポーネントの [[yii\web\Request::cookies|クッキー・コレクション]] からはアクセスすることが出来なくなります。