Skip to content

Y
yii2
Commit 4a53d0ca by Nobuo Kihara Committed by Carsten Brandt
Options

docs/guide-ja/runtime revised [ci skip]

close #6341
parent 53f1cb61
Showing with 313 additions and 388 deletions
docs/guide-ja/runtime-bootstrapping.md
ブートストラップ
================
ブートストラップとは、アプリケーションが入ってくるリクエストの解決と処理を開始する前の、
環境を準備する過程を指すものです。ブートストラップは二つの場所、すなわち、[エントリスクリプト](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) のインスタンスを作成します。
この中には、Composer の `autoload.php` によるオートローダと、Yii の `Yii` クラスファイルによるオートローダが含まれます。
エントリスクリプトは、次に、アプリケーションの [構成情報](concept-configurations.md) をロードして、[アプリケーション](structure-applications.md) のインスタンスを作成します。
アプリケーションのコンストラクタでは、次のようなブートストラップの仕事が行われます。
1. [[yii\base\Application::preInit()|preInit()]] が呼ばれます。このメソッドは、いくつかの
優先度の高いアプリケーションプロパティ、例えば [[yii\base\Application::basePath|basePath]]
などを構成します。
1. [[yii\base\Application::preInit()|preInit()]] が呼ばれます。
このメソッドは、いくつかの優先度の高いアプリケーションプロパティ、例えば [[yii\base\Application::basePath|basePath]] などを構成します。
2. [[yii\base\Application::errorHandler|エラーハンドラ]] を登録します。
3. 与えられたアプリケーションコンフィギュレーションを使って、アプリケーションプロパティを初期化します。
4. [[yii\base\Application::init()|init()]] が呼ばれます。そして `init()` が [[yii\base\Application::bootstrap()|bootstrap()]] を呼んで、
ブートストラップコンポーネントを走らせます。
3. 与えられたアプリケーションの構成情報を使って、アプリケーションのプロパティを初期化します。
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) を作成して走らせます。
ブートストラップの仕事は *全て* のリクエストを処理する前に、毎回しなければなりませんので、この過程を
軽いものに保って可能な限り最適化することは非常に重要なことです。
ブートストラップの仕事は *全て* のリクエストを処理する前に、毎回しなければなりませんので、この過程を軽いものに保って可能な限り最適化することは非常に重要なことです。
あまりに多くのブートストラップコンポーネントを登録しないように努めてください。ブートストラップ
コンポーネントが必要になるのは、リクエスト処理のライフサイクル全体に関与する必要がある場合だけです。
例えば、モジュールが追加の URL 解析規則を登録する必要がある場合は、モジュールを [bootstrap プロパティ](structure-applications.md#bootstrap)
のリストに挙げなければなりません。なぜなら、URL 規則を使ってリクエストが解決される前に、
新しい URL 規則を有効にしなければならないからです。
あまりに多くのブートストラップコンポーネントを登録しないように努めてください。
ブートストラップコンポーネントが必要になるのは、リクエスト処理のライフサイクル全体に関与する必要がある場合だけです。
例えば、モジュールが追加の 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) を持つものがあります。
そのような場合には、コンフィギュレーション配列全体をキャッシュしておき、エントリスクリプトでアプリケーションのインスタンスを作成する前には、コンフィギュレーション配列をキャッシュからロードするという方法を考慮してください。
大規模なアプリケーションには、多数の小さな構成情報ファイルに分割された、非常に複雑なアプリケーション [構成情報](concept-configurations.md) を持つものがあります。
そのような場合には、構成情報配列全体をキャッシュしておき、エントリスクリプトでアプリケーションのインスタンスを作成する前には、構成情報配列をキャッシュからロードするという方法を考慮してください。
docs/guide-ja/runtime-handling-errors.md
エラー処理
==========
Yii は、エラー処理を従来よりはるかに快適な経験にしてくれる、内臓の [[yii\web\ErrorHandler|エラーハンドラ]]
を持っています。具体的には、Yii のエラーハンドラはエラー処理を向上させるために、次のことを行います。
Yii は、エラー処理を従来よりはるかに快適な経験にしてくれる、内臓の [[yii\web\ErrorHandler|エラーハンドラ]] を持っています。
具体的には、Yii のエラーハンドラはエラー処理を向上させるために、次のことを行います。
* 致命的でない全ての PHP エラー (警告や通知) は捕捉可能な例外に変換されます。
* 例外と致命的な PHP エラーは、デバッグモードでは、詳細なコールスタック情報とソースコード行とともに表示されます。
* エラーを表示するために専用の [コントローラアクション](structure-controllers.md#actions) を使うことがサポートされています。
* さまざまなエラーレスポンス形式をサポートしています。
[[yii\web\ErrorHandler|エラーハンドラ]] は既定で有効になっています。アプリケーションの [エントリスクリプト](structure-entry-scripts.md)
において、定数 `YII_ENABLE_ERROR_HANDLER` を false と定義することによって、これを無効にすることが出来ます。
[[yii\web\ErrorHandler|エラーハンドラ]] は既定で有効になっています。
アプリケーションの [エントリスクリプト](structure-entry-scripts.md) において、定数 `YII_ENABLE_ERROR_HANDLER` を false と定義することによって、これを無効にすることが出来ます。
## エラーハンドラを使用する <a name="using-error-handler"></a>
[[yii\web\ErrorHandler|エラーハンドラ]] は `errorHandler` という名前の [アプリケーションコンポーネント](structure-application-components.md) です。
次のように、アプリケーションのコンフィギュレーションでこれをカスタマイズすることが出来ます。
次のように、アプリケーションの構成情報でこれをカスタマイズすることが出来ます。
```php
return [
......@@ -28,7 +28,7 @@ return [
];
```
上記のコンフィギュレーションによって、例外ページで表示されるソースコードの行数は最大で 20 までとなります。
上記の構成によって、例外ページで表示されるソースコードの行数は最大で 20 までとなります。
既に述べたように、エラーハンドラは致命的でない全ての PHP エラーを捕捉可能な例外に変換します。
これは、次のようなコードを使って PHP エラーを処理することが出来るということを意味します。
......@@ -46,8 +46,7 @@ try {
// 実行を継続 ...
```
ユーザに対して、リクエストが無効であったり予期しないものであったりすることを知らせるエラーページを表示したい場合は、
単に [[yii\web\NotFoundHttpException]] のような [[yii\web\HttpException|HTTP 例外]] を投げるだけで済ませることが出来ます。
ユーザに対して、リクエストが無効であったり予期しないものであったりすることを知らせるエラーページを表示したい場合は、単に [[yii\web\NotFoundHttpException]] のような [[yii\web\HttpException|HTTP 例外]] を投げるだけで済ませることが出来ます。
エラーハンドラがレスポンスの HTTP ステータスコードを正しく設定し、適切なエラービューを使ってエラーメッセージを表示してくれます。
```php
......@@ -60,28 +59,25 @@ throw new NotFoundHttpException();
## エラー表示をカスタマイズする <a name="customizing-error-display"></a>
[[yii\web\ErrorHandler|エラーハンドラ]] は、定数 `YII_DEBUG` の値に従って、エラー表示を調整します。
`YII_DEBUG` が true である (デバッグモードである) 場合は、エラーハンドラは、デバッグがより容易になるように、
詳細なコールスタック情報とソースコード行とともに例外を表示します。そして、`YII_DEBUG` が false のときは、
アプリケーションに関する公開できない情報を開示することを防ぐために、エラーメッセージだけが表示されます。
`YII_DEBUG` が true である (デバッグモードである) 場合は、エラーハンドラは、デバッグがより容易になるように、詳細なコールスタック情報とソースコード行とともに例外を表示します。
そして、`YII_DEBUG` が false のときは、アプリケーションに関する公開できない情報を開示することを防ぐために、エラーメッセージだけが表示されます。
> Info|情報: 例外が [[yii\base\UserException]] の子孫である場合は、`YII_DEBUG` の値の如何にかかわらず、コールスタックは表示されません。
これは、この種の例外はユーザの誤操作によって引き起こされるものであり、開発者は何も修正する必要がないと考えられるからです。
既定では、[[yii\web\ErrorHandler|エラーハンドラ]] は二つの [views](structure-views.md) を使ってエラーを表示します。
既定では、[[yii\web\ErrorHandler|エラーハンドラ]] は二つの [ビュー](structure-views.md) を使ってエラーを表示します。
* `@yii/views/errorHandler/error.php`: エラーがコールスタック情報なしで表示されるべき場合に使用されます。
`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]] プロパティを構成して、自分自身のビューを使用することが出来ます。
### エラーアクションを使う <a name="using-error-actions"></a>
エラー表示をカスタマイズするためのもっと良い方法は、専用のエラー [アクション](structure-controllers.md) を使うことです。
そうするためには、まず、`errorHandler` コンポーネントの [[yii\web\ErrorHandler::errorAction|errorAction]]
プロパティを次のように構成します。
そうするためには、まず、`errorHandler` コンポーネントの [[yii\web\ErrorHandler::errorAction|errorAction]] プロパティを次のように構成します。
```php
return [
......@@ -94,8 +90,7 @@ return [
```
[[yii\web\ErrorHandler::errorAction|errorAction]] プロパティは、アクションへの [ルート](structure-controllers.md#routes) を値として取ります。
上記のコンフィギュレーションは、エラーをコールスタック情報なしで表示する必要がある場合は、`site/error`
アクションが実行されるべきであることを記述しています。
上記の構成は、エラーをコールスタック情報なしで表示する必要がある場合は、`site/error` アクションが実行されるべきであることを記述しています。
`site/error` アクションは次のようにして作成することが出来ます。
......@@ -118,7 +113,8 @@ class SiteController extends Controller
}
```
上記のコードは [[yii\web\ErrorAction]] クラスを使って `error` アクションを定義しています。[[yii\web\ErrorAction]] クラスは `error` という名前のビューを使ってエラーをレンダリングします。
上記のコードは [[yii\web\ErrorAction]] クラスを使って `error` アクションを定義しています。
[[yii\web\ErrorAction]] クラスは `error` という名前のビューを使ってエラーをレンダリングします。
[[yii\web\ErrorAction]] を使う以外に、次のようにアクションメソッドを使って `error` アクションを定義することも出来ます。
......@@ -132,25 +128,22 @@ public function actionError()
}
```
次に `views/site/error.php` に配置されるビューファイルを作成しなければなりません。エラーアクションが [[yii\web\ErrorAction]]
として定義されている場合は、このビューファイルの中で次の変数にアクセスすることが出来ます。
次に `views/site/error.php` に配置されるビューファイルを作成しなければなりません。
エラーアクションが [[yii\web\ErrorAction]] として定義されている場合は、このビューファイルの中で次の変数にアクセスすることが出来ます。
* `name`: エラーの名前。
* `message`: エラーメッセージ。
* `exception`: 例外オブジェクト。これを通じて、更に有用な情報、例えば、HTTP ステータスコード、
エラーコード、エラーコールスタックなどにアクセス出来ます。
> Info|情報: あなたが [ベーシックアプリケーションテンプレート](start-installation.md) または
[アドバンストアプリケーションテンプレート](tutorial-advanced-app.md) を使っている場合は、
エラーアクションとエラービューは、既にあなたのために定義されています。
> Info|情報: あなたが [ベーシックアプリケーションテンプレート](start-installation.md) または [アドバンストアプリケーションテンプレート](tutorial-advanced-app.md) を使っている場合は、エラーアクションとエラービューは、既にあなたのために定義されています。
### エラーのレスポンス形式をカスタマイズする <a name="error-format"></a>
エラーハンドラは、[レスポンス](runtime-responses.md) の形式の設定に従ってエラーを表示します。
[[yii\web\Response::format|レスポンス形式]] が `html` である場合は、直前の項で説明したように、
エラービューまたは例外ビューを使ってエラーを表示します。その他のレスポンス形式の場合は、
エラーハンドラは例外の配列表現を [[yii\web\Response::data]] プロパティに代入し、次に `data` プロパティがレスポンス形式に応じて様々な形式に変換されます。
[[yii\web\Response::format|レスポンス形式]] が `html` である場合は、直前の項で説明したように、エラービューまたは例外ビューを使ってエラーを表示します。
その他のレスポンス形式の場合は、エラーハンドラは例外の配列表現を [[yii\web\Response::data]] プロパティに代入し、次に `data` プロパティがレスポンス形式に応じて様々な形式に変換されます。
例えば、レスポンス形式が `json` である場合は、次のようなレスポンスになります。
```
......@@ -168,8 +161,7 @@ Content-Type: application/json; charset=UTF-8
}
```
エラーのレスポンス形式をカスタマイズするために、アプリケーションのコンフィギュレーションの中で、
`response` コンポーネントの `beforeSend` イベントに反応するハンドラを構成することが出来ます。
エラーのレスポンス形式をカスタマイズするために、アプリケーションの構成情報の中で、`response` コンポーネントの `beforeSend` イベントに反応するハンドラを構成することが出来ます。
```php
return [
......
docs/guide-ja/runtime-logging.md
ロギング
========
Yii は高度なカスタマイズ性と拡張性を持った強力なロギングフレームワークを提供しています。このフレームワークを使用すると、
さまざまな種類のメッセージを記録し、フィルタして、ファイル、データベース、メールなど、さまざまなターゲットに収集することが簡単に出来ます。
Yii は高度なカスタマイズ性と拡張性を持った強力なロギングフレームワークを提供しています。
このフレームワークを使用すると、さまざまな種類のメッセージを記録し、フィルタして、ファイル、データベース、メールなど、さまざまなターゲットに収集することが簡単に出来ます。
Yii のロギングフレームワークを使うためには、下記のステップを踏みます。
* コードのさまざまな場所で [ログメッセージ](#log-messages) を記録する。
* アプリケーションのコンフィギュレーションで [ログターゲット](#log-targets) を構成して、ログメッセージをフィルタしてエクスポートする。
* アプリケーションの構成情報で [ログターゲット](#log-targets) を構成して、ログメッセージをフィルタしてエクスポートする。
* さまざまなターゲット (例えば [Yii デバッガ](tool-debugger.md)) によって、フィルタされエクスポートされたログメッセージを調査する。
この節では、主として最初の二つのステップについて説明します。
......@@ -23,8 +23,7 @@ Yii 縺ｮ繝ｭ繧ｮ繝ｳ繧ｰ繝輔Ξ繝ｼ繝繝ｯ繝ｼ繧ｯ繧剃ｽｿ縺◆繧√↓縺ｯ縲∽ｸ玖ｨ倥繧ｹ繝
* [[Yii::error()]]: 出来るだけ早急に調査すべき致命的なエラーを記録します。
これらのログ記録メソッドは、ログメッセージをさまざまな *重大性レベル* と *カテゴリ* で記録するものです。
これらのメソッドは `function ($message, $category = 'application')` という関数シグニチャを共有しており、`$message`
は記録されるログメッセージを示し、`$category` はログメッセージのカテゴリを示します。
これらのメソッドは `function ($message, $category = 'application')` という関数シグニチャを共有しており、`$message` は記録されるログメッセージを示し、`$category` はログメッセージのカテゴリを示します。
次のコードサンプルは、トレースメッセージをデフォルトのカテゴリである `application` の下に記録するものです。
```php
......@@ -45,8 +44,7 @@ Yii::trace('蟷ｳ蝮庶逶翫險育ｮ励ｒ髢句ｧ', __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()` という式でアクセス可能なシングルトンです。
......@@ -56,13 +54,13 @@ Yii::trace('蟷ｳ蝮庶逶翫險育ｮ励ｒ髢句ｧ', __METHOD__);
## ログターゲット <a name="log-targets"></a>
ログターゲットは [[yii\log\Target]] クラスまたはその子クラスのインスタンスです。ログターゲットは、
ログメッセージを重大性レベルとカテゴリによってフィルタして、何らかの媒体にエクスポートします。
例えば、[[yii\log\DbTarget|データベースターゲット]] は、フィルタされたログメッセージをデータベーステーブルにエクスポートし、
[[yii\log\EmailTarget|メールターゲット]] は、ログメッセージを指定されたメールアドレスにエクスポートします。
ログターゲットは [[yii\log\Target]] クラスまたはその子クラスのインスタンスです。
ログターゲットは、ログメッセージを重大性レベルとカテゴリによってフィルタして、何らかの媒体にエクスポートします。
例えば、[[yii\log\DbTarget|データベースターゲット]] は、フィルタされたログメッセージをデータベーステーブルにエクスポートし、[[yii\log\EmailTarget|メールターゲット]] は、ログメッセージを指定されたメールアドレスにエクスポートします。
一つのアプリケーションの中で複数のログターゲットを登録することが出来ます。そのためには、次のように、
アプリケーションのコンフィギュレーションの中で、`log` [アプリケーションコンポーネント](structure-application-components.md) によってログターゲットを構成します。
一つのアプリケーションの中で複数のログターゲットを登録することが出来ます。
そのためには、次のように、
アプリケーションの構成情報の中で、`log` [アプリケーションコンポーネント](structure-application-components.md) によってログターゲットを構成します。
```php
return [
......@@ -92,18 +90,16 @@ return [
];
```
> Note|注意: `log` コンポーネントは、ログメッセージをターゲットに即座に送付することが出来るように、
[ブートストラップ](runtime-bootstrapping.md) 時にロードされなければなりません。
> Note|注意: `log` コンポーネントは、ログメッセージをターゲットに即座に送付することが出来るように、[ブートストラップ](runtime-bootstrapping.md) 時にロードされなければなりません。
この理由により、上記の例で示されているように、`bootstrap` の配列に `log` をリストアップしています。
上記のコードでは、二つのログターゲットが [[yii\log\Dispatcher::targets]] プロパティに登録されています。
* 最初のターゲットは、エラーと警告のメッセージを選択して、データベーステーブルに保存します。
* 第二のターゲットは、名前が `yii\db\` で始まるカテゴリの下のエラーメッセージを選んで、
`admin@example.com` と `developer@example.com` の両方にメールで送信します。
* 第二のターゲットは、名前が `yii\db\` で始まるカテゴリの下のエラーメッセージを選んで、`admin@example.com` と `developer@example.com` の両方にメールで送信します。
Yii は下記のログターゲットをあらかじめ内蔵しています。その構成方法と使用方法を学ぶためには、
これらのクラスの API ドキュメントを参照してください。
Yii は下記のログターゲットをあらかじめ内蔵しています。
その構成方法と使用方法を学ぶためには、これらのクラスの API ドキュメントを参照してください。
* [[yii\log\DbTarget]]: ログメッセージをデータベーステーブルに保存する。
* [[yii\log\EmailTarget]]: ログメッセージを事前に指定されたメールアドレスに送信する。
......@@ -141,7 +137,7 @@ Yii 縺ｯ荳玖ｨ倥繝ｭ繧ｰ繧ｿ繝ｼ繧ｲ繝ヨ繧偵≠繧峨°縺倥ａ蜀鳩縺励※縺∪縺吶ゅ
プロパティによってブラックリストとして登録することも可能です。
カテゴリの名前がこの配列にあるか、または配列にあるパターンに合致する場合は、メッセージはターゲットによって処理されません。
次のターゲットのコンフィギュレーションは、ターゲットが、`yii\db\*` または `yii\web\HttpException:*`
次のターゲットの構成は、ターゲットが、`yii\db\*` または `yii\web\HttpException:*`
に合致するカテゴリ名を持つエラーおよび警告のメッセージだけを処理すべきこと、ただし、`yii\web\HttpException:404`
は除外すべきことを指定するものです。
......@@ -159,15 +155,14 @@ 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` というカテゴリのエラーメッセージを発生させます。
### メッセージの書式設定 <a name="message-formatting"></a>
ログターゲットはフィルタされたログメッセージを一定の書式でエクスポートします。例えば、[[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
......@@ -179,8 +174,8 @@ Yii 縺ｯ荳玖ｨ倥繝ｭ繧ｰ繧ｿ繝ｼ繧ｲ繝ヨ繧偵≠繧峨°縺倥ａ蜀鳩縺励※縺∪縺吶ゅ
タイムスタンプ [IP アドレス][ユーザ ID][セッション ID][重要性レベル][カテゴリ] メッセージテキスト
```
この書式は、[[yii\log\Target::prefix]] プロパティを構成することでカスタマイズすることが出来ます。[[yii\log\Target::prefix]]
プロパティは、カスタマイズされたメッセージ前置情報を返す PHP コーラブルを値として取ります。
この書式は、[[yii\log\Target::prefix]] プロパティを構成することでカスタマイズすることが出来ます。
[[yii\log\Target::prefix]] プロパティは、カスタマイズされたメッセージ前置情報を返す PHP コーラブルを値として取ります。
例えば、次のコードは、ログターゲットが全てのログメッセージの前にカレントユーザの ID を置くようにさせるものです
(IP アドレスとセッション ID はプライバシー上の理由から削除されています)。
......@@ -198,7 +193,7 @@ Yii 縺ｯ荳玖ｨ倥繝ｭ繧ｰ繧ｿ繝ｼ繧ｲ繝ヨ繧偵≠繧峨°縺倥ａ蜀鳩縺励※縺∪縺吶ゅ
メッセージ前置情報以外にも、ログターゲットは、一群のログメッセージごとに一定のコンテキスト情報を追加します。
既定では、その情報には、次のグローバル PHP 変数、すなわち、`$_GET`、`$_POST`、`$_FILES`、`$_COOKIE`、`$_SESSION` および `$_SERVER` の値が含まれます。
ログターゲットに含ませたいグローバル変数の名前を [[yii\log\Target::logVars]] プロパティに設定することによって、この動作を調整することが出来ます。
例えば、次のログターゲットのコンフィギュレーションは、`$_SERVER` の値だけがログメッセージに追加されるように指定するものです。
例えば、次のログターゲットの構成は、`$_SERVER` の値だけがログメッセージに追加されるように指定するものです。
```php
[
......@@ -213,8 +208,8 @@ Yii 縺ｯ荳玖ｨ倥繝ｭ繧ｰ繧ｿ繝ｼ繧ｲ繝ヨ繧偵≠繧峨°縺倥ａ蜀鳩縺励※縺∪縺吶ゅ
### メッセージのトレースレベル <a name="trace-level"></a>
開発段階では、各ログメッセージがどこから来ているかを知りたい場合がよくあります。これは、次のように、`log`
コンポーネントの [[yii\log\Dispatcher::traceLevel|traceLevel]] プロパティを構成することによって達成できます。
開発段階では、各ログメッセージがどこから来ているかを知りたい場合がよくあります。
これは、次のように、`log` コンポーネントの [[yii\log\Dispatcher::traceLevel|traceLevel]] プロパティを構成することによって達成できます。
```php
return [
......@@ -228,17 +223,16 @@ return [
];
```
上記のアプリケーションのコンフィギュレーションは、[[yii\log\Dispatcher::traceLevel|traceLevel]] を `YII_DEBUG` が on のときは 3、
`YII_DEBUG` が off のときは 0 に設定します。これは、`YII_DEBUG` が on のときは、各ログメッセージに対して、
ログメッセージが記録されたときのコールスタックを最大 3 レベルまで追加し、`YII_DEBUG` が 0 のときはコールスタックを含めない、ということを意味します。
上記のアプリケーションの構成は、[[yii\log\Dispatcher::traceLevel|traceLevel]] を `YII_DEBUG` が on のときは 3、`YII_DEBUG` が off のときは 0 に設定します。
これは、`YII_DEBUG` が on のときは、各ログメッセージに対して、ログメッセージが記録されたときのコールスタックを最大 3 レベルまで追加し、`YII_DEBUG` が 0 のときはコールスタックを含めない、ということを意味します。
> Info|情報: コールスタック情報の取得は軽微な処理ではありません。従って、この機能は開発時またはアプリケーションをデバッグするときに限って使用するべきです。
### メッセージの吐き出しとエクスポート <a name="flushing-exporting"></a>
既に述べたように、ログメッセージは [[yii\log\Logger|ロガーオブジェクト]] によって配列の中に保持されます。この配列のメモリ消費を制限するために、
この配列に一定数のログメッセージが蓄積されるたびに、ロガーは記録されたメッセージを [ログターゲット](#log-targets) に吐き出します。
既に述べたように、ログメッセージは [[yii\log\Logger|ロガーオブジェクト]] によって配列の中に保持されます。
この配列のメモリ消費を制限するために、この配列に一定数のログメッセージが蓄積されるたびに、ロガーは記録されたメッセージを [ログターゲット](#log-targets) に吐き出します。
この数は、`log` コンポーネントの [[yii\log\Dispatcher::flushInterval|flushInterval]] プロパティを構成することによってカスタマイズすることが出来ます。
......@@ -257,8 +251,8 @@ return [
> Info|情報: メッセージの吐き出しは、アプリケーションの終了時にも実行されます。これによって、ログターゲットが完全なログメッセージを受け取ることが保証されます。
[[yii\log\Logger|ロガーオブジェクト]] が [ログターゲット](#log-targets) にログメッセージを吐き出しても、ログメッセージはただちにはエクスポートされません。
そうではなく、ログターゲットが一定数のフィルタされたメッセージを蓄積して初めて、メッセージのエクスポートが発生します。この数は、下記のように、個々の [ログターゲット](#log-targets) の [[yii\log\Target::exportInterval|exportInterval]]
プロパティを構成することによってカスタマイズすることが出来ます。
そうではなく、ログターゲットが一定数のフィルタされたメッセージを蓄積して初めて、メッセージのエクスポートが発生します。
この数は、下記のように、個々の [ログターゲット](#log-targets) の [[yii\log\Target::exportInterval|exportInterval]] プロパティを構成することによってカスタマイズすることが出来ます。
```php
[
......@@ -267,8 +261,7 @@ return [
]
```
デフォルトの状態では、吐き出しとエクスポートの間隔の設定のために、`Yii::trace()` やその他のログ記録メソッドを呼んでも、
ただちには、ログメッセージはログターゲットに出現しません。
デフォルトの状態では、吐き出しとエクスポートの間隔の設定のために、`Yii::trace()` やその他のログ記録メソッドを呼んでも、ただちには、ログメッセージはログターゲットに出現しません。
このことは、長時間にわたって走るコンソールアプリケーションでは、問題になる場合もあります。
各ログメッセージがただちにログターゲットに出現するようにするためには、下記のように、[[yii\log\Dispatcher::flushInterval|flushInterval]]
と [[yii\log\Target::exportInterval|exportInterval]] の両方を 1 に設定しなければなりません。
......@@ -325,10 +318,10 @@ return [
### 新しいターゲットを作る <a name="new-targets"></a>
新しいログターゲットを作ることは非常に単純なことです。必要なことは、主として、[[yii\log\Target::messages]] 配列の中身を指定された媒体に送出する
[[yii\log\Target::export()]] メソッドを実装することです。各メッセージに書式を設定するためには、
[[yii\log\Target::formatMessage()]] を呼ぶことが出来ます。
更なる詳細については、Yii リリースに含まれているログターゲットクラスのどれか一つを参照してください。
新しいログターゲットを作ることは非常に単純なことです。
必要なことは、主として、[[yii\log\Target::messages]] 配列の中身を指定された媒体に送出する [[yii\log\Target::export()]] メソッドを実装することです。
各メッセージに書式を設定するためには、[[yii\log\Target::formatMessage()]] を呼ぶことが出来ます。
詳細については、Yii リリースに含まれているログターゲットクラスのどれか一つを参照してください。
## パフォーマンスプロファイリング <a name="performance-profiling"></a>
......@@ -346,8 +339,8 @@ return [
\Yii::endProfile('myBenchmark');
```
ここで `myBenchmark` はコードブロックを特定するユニークなトークンを表します。後でプロファイリング結果を検査するときに、
このトークンを使って、対応するコードブロックによって消費された時間を調べます。
ここで `myBenchmark` はコードブロックを特定するユニークなトークンを表します。
後でプロファイリング結果を検査するときに、このトークンを使って、対応するコードブロックによって消費された時間を調べます。
`beginProfile` と `endProfile` のペアが適正な入れ子になっているように確認することは、非常に重要なことです。
例えば、
......
docs/guide-ja/runtime-overview.md
......@@ -4,7 +4,7 @@
Yii のアプリケーションがリクエストを処理するときは、毎回、同じような作業の流れを経験します。
1. ユーザが [エントリスクリプト](structure-entry-scripts.md) `web/index.php` にリクエストをします。
2. エントリスクリプトは、アプリケーションの [コンフィギュレーション](concept-configurations.md) をロードして、リクエストを処理するための [アプリケーション](structure-applications.md) のインスタンスを作成します。
2. エントリスクリプトは、アプリケーションの [構成情報](concept-configurations.md) をロードして、リクエストを処理するための [アプリケーション](structure-applications.md) のインスタンスを作成します。
3. アプリケーションは、[リクエスト](runtime-requests.md) アプリケーションコンポーネントの助けを借りて、リクエストされた [ルート](runtime-routing.md) を解決します。
4. アプリケーションはリクエストを処理するための [コントローラ](structure-controllers.md) のインスタンスを作成します。
5. コントローラは [アクション](structure-controllers.md) のインスタンスを作成して、アクションのためのフィルタを実行します。
......
docs/guide-ja/runtime-requests.md
リクエスト
==========
アプリケーションに対するリクエストは、リクエストのパラメータ、HTTP ヘッダ、クッキーなどの情報を提供する [[yii\web\Request]]
オブジェクトの形で表されます。与えられたリクエストに対応するリクエストオブジェクトには、
既定では [[yii\web\Request]] のインスタンスである `request` [アプリケーションコンポーネント](structure-application-components.md)
を通じてアクセスすることが出来ます。この節では、アプリケーションの中でこのコンポーネントをどのように利用できるかを説明します。
アプリケーションに対するリクエストは、リクエストのパラメータ、HTTP ヘッダ、クッキーなどの情報を提供する [[yii\web\Request]] オブジェクトの形で表されます。
与えられたリクエストに対応するリクエストオブジェクトには、既定では [[yii\web\Request]] のインスタンスである `request` [アプリケーションコンポーネント](structure-application-components.md) を通じてアクセスすることが出来ます。
この節では、アプリケーションの中でこのコンポーネントをどのように利用できるかを説明します。
## リクエストのパラメータ <a name="request-parameters"></a>
リクエストのパラメータを取得するためには、`request` コンポーネントの [[yii\web\Request::get()|get()]] および
[[yii\web\Request::post()|post()]] メソッドを呼ぶことが出来ます。これらは、ぞれぞれ、`$_GET` と `$_POST` の値を返します。例えば、
リクエストのパラメータを取得するためには、`request` コンポーネントの [[yii\web\Request::get()|get()]] および [[yii\web\Request::post()|post()]] メソッドを呼ぶことが出来ます。
これらは、ぞれぞれ、`$_GET` と `$_POST` の値を返します。例えば、
```php
$request = Yii::$app->request;
......@@ -34,13 +33,12 @@ $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)
によって送信されたパラメータを読み出さなければならないことがよくあります。そういうパラメータは [[yii\web\Request::getBodyParam()]]
メソッドを呼ぶことで取得することが出来ます。例えば、
[RESTful API](rest-quick-start.md) を実装するときは、PUT、PATCH またはその他の [リクエストメソッド](#request-methods) によって送信されたパラメータを読み出さなければならないことがよくあります。
そういうパラメータは [[yii\web\Request::getBodyParam()]] メソッドを呼ぶことで取得することが出来ます。
例えば、
```php
$request = Yii::$app->request;
......@@ -76,8 +74,7 @@ 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` を返します。
......@@ -93,8 +90,7 @@ if ($request->isPut) { // リクエストメソッドは PUT }
## HTTP ヘッダ <a name="http-headers"></a>
[[yii\web\Request::headers]] プロパティによって返される [[yii\web\HeaderCollection|header コレクション]]
を通じて、HTTP ヘッダ情報を取得することが出来ます。例えば、
[[yii\web\Request::headers]] プロパティによって返される [[yii\web\HeaderCollection|header コレクション]] を通じて、HTTP ヘッダ情報を取得することが出来ます。例えば、
```php
// $headers は yii\web\HeaderCollection のオブジェクト
......@@ -106,7 +102,8 @@ $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` ヘッダの値を返します。
......@@ -115,20 +112,16 @@ if ($headers->has('User-Agent')) { // User-Agent ヘッダが在る }
* [[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]] フィルタを使用して、レスポンスにおいてどのコンテントタイプと言語を使うべきかを動的に決定することも出来ます。
このフィルタは、上記で説明したプロパティとメソッドの上に、コンテントネゴシエーションを実装しています。
## クライアント情報 <a name="client-information"></a>
クライアントマシンのホスト名と 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;
......
docs/guide-ja/runtime-responses.md
レスポンス
==========
アプリケーションは [リクエスト](runtime-requests.md) の処理を完了すると、[[yii\web\Response|レスポンス]] オブジェクトを生成して、
エンドユーザに送信します。レスポンスオブジェクトは、HTTP ステータスコード、HTTP ヘッダ、HTTP ボディなどの情報を含みます。
ウェブアプリケーション開発の最終的な目的は、本質的には、さまざまなリクエストに対してそのようなレスポンスオブジェクトを
作成することにあります。
アプリケーションは [リクエスト](runtime-requests.md) の処理を完了すると、[[yii\web\Response|レスポンス]] オブジェクトを生成して、エンドユーザに送信します。
レスポンスオブジェクトは、HTTP ステータスコード、HTTP ヘッダ、HTTP ボディなどの情報を含みます。
ウェブアプリケーション開発の最終的な目的は、本質的には、さまざまなリクエストに対してそのようなレスポンスオブジェクトを作成することにあります。
ほとんどの場合は、主として `response` [アプリケーションコンポーネント](structure-application-components.md) を使用すべきです。
このコンポーネントは、既定では、[[yii\web\Response]] のインスタンスです。しかしながら、Yii は、以下で説明するように、
あなた自身のレスポンスオブジェクトを作成してエンドユーザに送信することも許容しています。
このコンポーネントは、既定では、[[yii\web\Response]] のインスタンスです。
しかしながら、Yii は、以下で説明するように、あなた自身のレスポンスオブジェクトを作成してエンドユーザに送信することも許容しています。
この節では、レスポンスを構成してエンドユーザに送信する方法を説明します。
## ステータスコード <a name="status-code"></a>
レスポンスを作成するときに最初にすることの一つは、リクエストが成功裡に処理されたかどうかを記述することです。そのためには、
[[yii\web\Response::statusCode]] プロパティに有効な [HTTP ステータスコード](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
の一つを設定します。例えば、下記のように、リクエストの処理が成功したことを示すために、ステータスコードを 200 に設定します。
レスポンスを作成するときに最初にすることの一つは、リクエストが成功裡に処理されたかどうかを記述することです。
そのためには、[[yii\web\Response::statusCode]] プロパティに有効な [HTTP ステータスコード](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) の一つを設定します。
例えば、下記のように、リクエストの処理が成功したことを示すために、ステータスコードを 200 に設定します。
```php
Yii::$app->response->statusCode = 200;
```
けれども、たいていの場合、ステータスコードを明示的に設定する必要はありません。これは、[[yii\web\Response::statusCode]]
の既定値が 200 であるからです。そして、リクエストが失敗したことを示したいときは、下記のように、適切な HTTP 例外を投げることが出来ます。
けれども、たいていの場合、ステータスコードを明示的に設定する必要はありません。
これは、[[yii\web\Response::statusCode]] の既定値が 200 であるからです。
そして、リクエストが失敗したことを示したいときは、下記のように、適切な HTTP 例外を投げることが出来ます。
```php
throw new \yii\web\NotFoundHttpException;
......@@ -47,8 +47,9 @@ 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);
```
......@@ -56,8 +57,8 @@ throw new \yii\web\HttpException(402);
## HTTP ヘッダ <a name="http-headers"></a>
`response` コンポーネントの [[yii\web\Response::headers|ヘッダコレクション]] を操作することによって、
HTTP ヘッダを送信することが出来ます。例えば、
`response` コンポーネントの [[yii\web\Response::headers|ヘッダコレクション]] を操作することによって、HTTP ヘッダを送信することが出来ます。
例えば、
```php
$headers = Yii::$app->response->headers;
......@@ -72,24 +73,23 @@ $headers->set('Pragma', 'no-cache');
$values = $headers->remove('Pragma');
```
> Info|情報: ヘッダ名は大文字小文字を区別しません。そして、新しく登録されたヘッダは、
[[yii\web\Response::send()]] メソッドが呼ばれるまで送信されません。
> Info|情報: ヘッダ名は大文字小文字を区別しません。
そして、新しく登録されたヘッダは、[[yii\web\Response::send()]] メソッドが呼ばれるまで送信されません。
## レスポンスボディ <a name="response-body"></a>
ほとんどのレスポンスは、エンドユーザに対して表示したい内容を示すボディを持っていなければなりません。
既にフォーマットされたボディの文字列を持っている場合は、それをレスポンスの [[yii\web\Response::content]]
プロパティに割り付けることが出来ます。例えば、
既にフォーマットされたボディの文字列を持っている場合は、それをレスポンスの [[yii\web\Response::content]] プロパティに割り付けることが出来ます。
例えば、
```php
Yii::$app->response->content = 'hello world!';
```
データをエンドユーザに送信する前にフォーマットする必要がある場合は、[[yii\web\Response::format|format]] と [[yii\web\Response::data|data]]
の両方のプロパティをセットしなければなりません。[[yii\web\Response::format|format]]
プロパティは [[yii\web\Response::data|data]] がどの形式でフォーマットされるべきかを指定するものです。
データをエンドユーザに送信する前にフォーマットする必要がある場合は、[[yii\web\Response::format|format]] と [[yii\web\Response::data|data]] の両方のプロパティをセットしなければなりません。
[[yii\web\Response::format|format]] プロパティは [[yii\web\Response::data|data]] がどの形式でフォーマットされるべきかを指定するものです。
例えば、
```php
......@@ -98,9 +98,9 @@ $response->format = \yii\web\Response::FORMAT_JSON;
$response->data = ['message' => 'hello world'];
```
Yii は下記の形式を初めからサポートしています。それぞれ、[[yii\web\ResponseFormatterInterface|フォーマッタ]] クラスとして実装されています。
[[yii\web\Response::formatters]] プロパティを構成することで、これらのフォーマッタをカスタマイズしたり、
または、新しいフォーマッタを追加することが出来ます。
Yii は下記の形式を初めからサポートしています。
それぞれ、[[yii\web\ResponseFormatterInterface|フォーマッタ]] クラスとして実装されています。
[[yii\web\Response::formatters]] プロパティを構成することで、これらのフォーマッタをカスタマイズしたり、または、新しいフォーマッタを追加することが出来ます。
* [[yii\web\Response::FORMAT_HTML|HTML]]: [[yii\web\HtmlResponseFormatter]] によって実装
* [[yii\web\Response::FORMAT_XML|XML]]: [[yii\web\XmlResponseFormatter]] によって実装
......@@ -108,8 +108,8 @@ Yii 縺ｯ荳玖ｨ倥蠖｢蠑上ｒ蛻昴ａ縺九ｉ繧ｵ繝昴繝医＠縺ｦ縺∪縺吶ゅ◎繧後◇繧後
* [[yii\web\Response::FORMAT_JSONP|JSONP]]: [[yii\web\JsonResponseFormatter]] によって実装
* [[yii\web\Response::FORMAT_RAW|RAW]]: 書式を何も適用せずにレスポンスを送信したいときは、このフォーマットを使用
レスポンスボディは、上記のように、明示的に設定することも出来ますが、たいていの場合は、[アクション](structure-controllers.md)
メソッドの返り値によって暗黙のうちに設定することが出来ます。よくあるユースケースは下記のようなものになります。
レスポンスボディは、上記のように、明示的に設定することも出来ますが、たいていの場合は、[アクション](structure-controllers.md) メソッドの返り値によって暗黙のうちに設定することが出来ます。
よくあるユースケースは下記のようなものになります。
```php
public function actionIndex()
......@@ -118,11 +118,12 @@ public function actionIndex()
}
```
上記の `index` アクションは、`index` ビューのレンダリング結果を返しています。返された値は `response`
コンポーネントによって受け取られ、フォーマットされてエンドユーザに送信されます。
上記の `index` アクションは、`index` ビューのレンダリング結果を返しています。
返された値は `response` コンポーネントによって受け取られ、フォーマットされてエンドユーザに送信されます。
デフォルトのレスポンス形式が [[yii\web\Response::FORMAT_HTML|HTML]] であるため、アクションメソッドの中では文字列を返すだけにすべきです。
別のレスポンス形式を使いたい場合は、データを返す前にレスポンス形式を設定しなければなりません。例えば、
別のレスポンス形式を使いたい場合は、データを返す前にレスポンス形式を設定しなければなりません。
例えば、
```php
public function actionInfo()
......@@ -135,9 +136,8 @@ public function actionInfo()
}
```
既に述べたように、デフォルトの `response` アプリケーションコンポーネントを使う代りに、
自分自身のレスポンスオブジェクトを作成してエンドユーザに送信することも出来ます。そうするためには、次のように、
アクションメソッドの中でそのようなオブジェクトを返します。
既に述べたように、デフォルトの `response` アプリケーションコンポーネントを使う代りに、自分自身のレスポンスオブジェクトを作成してエンドユーザに送信することも出来ます。
そうするためには、次のように、アクションメソッドの中でそのようなオブジェクトを返します。
```php
public function actionInfo()
......@@ -153,19 +153,19 @@ public function actionInfo()
}
```
> Note|注意: 自分自身のレスポンスオブジェクトを作成しようとする場合は、アプリケーションのコンフィギュレーションで `response`
コンポーネントのために設定したコンフィギュレーションを利用することは出来ません。しかし、 [依存の注入](concept-di-container.md) を使えば、
共通のコンフィギュレーションをあなたの新しいレスポンスオブジェクトに適用することが出来ます。
> Note|注意: 自分自身のレスポンスオブジェクトを作成しようとする場合は、アプリケーションの構成情報で `response` コンポーネントのために設定した構成情報を利用することは出来ません。
しかし、 [依存の注入](concept-di-container.md) を使えば、 共通の構成情報をあなたの新しいレスポンスオブジェクトに適用することが出来ます。
## ブラウザのリダイレクト <a name="browser-redirection"></a>
ブラウザのリダイレクトは `Location` HTTP ヘッダの送信に依存しています。この機能は通常よく使われるものであるため、
Yii はこれについて特別のサポートを提供しています。
ブラウザのリダイレクトは `Location` HTTP ヘッダの送信に依存しています。
この機能は通常よく使われるものであるため、Yii はこれについて特別のサポートを提供しています。
[[yii\web\Response::redirect()]] メソッドを呼ぶことによって、ユーザのブラウザをある URL にリダイレクトすることが出来ます。
このメソッドは与えられた URL を持つ適切な `Location` ヘッダを設定して、レスポンスオブジェクトそのものを返します。
アクションメソッドの中では、そのショートカット版である [[yii\web\Controller::redirect()]] を呼ぶことが出来ます。例えば、
アクションメソッドの中では、そのショートカット版である [[yii\web\Controller::redirect()]] を呼ぶことが出来ます。
例えば、
```php
public function actionOld()
......@@ -174,11 +174,10 @@ public function actionOld()
}
```
上記のコードでは、アクションメソッドが `redirect()` メソッドの結果を返しています。前に説明したように、
アクションメソッドによって返されるレスポンスオブジェクトは、エンドユーザに送信されるレスポンスとして使用されることになります。
上記のコードでは、アクションメソッドが `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();
......@@ -192,17 +191,15 @@ public function actionOld()
この問題を解決するために、[[yii\web\Response::redirect()]] メソッドは `X-Redirect` ヘッダにリダイレクト先 URL を値としてセットします。
そして、クライアントサイドで、このヘッダの値を読み、それに応じてブラウザをリダイレクトする JavaScript を書くことが出来ます。
> Info|情報: Yii には `yii.js` という JavaScript ファイルが付いています。これは、よく使われる一連の JavaScript 機能を提供するもので、
その中には `X-Redirect` ヘッダに基づくブラウザのリダイレクトも含まれています。従って、あなたが
([[yii\web\YiiAsset]] アセットバンドルを登録して) この JavaScript ファイルを使うつもりなら、
AJAX のリダイレクトをサポートするためには、何も書く必要がなくなります。
> Info|情報: Yii には `yii.js` という JavaScript ファイルが付いています。
これは、よく使われる一連の JavaScript 機能を提供するもので、その中には `X-Redirect` ヘッダに基づくブラウザのリダイレクトも含まれています。
従って、あなたが ([[yii\web\YiiAsset]] アセットバンドルを登録して) この JavaScript ファイルを使うつもりなら、AJAX のリダイレクトをサポートするためには、何も書く必要がなくなります。
## ファイルを送信する <a name="sending-files"></a>
ブラウザのリダイレクトと同じように、ファイルの送信という機能も特定の HTTP ヘッダに依存しています。
Yii はさまざまなファイル送信の必要をサポートするための一連のメソッドを提供しています。それらはすべて、
HTTP range ヘッダに対するサポートを内蔵しています。
Yii はさまざまなファイル送信の必要をサポートするための一連のメソッドを提供しています。それらはすべて、HTTP range ヘッダに対するサポートを内蔵しています。
* [[yii\web\Response::sendFile()]]: 既存のファイルをクライアントに送信する
* [[yii\web\Response::sendContentAsFile()]]: テキストの文字列をファイルとしてクライアントに送信する
......@@ -219,18 +216,17 @@ public function actionDownload()
}
```
ファイル送信メソッドをアクションメソッド以外の場所で呼ぶ場合は、その後で [[yii\web\Response::send()]] メソッドも呼んで、
レスポンスに余計なコンテンツが追加されないことを保証すべきです。
ファイル送信メソッドをアクションメソッド以外の場所で呼ぶ場合は、その後で [[yii\web\Response::send()]] メソッドも呼んで、レスポンスに余計なコンテンツが追加されないことを保証すべきです。
```php
\Yii::$app->response->sendFile('path/to/file.txt')->send();
```
ウェブサーバには、*X-Sendfile* と呼ばれる特別なファイル送信をサポートするものがあります。アイデアとしては、
ファイルに対するリクエストをウェブサーバにリダイレクトして、ウェブサーバに直接にファイルを送信させる、というものです。
ウェブサーバには、*X-Sendfile* と呼ばれる特別なファイル送信をサポートするものがあります。
アイデアとしては、ファイルに対するリクエストをウェブサーバにリダイレクトして、ウェブサーバに直接にファイルを送信させる、というものです。
その結果として、ウェブサーバがファイルを送信している間でも、ウェブアプリケーションは早期に終了することが出来るようになります。
この機能を使うために、[[yii\web\Response::xSendFile()]] を呼ぶことが出来ます。次のリストは、
よく使われるいくつかのウェブサーバにおいて `X-Sendfile` 機能を有効にする方法を要約するものです。
この機能を使うために、[[yii\web\Response::xSendFile()]] を呼ぶことが出来ます。
次のリストは、よく使われるいくつかのウェブサーバにおいて `X-Sendfile` 機能を有効にする方法を要約するものです。
- Apache: [X-Sendfile](http://tn123.org/mod_xsendfile)
- Lighttpd v1.4: [X-LIGHTTPD-send-file](http://redmine.lighttpd.net/projects/lighttpd/wiki/X-LIGHTTPD-send-file)
......@@ -242,8 +238,8 @@ public function actionDownload()
## レスポンスを送信する <a name="sending-response"></a>
レスポンスの中のコンテントは、[[yii\web\Response::send()]] メソッドが呼ばれるまでは、エンドユーザに向けて送信されません。
既定では、このメソッドは [[yii\base\Application::run()]] の最後で自動的に呼ばれます。しかし、
このメソッドを明示的に呼んで、強制的にレスポンスを即座に送信することも可能です。
既定では、このメソッドは [[yii\base\Application::run()]] の最後で自動的に呼ばれます。
しかし、このメソッドを明示的に呼んで、強制的にレスポンスを即座に送信することも可能です。
[[yii\web\Response::send()]] メソッドは次のステップを踏んでレスポンスを送出します。
......@@ -258,5 +254,5 @@ public function actionDownload()
[[yii\web\Response::send()]] メソッドが一度呼び出された後では、このメソッドに対する更なる呼び出しは無視されます。
このことは、いったんレスポンスが送出された後では、それにコンテントを追加することは出来なくなる、ということを意味します。
ごらんのように、the [[yii\web\Response::send()]] メソッドはいくつかの有用なイベントをトリガします。これらのイベントに反応することによって、
レスポンスを調整したり修飾したりすることが出来ます。
ごらんのように、the [[yii\web\Response::send()]] メソッドはいくつかの有用なイベントをトリガします。
これらのイベントに反応することによって、レスポンスを調整したり修飾したりすることが出来ます。
docs/guide-ja/runtime-routing.md
ルーティングと URL 生成
=======================
Yii のアプリケーションがリクエストされた URL の処理を開始するときに、最初に実行するステップは URL を解析して
[ルート](structure-controllers.md#routes) にすることです。次に、リクエストを処理するために、このルートを使って、
対応する [コントローラアクション](structure-controllers.md) のインスタンスが作成されます。
Yii のアプリケーションがリクエストされた URL の処理を開始するときに、最初に実行するステップは URL を解析して [ルート](structure-controllers.md#routes) にすることです。
次に、リクエストを処理するために、このルートを使って、対応する [コントローラアクション](structure-controllers.md) のインスタンスが作成されます。
このプロセスの全体が *ルーティング* と呼ばれます。
ルーティングの逆のプロセスが *URL 生成* と呼ばれます。これは、与えられたルートとそれに結び付いたクエリパラメータから
URL を生成するものです。生成された URL が後でリクエストされたとき、ルーティングのプロセスは、その URL を解決して、
元のルートとクエリパラメータに戻すことが出来ます。
ルーティングの逆のプロセスが *URL 生成* と呼ばれます。
これは、与えられたルートとそれに結び付いたクエリパラメータからURL を生成するものです。
生成された URL が後でリクエストされたとき、ルーティングのプロセスは、その URL を解決して、元のルートとクエリパラメータに戻すことが出来ます。
ルーティングと URL 生成について責任を持つ主要コンポーネントが [[yii\web\UrlManager|URL マネージャ]] であり、`urlManager`
アプリケーションコンポーネントとして登録されているものです。[[yii\web\UrlManager|URL マネージャ]] は、入ってくるリクエストを
ルートとそれに結び付いたクエリパラメータとして解析するための [[yii\web\UrlManager::parseRequest()|parseRequest()]] メソッドと、
与えられたルートとそれに結び付いたクエリパラメータから URL を生成するための [[yii\web\UrlManager::createUrl()|createUrl()]]
メソッドを提供するものです。
ルーティングと URL 生成について責任を持つ主要コンポーネントが [[yii\web\UrlManager|URL マネージャ]] であり、`urlManager` アプリケーションコンポーネントとして登録されているものです。
[[yii\web\UrlManager|URL マネージャ]] は、入ってくるリクエストをルートとそれに結び付いたクエリパラメータとして解析するための [[yii\web\UrlManager::parseRequest()|parseRequest()]] メソッドと、
与えられたルートとそれに結び付いたクエリパラメータから URL を生成するための [[yii\web\UrlManager::createUrl()|createUrl()]] メソッドを提供するものです。
アプリケーションコンフィギュレーションの `urlManager` コンポーネントを構成することによって、既存のアプリケーションコードを
修正することなく、任意の URL 形式をアプリケーションに認識させることが出来ます。例えば、`post/view` アクションのための URL
を生成するために、次のコードを使うことが出来ます:
アプリケーション構成情報の `urlManager` コンポーネントを構成することによって、既存のアプリケーションコードを修正することなく、任意の URL 形式をアプリケーションに認識させることが出来ます。
例えば、`post/view` アクションのための URL を生成するためには、次のコードを使うことが出来ます。
```php
use yii\helpers\Url;
......@@ -27,8 +23,8 @@ use yii\helpers\Url;
$url = Url::to(['post/view', 'id' => 100]);
```
このコードによって生成される URL は、`urlManager` のコンフィギュレーションに応じて、下記の形式のうちの一つ (またはその他の形式)
になります。そしてまた、生成された URL が後でリクエストされたときには、解析されて元のルートとクエリパラメータに戻されます。
このコードによって生成される URL は、`urlManager` の構成に応じて、下記の形式のうちの一つ (またはその他の形式) になります。
そしてまた、生成された URL が後でリクエストされたときには、解析されて元のルートとクエリパラメータに戻されます。
```
/index.php?r=post/view&id=100
......@@ -39,18 +35,15 @@ $url = Url::to(['post/view', 'id' => 100]);
## URL 形式 <a name="url-formats"></a>
[[yii\web\UrlManager|URL マネージャ]] は二つの URL 形式をサポートします: デフォルトの URL 形式と、綺麗な URL 形式です。
[[yii\web\UrlManager|URL マネージャ]] は二つの URL 形式、すなわち、デフォルトの URL 形式と、綺麗な URL 形式をサポートします。
既定の URL 形式は、`r` というクエリパラメータを使用してルートを表し、通常のクエリパラメータを使用してルートに結び付いたクエリパラメータを表します。
デフォルトの URL 形式は、`r` というクエリパラメータを使用してルートを表し、通常のクエリパラメータを使用してルートに結び付いたクエリパラメータを表します。
例えば、`/index.php?r=post/view&id=100` という URL は、`post/view` というルートと、`id` というクエリパラメータが 100 であることを表します。
既定の URL 形式は、[[yii\web\UrlManager|URL マネージャ]] についてのコンフィギュレーションを何も必要とせず、
ウェブサーバの設定がどのようなものでも動作します。
デフォルトの URL 形式は、[[yii\web\UrlManager|URL マネージャ]] についての構成を何も必要とせず、ウェブサーバの設定がどのようなものでも動作します。
綺麗な URL 形式は、エントリスクリプトの名前に続く追加のパスを使用してルートとそれに結び付いたクエリパラメータを表します。
例えば、`/index.php/post/100` という URL の追加のパスは `/post/100` ですが、適切な [[yii\web\UrlManager::rules|URL 規則]]
があれば、この URL が `post/view` というルートと `id` というクエリパラメータが 100 であることを表すことが出来ます。
綺麗な URL 形式を使用するためには、URL をどのように表現すべきかという実際の要求に従って、一連の [[yii\web\UrlManager::rules|URL 規則]]
を設計する必要があります。
綺麗な URL 形式は、エントリスクリプトの名前に続く追加のパスを使用して、ルートとそれに結び付いたクエリパラメータを表します。
例えば、`/index.php/post/100` という URL の追加のパスは `/post/100` ですが、適切な [[yii\web\UrlManager::rules|URL 規則]] があれば、この URL が `post/view` というルートと `id` というクエリパラメータが 100 であることを表すことが出来ます。
綺麗な URL 形式を使用するためには、URL をどのように表現すべきかという実際の要求に従って、一連の [[yii\web\UrlManager::rules|URL 規則]] を設計する必要があります。
この二つの URL 形式は、[[yii\web\UrlManager|URL マネージャ]] の [[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]]
プロパティを ON/OFF することによって、他のアプリケーションコードを少しも変えることなく、切り替えることが出来ます。
......@@ -58,43 +51,41 @@ $url = Url::to(['post/view', 'id' => 100]);
## ルーティング <a name="routing"></a>
ルーティングは二つのステップを含みます。最初のステップでは、入ってくるリクエストが解析されて、ルートとそれに結び付いたクエリパラメータに分解されます。そして、第二のステップでは、解析されたルートに対応する [コントローラアクション](structure-controllers.md)
がリクエストを処理するために生成されます。
ルーティングは二つのステップを含みます。最初のステップでは、入ってくるリクエストが解析されて、ルートとそれに結び付いたクエリパラメータに分解されます。
そして、第二のステップでは、解析されたルートに対応する [コントローラアクション](structure-controllers.md) がリクエストを処理するために生成されます。
既定の URL 形式を使っている場合は、リクエストからルートを解析することは、`r` という名前の `GET` クエリパラメータを取得するだけの
簡単なことです。
デフォルトの URL 形式を使っている場合は、リクエストからルートを解析することは、`r` という名前の `GET` クエリパラメータを取得するだけの簡単なことです。
綺麗な URL 形式を使っている場合は、[[yii\web\UrlManager|URL マネージャ]] が登録されている [[yii\web\UrlManager::rules|URL 規則]]
を調べます。合致する規則が見つかれば、リクエストをルートに解決することが出来ます。そういう規則が見つからなかったら、
[[yii\web\NotFoundHttpException]] 例外が投げられます。
綺麗な URL 形式を使っている場合は、[[yii\web\UrlManager|URL マネージャ]] が、登録されている [[yii\web\UrlManager::rules|URL 規則]] を調べます。
合致する規則が見つかれば、リクエストをルートに解決することが出来ます。
合致する規則が見つからなかったら、[[yii\web\NotFoundHttpException]] 例外が投げられます。
いったんリクエストからルートが解析されたら、今度はルートによって特定されるコントローラアクションを生成する番です。
ルートはその中にあるスラッシュによって複数の部分に分けられます。例えば、`site/index` は `site` と `index` に分割されます。
その各部分がモジュール、コントローラ、アクションを参照する ID となります。アプリケーションは、ルートの中の最初の部分から始めて、
下記のステップを踏んで、モジュール (もし有れば)、コントローラ、アクションを生成します。
その各部分がモジュール、コントローラ、アクションを参照する ID となります。
アプリケーションは、ルートの中の最初の部分から始めて、下記のステップを踏んで、モジュール (もし有れば)、コントローラ、アクションを生成します。
1. アプリケーションをカレントモジュールとして設定します。
2. カレントモジュールの [[yii\base\Module::controllerMap|コントローラマップ]] がカレント ID を含むかどうかを調べます。
もしそうであれば、マップの中で見つかったコントローラコンフィギュレーションに従ってコントローラオブジェクトが生成され、
ルートの残りの部分を処理するために、ステップ 5 に飛びます。
もしそうであれば、マップの中で見つかったコントローラのオブジェクトが構成情報に従って生成されます。
そして、ルートの残りの部分を処理するために、ステップ 5 に飛びます。
3. ID がカレントモジュールの [[yii\base\Module::modules|modules]] プロパティのリストに挙げられたモジュールを指すかどうかを調べます。
もしそうであれば、モジュールのリストで見つかったコンフィギュレーションに従ってモジュールが生成されます。そして、ステップ 2
に戻って、新しく生成されたモジュールのコンテキストのもとで、ルートの次の部分を処理します。
4. ID をコントローラ ID として扱ってコントローラオブジェクトを生成します。そしてルートの残りの部分を持って次のステップに進みます。
5. コントローラは、[[yii\base\Controller::actions()|アクションマップ]] の中にカレント ID があるかどうかを調べます。もし有れば、
マップの中で見つかったコンフィギュレーションに従ってアクションを生成します。もし無ければ、カレント ID
に対応するアクションメソッドによって定義されるインラインアクションを生成しようと試みます。
もしそうであれば、モジュールのリストで見つかったモジュールが構成情報に従って生成されます。
そして、ステップ 2 に戻って、新しく生成されたモジュールのコンテキストのもとで、ルートの次の部分を処理します。
4. ID をコントローラ ID として扱ってコントローラオブジェクトを生成します。
そしてルートの残りの部分を持って次のステップに進みます。
5. コントローラは、[[yii\base\Controller::actions()|アクションマップ]] の中にカレント ID があるかどうかを調べます。
もし有れば、マップの中で見つかったアクションを構成情報に従って生成します。
もし無ければ、カレント ID に対応するアクションメソッドによって定義されるインラインアクションを生成しようと試みます。
上記のステップの中で、何かエラーが発生すると、[[yii\web\NotFoundHttpException]] が投げられて、
ルーティングのプロセスが失敗したことが示されます。
上記のステップの中で、何かエラーが発生すると、[[yii\web\NotFoundHttpException]] が投げられて、ルーティングのプロセスが失敗したことが示されます。
### デフォルトルート <a name="default-route"></a>
リクエストから解析されたルートが空っぽになった場合は、いわゆる *デフォルトルート* が代りに使用されることになります。既定では、
デフォルトルートは `site/index` であり、`site` コントローラの `index` アクションを指します。デフォルトルートは、次のように、
アプリケーションコンフィギュレーションの中でアプリケーションの [[yii\web\Application::defaultRoute|defaultRoute]]
プロパティを構成することによって、カスタマイズすることが出来ます。
リクエストから解析されたルートが空っぽになった場合は、いわゆる *デフォルトルート* が代りに使用されることになります。
既定では、デフォルトルートは `site/index` であり、`site` コントローラの `index` アクションを指します。
デフォルトルートは、次のように、アプリケーションの構成情報の中でアプリケーションの [[yii\web\Application::defaultRoute|defaultRoute]] プロパティを構成することによって、カスタマイズすることが出来ます。
```php
[
......@@ -107,8 +98,7 @@ $url = Url::to(['post/view', 'id' => 100]);
### `catchAll` ルート <a name="catchall-route"></a>
たまには、ウェブアプリケーションを一時的にメンテナンスモードにして、全てのリクエストに対して同じ「お知らせ」のページを表示したいことがあるでしょう。
この目的を達する方法はたくさんありますが、最も簡単な方法の一つは、次のように、
アプリケーションのコンフィギュレーションの中で [[yii\web\Application::catchAll]] プロパティを構成することです。
この目的を達する方法はたくさんありますが、最も簡単な方法の一つは、次のように、アプリケーションの構成情報の中で [[yii\web\Application::catchAll]] プロパティを構成することです。
```php
[
......@@ -117,8 +107,7 @@ $url = Url::to(['post/view', 'id' => 100]);
];
```
上記のコンフィギュレーションによって、入ってくる全てのリクエストを処理するために
`site/offline` アクションが使われるようになります。
上記の構成によって、入ってくる全てのリクエストを処理するために `site/offline` アクションが使われるようになります。
`catchAll` プロパティは配列を取り、最初の要素はルートを指定し、残りの要素 (「名前-値」のペア) は
[アクションのパラメータ](structure-controllers.md#action-parameters) を指定するものでなければなりません。
......@@ -127,7 +116,7 @@ $url = Url::to(['post/view', 'id' => 100]);
## URL を生成する <a name="creating-urls"></a>
Yii は、与えられたルートとそれに結び付けられるクエリパラメータからさまざまな URL を生成する
[[yii\helpers\Url::to()]] というヘルパーメソッドを提供しています。例えば、
[[yii\helpers\Url::to()]] というヘルパメソッドを提供しています。例えば、
```php
use yii\helpers\Url;
......@@ -148,18 +137,15 @@ echo Url::to(['post/index'], true);
echo Url::to(['post/index'], 'https');
```
上記の例では、既定の URL 形式が使われていると仮定していることに注意してください。綺麗な URL
形式が有効になっている場合は、生成される URL は、使われている [[yii\web\UrlManager::rules|URL 規則]]
に従って、違うものになります。
上記の例では、デフォルトの URL 形式が使われていると仮定していることに注意してください。
綺麗な URL 形式が有効になっている場合は、生成される URL は、使われている [[yii\web\UrlManager::rules|URL 規則]] に従って、異なるものになります。
[[yii\helpers\Url::to()]] メソッドに渡されるルートの意味は、コンテキストに依存します。ルートは
*相対* ルートか *絶対* ルートかのどちらかであり、下記の規則によって正規化されます。
[[yii\helpers\Url::to()]] メソッドに渡されるルートの意味は、コンテキストに依存します。
ルートは *相対* ルートか *絶対* ルートかのどちらかであり、下記の規則によって正規化されます。
- ルートが空文字列である場合は、現在リクエストされている [[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]] の値が前置されます。
例えば、カレントモジュールが `admin` であり、カレントコントローラが `post` であると仮定すると、
......@@ -182,11 +168,10 @@ echo Url::to(['/post/index']);
[[yii\helpers\Url::to()]] メソッドは、[[yii\web\UrlManager|URL マネージャ]] の
[[yii\web\UrlManager::createUrl()|createUrl()]] メソッド、および、[[yii\web\UrlManager::createAbsoluteUrl()|createAbsoluteUrl()]]
を呼び出すことによって実装されています。
次に続くいくつかの項では、[[yii\web\UrlManager|URL マネージャ]] を構成して、生成される URL
の形式をカスタマイズする方法を説明します。
次に続くいくつかの項では、[[yii\web\UrlManager|URL マネージャ]] を構成して、生成される URL の形式をカスタマイズする方法を説明します。
[[yii\helpers\Url::to()]] メソッドは、特定のルートとの関係を持たない URL の生成もサポートしています。
その場合、最初のパラメータとして配列を渡す代りに文字列を渡さなければなりません。例えば、
その場合、最初のパラメータには、配列を渡す代りに文字列を渡さなければなりません。例えば、
```php
use yii\helpers\Url;
......@@ -202,7 +187,7 @@ echo Url::to('@example');
echo Url::to('/images/logo.gif', true);
```
`to()` メソッドの他にも、[[yii\helpers\Url]]` ヘルパークラスは、便利な URL 生成メソッドをいくつか提供しています。
`to()` メソッドの他にも、[[yii\helpers\Url]]` ヘルパクラスは、便利な URL 生成メソッドをいくつか提供しています。
例えば、
```php
......@@ -226,7 +211,7 @@ echo Url::previous();
## 綺麗な URL を使う <a name="using-pretty-urls"></a>
綺麗な URL を使うためには、アプリケーションコンフィギュレーションの中で `urlManager` コンポーネントを次のように構成します。
綺麗な URL を使うためには、アプリケーションの構成情報の中で `urlManager` コンポーネントを次のように構成します。
```php
[
......@@ -244,44 +229,39 @@ echo Url::previous();
```
[[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] プロパティは、綺麗な URL 形式の有効/無効を切り替えますので、必須です。
その他のプロパティはオプションですが、上記で示されているコンフィギュレーションが最もよく用いられているものです。
その他のプロパティはオプションですが、上記で示されている構成が最もよく用いられているものです。
* [[yii\web\UrlManager::showScriptName|showScriptName]]: このプロパティは、エントリスクリプトを生成される URL に含めるべきかどうかを
決定します。例えば、このプロパティを true にすると、`/index.php/post/100` という URL を生成する代りに、`/post/100` という URL
を生成することが出来ます。
* [[yii\web\UrlManager::showScriptName|showScriptName]]: このプロパティは、生成される 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]] の少なくとも一つに合致しなければなりません。
そうでなければ、[[yii\web\NotFoundHttpException]] が投げられます。
厳密な解析が無効にされると、リクエストされた URL が [[yii\web\UrlManager::rules|rules]] のどれにも合致しない場合は、URL のパス情報の部分がリクエストされたルートとして扱われます。
* [[yii\web\UrlManager::rules|rules]]: このプロパティが URL を解析および生成するための一連の規則を含みます。
このプロパティが、アプリケーションの固有の要求を満たす形式を持つ URL を生成するために、あなたが主として使うプロパティです。
> Note|注意: 生成された URL からエントリスクリプト名を隠すためには、[[yii\web\UrlManager::showScriptName|showScriptName]]
を true に設定するだけでなく、ウェブサーバを構成して、リクエストされた URL が PHP スクリプトを明示的に指定していない場合でも、
正しい PHP スクリプトを特定出来るようにする必要があります。もしあなたが Apache ウェブサーバを使うつもりなら、
[インストール](start-installation.md#recommended-apache-configuration) の節で説明されている推奨設定を参照することが出来ます。
> Note|注意: 生成された URL からエントリスクリプト名を隠すためには、[[yii\web\UrlManager::showScriptName|showScriptName]] を false に設定するだけでなく、ウェブサーバを構成して、リクエストされた URL が PHP スクリプトを明示的に指定していない場合でも、正しい PHP スクリプトを特定出来るようにする必要があります。
もしあなたが Apache ウェブサーバを使うつもりなら、[インストール](start-installation.md#recommended-apache-configuration) の節で説明されている推奨設定を参照することが出来ます。
### URL 規則 <a name="url-rules"></a>
URL 規則は [[yii\web\UrlRule]] またはその子クラスのインスタンスです。すべての URL 規則は、URL のパス情報の部分との照合に使われるパターン、
ルート、そして、いくつかのクエリパラメータから構成されます。URL 規則は、パターンがリクエストされた URL と合致する場合に、
リクエストの解析に使用することが出来ます。また、URL 規則は、ルートとクエリパラメータ名が与えられたものと合致する場合に、
URL の生成に使用することが出来ます。
URL 規則は [[yii\web\UrlRule]] またはその子クラスのインスタンスです。
すべての URL 規則は、URL のパス情報の部分との照合に使われるパターン、ルート、そして、いくつかのクエリパラメータから構成されます。
URL 規則は、パターンがリクエストされた URL と合致する場合に、リクエストの解析に使用することが出来ます。
また、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 を生成します。
プロパティに宣言されている URL 規則を使って、入ってくるリクエストの解析と URL の生成を行います。
具体的に言えば、入ってくるリクエストを解析するためには、[[yii\web\UrlManager|URL マネージャ]] は宣言されている順に規則を調べて、リクエストされた URL に合致する *最初の* 規則を探します。
そして、その合致する規則を使って URL を解析して、ルートとそれと結合されたパラメータを得ます。
同じように、URL を生成するためには、[[yii\web\UrlManager|URL マネージャ]] は、与えられたルートとパラメータに合致する最初の規則を探して、それを使って URL を生成します。
[[yii\web\UrlManager::rules]] は、パターンをキーとし、それに対応するルートを値とする配列として構成することが出来ます。
「パターン - ルート」のペアが、それぞれ、URL 規則を構成します。例えば、次の [[yii\web\UrlManager::rules|rules]]
のコンフィギュレーションは、二つの URL 規則を宣言するものです。最初の規則は `posts` という URL に合致し、それを `post/index`
というルートにマップします。第二の規則は `post/(\d+)` という正規表現にマッチする URL に合致し、それを `post/view`
というルートと `id` という名前のパラメータにマップします。
「パターン - ルート」のペアが、それぞれ、URL 規則を構成します。
例えば、次の [[yii\web\UrlManager::rules|rules]] の構成は、二つの URL 規則を宣言するものです。
最初の規則は `posts` という URL に合致し、それを `post/index` というルートにマップします。
第二の規則は `post/(\d+)` という正規表現にマッチする URL に合致し、それを `post/view` というルートと `id` という名前のパラメータにマップします。
```php
[
......@@ -290,12 +270,13 @@ URL 縺ｫ蜷郁縺吶ｋ *譛蛻昴* 隕丞援繧呈爾縺励∪縺吶ゅ◎縺励※縲√◎縺ｮ蜷郁
]
```
> Info|情報: 規則のパターンは URL のパス情報の部分との照合に使用されます。例えば、`/index.php/post/100?source=ad`
のパス情報は `post/100` であり (先頭と末尾のスラッシュは無視します)、これは `post/(\d+)` というパターンに合致します。
> Info|情報: 規則のパターンは URL のパス情報の部分との照合に使用されます。
例えば、`/index.php/post/100?source=ad` のパス情報は `post/100` であり (先頭と末尾のスラッシュは無視します)、これは `post/(\d+)` というパターンに合致します。
URL 規則は、「パターン - ルート」のペアとして宣言する以外に、コンフィギュレーション配列として宣言することも出来ます。
すべてのコンフィギュレーション配列が、それぞれ、一つの URL 規則のオブジェクトを構成するために使われます。この形式は、
URL 規則の他のプロパティを構成したい場合に、よく必要になります。例えば、
URL 規則は、「パターン - ルート」のペアとして宣言する以外に、構成情報配列として宣言することも出来ます。
すべての構成情報配列が、それぞれ、一つの URL 規則のオブジェクトを構成するために使われます。
この形式は、URL 規則の他のプロパティを構成したい場合に、よく必要になります。
例えば、
```php
[
......@@ -309,7 +290,7 @@ URL 隕丞援縺ｮ莉悶繝励Ο繝代ユ繧｣繧呈ｧ区縺励◆縺ｴ蜷医↓縲√ｈ縺丞ｿｦ√↓
]
```
規則のコンフィギュレーションで `class` を指定しない場合は、既定として、[[yii\web\UrlRule]] が使われます。
規則の構成情報で `class` を指定しない場合は、既定として、[[yii\web\UrlRule]] が使われます。
### 名前付きパラメータ <a name="named-parameters"></a>
......@@ -334,23 +315,21 @@ URL 隕丞援縺ｯ縲√ヱ繧ｿ繝ｼ繝ｳ縺ｮ荳ｭ縺ｧ `<ParamName:RgExp>` 縺ｮ蠖｢蠑上〒謖ｮ壹＆
]
```
規則が URL 解析に使われる場合は:
規則が URL 解析に使われる場合は、
- `/index.php/posts` は、最初の規則を使って解析され、ルート `post/index` になります。
- `/index.php/posts/2014/php` は、三番目の規則を使って解析され、ルートは `post/index`、`year` パラメータの値は 2014、
そして、`category` パラメータの値は `php` となります。
- `/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` がルートとして返されることになります。
- `/index.php/posts/php` は、どのパターンにも合致しないため、[[yii\web\UrlManager::enableStrictParsing]] が true の場合は、[[yii\web\NotFoundHttpException]] を引き起こします。
[[yii\web\UrlManager::enableStrictParsing]] が false (これが既定値です) の場合は、パス情報の部分である `posts/php` がルートとして返されることになります。
規則が URL 生成に使われる場合は:
規則が URL 生成に使われる場合は、
- `Url::to(['post/index'])` は、最初の規則を使って、`/index.php/posts` を生成します。
- `Url::to(['post/index', 'year' => 2014, 'category' => 'php'])` は、三番目の規則を使って、`/index.php/posts/2014/php` を生成します。
- `Url::to(['post/view', 'id' => 100])` は、二番目の規則を使って、`/index.php/post/100` を生成します。
- `Url::to(['post/view', 'id' => 100, 'source' => 'ad'])` も、二番目の規則を使って、`/index.php/post/100?source=ad` を生成します。
`source` パラメータは規則の中で指定されていないので、クエリパラメータとして生成された URL に追加されます。
`source` パラメータは規則の中で指定されていないので、クエリパラメータとして、生成される URL に追加されます。
- `Url::to(['post/index', 'category' => 'php'])` は、どの規則も使わずに、`/index.php/post/index?category=php` を生成します。
どの規則も当てはまらないため、URL は、単純に、ルートをパス情報とし、すべてのパラメータをクエリ文字列として追加して生成されます。
......@@ -368,22 +347,19 @@ URL 隕丞援縺ｮ繝ｫ繝ｼ繝医↓縺ｯ繝代Λ繝｡繝ｼ繧ｿ蜷阪ｒ蝓九ａ霎ｼ繧縺薙→縺悟譚･縺ｾ
]
```
`/index.php/comment/100/create` という URL の解析には、最初の規則が適用され、`controller` パラメータには `comment`、
`action` パラメータには `create` がセットされます。こうして、`<controller>/<action>` というルートは、`comment/create`
として解決されます。
`/index.php/comment/100/create` という URL の解析には、最初の規則が適用され、`controller` パラメータには `comment`、`action` パラメータには `create` がセットされます。
こうして、`<controller>/<action>` というルートは、`comment/create` として解決されます。
同じように、`comment/index` というルートの URL を生成するためには、三番目の規則が適用されて、`index.php/comments` という URL が生成されます。
> Info|情報: ルートをパラメータ化することによって、URL 規則の数を大幅に減らすことが可能になり、
[[yii\web\UrlManager|URL マネージャ]] のパフォーマンスを目に見えて改善することが出来ます。
> Info|情報: ルートをパラメータ化することによって、URL 規則の数を大幅に減らすことが可能になり、[[yii\web\UrlManager|URL マネージャ]] のパフォーマンスを目に見えて改善することが出来ます。
既定では、規則の中で宣言されたパラメータは必須となります。リクエストされた URL が特定のパラメータを含まない場合や、
URL が特定のパラメータなしで生成される場合には、規則は適用されません。パラメータのどれかをオプション扱いにしたい場合は、規則の
[[yii\web\UrlRule::defaults|defaults]] プロパティを構成することが出来ます。このプロパティのリストに挙げられたパラメータは
オプション扱いとなり、規定されなかった場合は指定された値を取るようになります。
既定では、規則の中で宣言されたパラメータは必須となります。
リクエストされた URL が特定のパラメータを含まない場合や、URL が特定のパラメータなしで生成される場合には、規則は適用されません。
パラメータのどれかをオプション扱いにしたい場合は、規則の [[yii\web\UrlRule::defaults|defaults]] プロパティを構成することが出来ます。
このプロパティのリストに挙げられたパラメータはオプション扱いとなり、規定されなかった場合は指定された値を取るようになります。
次の規則の宣言においては、`page` と `tag` のパラメータは両方ともオプション扱いで、規定されなかった場合は、それぞれ、1
と空文字列を取ります。
次の規則の宣言においては、`page` と `tag` のパラメータは両方ともオプション扱いで、規定されなかった場合は、それぞれ、1 と空文字列を取ります。
```php
[
......@@ -408,9 +384,9 @@ URL 縺檎音螳壹繝代Λ繝｡繝ｼ繧ｿ縺ｪ縺励〒逕滓縺輔ｌ繧句ｴ蜷医↓縺ｯ縲∬ｦ丞援縺ｯ
### サーバ名を持つ規則 <a name="rules-with-server-names"></a>
URL 規則のパターンには、ウェブサーバ名を含むことが出来ます。このことが役に立つのは、主として、あなたのアプリケーションが
ウェブサーバ名によって異なる動作をしなければならない場合です。例えば、次の規則は、`http://admin.example.com/login`
という URL を `admin/user/login` のルートとして解析し、`http://www.example.com/login` を `site/login` として解析するものです。
URL 規則のパターンには、ウェブサーバ名を含むことが出来ます。
このことが役に立つのは、主として、あなたのアプリケーションがウェブサーバ名によって異なる動作をしなければならない場合です。
例えば、次の規則は、`http://admin.example.com/login` という URL を `admin/user/login` のルートとして解析し、`http://www.example.com/login` を `site/login` として解析するものです。
```php
[
......@@ -419,8 +395,8 @@ URL 隕丞援縺ｮ繝代ち繝ｼ繝ｳ縺ｫ縺ｯ縲√え繧ｧ繝悶し繝ｼ繝仙錐繧貞性繧縺薙→縺悟譚･
]
```
サーバ名にパラメータを埋め込んで、そこから動的な情報を抽出することも出来ます。例えば、次の規則は `http://en.example.com/posts`
という URL を解析して、`post/index` というルートと `language=en` というパラメータを取得するものです。
サーバ名にパラメータを埋め込んで、そこから動的な情報を抽出することも出来ます。
例えば、次の規則は `http://en.example.com/posts` という URL を解析して、`post/index` というルートと `language=en` というパラメータを取得するものです。
```php
[
......@@ -428,18 +404,17 @@ URL 隕丞援縺ｮ繝代ち繝ｼ繝ｳ縺ｫ縺ｯ縲√え繧ｧ繝悶し繝ｼ繝仙錐繧貞性繧縺薙→縺悟譚･
]
```
> Note|注意: サーバ名を持つ規則は、エントリスクリプトのサブフォルダをパターンに含むべきではありません。例えば、アプリケーションが
`http://www.example.com/sandbox/blog` の下にある場合は、`http://www.example.com/sandbox/blog/posts` ではなく、
`http://www.example.com/posts` というパターンを使うべきです。こうすれば、アプリケーションをどのようなディレクトリに配置しても、
アプリケーションのコードを変更する必要がなくなります。
> Note|注意: サーバ名を持つ規則は、エントリスクリプトのサブフォルダをパターンに含むべきではありません。
例えば、アプリケーションが `http://www.example.com/sandbox/blog` の下にある場合は、`http://www.example.com/sandbox/blog/posts` ではなく、`http://www.example.com/posts` というパターンを使うべきです。
こうすれば、アプリケーションをどのようなディレクトリに配置しても、アプリケーションのコードを変更する必要がなくなります。
### URL 接尾辞 <a name="url-suffixes"></a>
さまざまな目的から URL に接尾辞を追加したいことがあるでしょう。例えば、静的な HTML ページに見えるように、`.html` を URL
に追加したいかも知れません。また、レスポンスとして期待されているコンテントタイプを示すために、`.json` を URL
に追加したい場合もあるでしょう。アプリケーションのコンフィギュレーションで、次のように、[[yii\web\UrlManager::suffix]]
プロパティを構成することによって、この目的を達することが出来ます。
さまざまな目的から URL に接尾辞を追加したいことがあるでしょう。
例えば、静的な HTML ページに見えるように、`.html` を URL に追加したいかも知れません。
また、レスポンスとして期待されているコンテントタイプを示すために、`.json` を URL に追加したい場合もあるでしょう。
アプリケーションの構成情報で、次のように、[[yii\web\UrlManager::suffix]] プロパティを構成することによって、この目的を達することが出来ます。
```php
[
......@@ -457,7 +432,7 @@ URL 隕丞援縺ｮ繝代ち繝ｼ繝ｳ縺ｫ縺ｯ縲√え繧ｧ繝悶し繝ｼ繝仙錐繧貞性繧縺薙→縺悟譚･
]
```
上記のコンフィギュレーションによって、[[yii\web\UrlManager|URL マネージャ]] は、接尾辞として `.html` の付いた URL
上記の構成によって、[[yii\web\UrlManager|URL マネージャ]] は、接尾辞として `.html` の付いた URL
を認識し、また、生成するようになります。
> Tip|ヒント: URL が全てスラッシュで終るようにするためには、URL 接尾辞として `/` を設定することが出来ます。
......@@ -465,10 +440,10 @@ URL 隕丞援縺ｮ繝代ち繝ｼ繝ｳ縺ｫ縺ｯ縲√え繧ｧ繝悶し繝ｼ繝仙錐繧貞性繧縺薙→縺悟譚･
> Note|注意: URL 接尾辞を構成すると、リクエストされた URL が接尾辞を持たない場合は、認識できない URL であると見なされるようになります。
SEO の目的からも、これが推奨される慣行です。
場合によっては、URL によって異なる接尾辞を使いたいことがあるでしょう。その目的は、個々の URL 規則の [[yii\web\UrlRule::suffix|suffix]]
プロパティを構成することによって達成できます。URL 規則にこのプロパティが設定されている場合は、それが [[yii\web\UrlManager|URL マネージャ]]
レベルの接尾辞の設定をオーバーライドします。例えば、次のコンフィギュレーションには、グローバルな接尾辞 `.html` の代りに
`.json` を使用するカスタマイズされた URL 規則が含まれています。
場合によっては、URL によって異なる接尾辞を使いたいことがあるでしょう。
その目的は、個々の URL 規則の [[yii\web\UrlRule::suffix|suffix]] プロパティを構成することによって達成できます。
URL 規則にこのプロパティが設定されている場合は、それが [[yii\web\UrlManager|URL マネージャ]] レベルの接尾辞の設定をオーバーライドします。
例えば、次の構成には、グローバルな接尾辞 `.html` の代りに `.json` を使用するカスタマイズされた URL 規則が含まれています。
```php
[
......@@ -494,12 +469,11 @@ URL 隕丞援縺ｮ繝代ち繝ｼ繝ｳ縺ｫ縺ｯ縲√え繧ｧ繝悶し繝ｼ繝仙錐繧貞性繧縺薙→縺悟譚･
### HTTP メソッド <a name="http-methods"></a>
RESTful API を実装するときは、使用されている HTTP メソッドに応じて、同一の URL を異なるルートとして解析することが
必要になル場合がよくあります。これは、規則のパターンにサポートされている HTTP メソッドを前置することによって、
簡単に達成することが出来ます。一つの規則が複数の HTTP メソッドをサポートする場合は、メソッド名をカンマで区切ります。
RESTful API を実装するときは、使用されている HTTP メソッドに応じて、同一の URL を異なるルートとして解析することが必要になる場合がよくあります。
これは、規則のパターンにサポートされている HTTP メソッドを前置することによって、簡単に達成することが出来ます。
一つの規則が複数の HTTP メソッドをサポートする場合は、メソッド名をカンマで区切ります。
例えば、次の三つの規則は、`post/<id:\d+>` という同一のパターンを持って、異なる HTTP メソッドをサポートするものです。
`PUT post/100` に対するリクエストは `post/create` と解析され、`GET post/100` に対するリクエストは `post/view`
と解析されることになります。
`PUT post/100` に対するリクエストは `post/create` と解析され、`GET post/100` に対するリクエストは `post/view` と解析されることになります。
```php
[
......@@ -509,8 +483,8 @@ RESTful API 繧貞ｮ溯｣☆繧九→縺阪縲∽ｽｿ逕ｨ縺輔ｌ縺ｦ縺ｋ HTTP 繝｡繧ｽ繝ラ縺
]
```
> Note|注意: URL 規則が HTTP メソッドをパターンに含む場合、その規則は解析目的にだけ使用されます。[[yii\web\UrlManager|URL マネージャ]]
が URL 生成のために呼ばれたときは、その規則はスキップされます。
> Note|注意: URL 規則が HTTP メソッドをパターンに含む場合、その規則は解析目的にだけ使用されます。
[[yii\web\UrlManager|URL マネージャ]] が URL 生成のために呼ばれたときは、その規則はスキップされます。
> Tip|ヒント: RESTful API のルーティングを簡単にするために、Yii は特別な URL 規則クラス [[yii\rest\UrlRule]] を提供しています。
これは非常に効率的なもので、コントローラ ID の自動的な複数形化など、いくつかの素敵な機能をサポートするものです。
......@@ -520,9 +494,9 @@ RESTful API 繧貞ｮ溯｣☆繧九→縺阪縲∽ｽｿ逕ｨ縺輔ｌ縺ｦ縺ｋ HTTP 繝｡繧ｽ繝ラ縺
### 規則をカスタマイズする <a name="customizing-rules"></a>
これまでの例では、URL 規則は主として「パターン - ルート」のペアの形で宣言されています。これが通常使用される短縮形式です。
特定のシナリオの下では、[[yii\web\UrlRule::suffix]] などのような、他のプロパティを構成して URL 規則をカスタマイズしたいことも
あるでしょう。完全なコンフィギュレーション配列を使って規則を指定すれば、そうすることが出来ます。次の例は、[URL 接尾辞](#url-suffixes)
の項から抜き出したものです。
特定のシナリオの下では、[[yii\web\UrlRule::suffix]] などのような、他のプロパティを構成して URL 規則をカスタマイズしたいこともあるでしょう。
完全な構成情報配列を使って規則を指定すれば、そうすることが出来ます。
次の例は、[URL 接尾辞](#url-suffixes) の項から抜き出したものです。
```php
[
......@@ -536,16 +510,15 @@ RESTful API 繧貞ｮ溯｣☆繧九→縺阪縲∽ｽｿ逕ｨ縺輔ｌ縺ｦ縺ｋ HTTP 繝｡繧ｽ繝ラ縺
]
```
> Info|情報: 規則のコンフィギュレーションで `class` を指定しない場合は、既定として、[[yii\web\UrlRule]] クラスが使われます。
> Info|情報: 規則の構成情報で `class` を指定しない場合は、既定として、[[yii\web\UrlRule]] クラスが使われます。
### 規則を動的に追加する <a name="adding-rules"></a>
URL 規則は [[yii\web\UrlManager|URL マネージャ]] に動的に追加することが出来ます。このことは、再配布可能な [モジュール](structure-modules.md)
が自分自身の URL 規則を管理する必要がある場合に、しばしば必要になります。動的に追加された規則がルーティングのプロセスで効果を発揮するためには、
その規則を [ブートストラップ](runtime-bootstrapping.md) の段階で追加しなければなりません。これは、モジュールにとっては、次のように、
[[yii\base\BootstrapInterface]] を実装して、[[yii\base\BootstrapInterface::bootstrap()|bootstrap()]]
メソッドの中で規則を追加しなければならないことを意味します。
URL 規則は [[yii\web\UrlManager|URL マネージャ]] に動的に追加することが出来ます。
このことは、再配布可能な [モジュール](structure-modules.md) が自分自身の URL 規則を管理する必要がある場合に、しばしば必要になります。
動的に追加された規則がルーティングのプロセスで効果を発揮するためには、その規則を [ブートストラップ](runtime-bootstrapping.md) の段階で追加しなければなりません。
これは、モジュールにとっては、次のように、[[yii\base\BootstrapInterface]] を実装して、[[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] メソッドの中で規則を追加しなければならないことを意味します。
```php
public function bootstrap($app)
......@@ -556,16 +529,13 @@ public function bootstrap($app)
}
```
さらに、モジュールが [ブートストラップ](runtime-bootstrapping.md) の過程に関与できるように、それを [[yii\web\Application::bootstrap]]
のリストに挙げなければならないことに注意してください。
さらに、モジュールが [ブートストラップ](runtime-bootstrapping.md) の過程に関与できるように、それを [[yii\web\Application::bootstrap]] のリストに挙げなければならないことに注意してください。
### 規則クラスを作成する <a name="creating-rules"></a>
デフォルトの [[yii\web\UrlRule]] クラスはほとんどのプロジェクトに対して十分に柔軟なものであるというのは事実ですが、
それでも、自分自身で規則クラスを作る必要があるような状況はあります。例えば、自動車ディーラーのウェブサイトにおいて、
`/Manufacturer/Model` のような URL 形式をサポートしたいけれども、`Manufacturer` と `Model` は、両方とも、
データベーステーブルに保存されている何らかのデータに合致するものでなければならない、というような場合です。
デフォルトの [[yii\web\UrlRule]] クラスはほとんどのプロジェクトに対して十分に柔軟なものであるというのは事実ですが、それでも、自分自身で規則クラスを作る必要があるような状況はあります。
例えば、自動車ディーラーのウェブサイトにおいて、`/Manufacturer/Model` のような URL 形式をサポートしたいけれども、`Manufacturer` と `Model` は、両方とも、データベーステーブルに保存されている何らかのデータに合致するものでなければならない、というような場合です。
デフォルトの規則クラスは、静的に宣言されるパターンに依拠しているため、ここでは役に立ちません。
この問題を解決するために、次のような URL 規則クラスを作成することが出来ます。
......@@ -605,7 +575,7 @@ class CarUrlRule extends Object implements UrlRuleInterface
}
```
そして、[[yii\web\UrlManager::rules]] のコンフィギュレーションで、新しい規則クラスを使います。
そして、[[yii\web\UrlManager::rules]] の構成情報で、新しい規則クラスを使います。
```php
[
......@@ -621,15 +591,12 @@ class CarUrlRule extends Object implements UrlRuleInterface
## パフォーマンスに対する考慮 <a name="performance-consideration"></a>
複雑なウェブアプリケーションを開発するときは、リクエストの解析と URL 生成に要する時間を削減するために
URL 規則を最適化することが重要になります。
複雑なウェブアプリケーションを開発するときは、リクエストの解析と URL 生成に要する時間を削減するために URL 規則を最適化することが重要になります。
パラメータ化したルートを使うことによって、URL 規則の数を減らして、パフォーマンスを著しく向上させることが出来ます。
URL を解析または生成するときに、[[yii\web\UrlManager|URL マネージャ]] は、宣言された順序で URL 規則を調べます。
従って、より多く使われる規則がより少なく使われる規則より前に来るように順序を調整することを検討してください。
パターンまたはルートに共通の先頭部分を持つ URL 規則がある場合は、[[yii\web\UrlManager|URL マネージャ]]
がそれらをグループ化して効率的に調べることが出来るように、[[yii\web\GroupUrlRule]] を使うことを検討してください。
あなたのアプリケーションがモジュールによって構成されており、モジュールごとに、モジュール ID を共通の先頭部分とする
一群の URL 規則を持っている場合は、通常、このことが当てはまります。
パターンまたはルートに共通の先頭部分を持つ URL 規則がある場合は、[[yii\web\UrlManager|URL マネージャ]] がそれらをグループ化して効率的に調べることが出来るように、[[yii\web\GroupUrlRule]] を使うことを検討してください。
あなたのアプリケーションがモジュールによって構成されており、モジュールごとに、モジュール ID を共通の先頭部分とする一群の URL 規則を持っている場合は、通常、このことが当てはまります。
docs/guide-ja/runtime-sessions-cookies.md
セッションとクッキー
====================
セッションとクッキーは、データが複数のユーザリクエストを超えて持続することを可能にします。素の PHP では、それぞれ、
グローバル変数 `$_SESSION` と `$_COOKIE` によってアクセスすることが出来ます。
Yii はセッションとクッキーをオブジェクトとしてカプセル化し、オブジェクト指向の流儀でアクセスできるようにするとともに、
有用な機能強化を追加しています。
セッションとクッキーは、データが複数のユーザリクエストを超えて持続することを可能にします。
素の PHP では、それぞれ、グローバル変数 `$_SESSION` と `$_COOKIE` によってアクセスすることが出来ます。
Yii はセッションとクッキーをオブジェクトとしてカプセル化し、オブジェクト指向の流儀でアクセスできるようにするとともに、有用な機能強化を追加しています。
## セッション <a name="sessions"></a>
[リクエスト](runtime-requests.md) や [レスポンス](runtime-responses.md) と同じように、セッションに対しては、
既定では [[yii\web\Session]] のインスタンスである `session` [アプリケーションコンポーネント] によってアクセスすることが出来ます。
[リクエスト](runtime-requests.md) や [レスポンス](runtime-responses.md) と同じように、既定では [[yii\web\Session]] のインスタンスである `session` [アプリケーションコンポーネント] によって、セッションにアクセスすることが出来ます。
### セッションのオープンとクローズ <a name="opening-closing-sessions"></a>
......@@ -69,9 +67,8 @@ foreach ($session as $name => $value) ...
foreach ($_SESSION as $name => $value) ...
```
> Info|情報: セッションデータに `session` コンポーネントによってアクセスする場合は、まだ開かれていないときは、
自動的にセッションが開かれます。これに対して `$_SESSION` によってセッションデータにアクセスする場合は、
`session_start()` を明示的に呼び出すことが必要になります。
> Info|情報: セッションデータに `session` コンポーネントによってアクセスする場合は、まだ開かれていないときは、自動的にセッションが開かれます。
これに対して `$_SESSION` によってセッションデータにアクセスする場合は、`session_start()` を明示的に呼び出すことが必要になります。
配列であるセッションデータを扱う場合、`session` コンポーネントには、配列の要素を直接修正することができない、という制約があります。例えば、
......@@ -118,29 +115,28 @@ $session['captcha.number'] = 5;
$session['captcha.lifetime'] = 3600;
```
パフォーマンスとコードの可読性を高めるためには、最後の回避策を推奨します。すなわち、
配列を一つのセッション変数として保存する代りに、配列の個々の要素を他の要素と同じキー接頭辞を共有する一つのセッション変数として保存することです。
パフォーマンスとコードの可読性を高めるためには、最後の回避策を推奨します。
すなわち、配列を一つのセッション変数として保存する代りに、配列の個々の要素を他の要素と同じキー接頭辞を共有する一つのセッション変数として保存することです。
### カスタムセッションストレージ <a name="custom-session-storage"></a>
既定の [[yii\web\Session]] クラスはセッションデータをサーバ上のファイルとして保存します。Yii は、また、さまざまなセッションストレージを実装する下記のクラスをも提供しています。
既定の [[yii\web\Session]] クラスはセッションデータをサーバ上のファイルとして保存します。
Yii は、また、さまざまなセッションストレージを実装する下記のクラスをも提供しています。
* [[yii\web\DbSession]]: セッションデータをデータベーステーブルを使って保存する。
* [[yii\web\CacheSession]]: セッションデータを、構成された [キャッシュコンポーネント](caching-data.md#cache-components) の力を借りて、キャッシュを使って保存する。
* [[yii\redis\Session]]: セッションデータを [redis](http://redis.io/) をストレージ媒体として使って保存する。
* [[yii\mongodb\Session]]: セッションデータを [MongoDB](http://www.mongodb.org/) に保存する。
これらのセッションクラスは全て一連の同じ API メソッドをサポートします。その結果として、
セッションを使用するアプリケーションコードを修正することなしに、セッションストレージクラスを切り替えることが出来ます。
これらのセッションクラスは全て一連の同じ API メソッドをサポートします。
その結果として、セッションを使用するアプリケーションコードを修正することなしに、セッションストレージクラスを切り替えることが出来ます。
> Note|注意: カスタムセッションストレージを使っているときに `$_SESSION` を通じてセッションデータにアクセスしたい場合は、
セッションが [[yii\web\Session::open()]] によって既に開始されていることを確認しなければなりません。
> Note|注意: カスタムセッションストレージを使っているときに `$_SESSION` を通じてセッションデータにアクセスしたい場合は、セッションが [[yii\web\Session::open()]] によって既に開始されていることを確認しなければなりません。
これは、カスタムセッションストレージのハンドラが、このメソッドの中で登録されるからです。
これらのコンポーネントクラスの構成方法と使用方法については、それらの API ドキュメントを参照してください。
下記の例は、アプリケーションのコンフィギュレーションにおいて、データベーステーブルをセッションストレージとして使うために
[[yii\web\DbSession]] を構成する方法を示すものです。
下記の例は、アプリケーションの構成情報において、データベーステーブルをセッションストレージとして使うために [[yii\web\DbSession]] を構成する方法を示すものです。
```php
return [
......@@ -177,9 +173,8 @@ CREATE TABLE session
### フラッシュデータ <a name="flash-data"></a>
フラッシュデータは特殊な種類のセッションデータで、あるリクエストの中で設定されると、次のリクエストの間においてのみ読み出すことが出来て、
その後は自動的に削除されるものです。フラッシュデータが最もよく使われるのは、エンドユーザに一度だけ表示されるべきメッセージ、
例えば、ユーザのフォーム送信が成功した後に表示される確認メッセージなどを実装するときです。
フラッシュデータは特殊な種類のセッションデータで、あるリクエストの中で設定されると、次のリクエストの間においてのみ読み出すことが出来て、その後は自動的に削除されるものです。
フラッシュデータが最もよく使われるのは、エンドユーザに一度だけ表示されるべきメッセージ、例えば、ユーザのフォーム送信が成功した後に表示される確認メッセージなどを実装するときです。
`session` アプリケーションコンポーネントによって、フラッシュデータを設定し、アクセスすることが出来ます。例えば、
......@@ -221,16 +216,14 @@ $alerts = $session->getFlash('alerts');
> Note|注意: 同じ名前のフラッシュデータに対して、[[yii\web\Session::setFlash()]] と [[yii\web\Session::addFlash()]] を一緒に使わないようにしてください。
これは、後者のメソッドが、同じ名前のフラッシュデータを追加できるように、フラッシュデータを自動的に配列に変換するからです。
その結果、[[yii\web\Session::getFlash()]] を呼び出したとき、この二つのメソッドの呼び出し順によって、
あるときは配列を受け取り、あるときは文字列を受け取るということになってしまいます。
その結果、[[yii\web\Session::getFlash()]] を呼び出したとき、この二つのメソッドの呼び出し順によって、あるときは配列を受け取り、あるときは文字列を受け取るということになってしまいます。
## クッキー <a name="cookies"></a>
Yii は個々のクッキーを [[yii\web\Cookie]] のオブジェクトとして表します。[[yii\web\Request]] と [[yii\web\Response]] は、
ともに、`cookies` という名前のプロパティによって、クッキーのコレクションを保持します。
後者のクッキーコレクションはリクエストの中で送信されたクッキーを表し、一方、後者のクッキーコレクションは、
ユーザに送信されることになるクッキーを表します。
Yii は個々のクッキーを [[yii\web\Cookie]] のオブジェクトとして表します。
[[yii\web\Request]] と [[yii\web\Response]] は、ともに、`cookies` という名前のプロパティによって、クッキーのコレクションを保持します。
後者のクッキーコレクションはリクエストの中で送信されたクッキーを表し、一方、後者のクッキーコレクションは、ユーザに送信されることになるクッキーを表します。
### クッキーを読み出す <a name="reading-cookies"></a>
......@@ -280,9 +273,8 @@ $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 に設定されています。
......@@ -291,22 +283,22 @@ unset($cookies['language']);
### クッキー検証 <a name="cookie-validation"></a>
最後の二つの項で示されているように、`request` と `response` のコンポーネントを通じてクッキーを読んだり送信したりする場合には、
クッキーがクライアントサイドで修正されるのを防止するクッキー検証という追加のセキュリティを享受することが出来ます。
これは、個々のクッキーにハッシュ文字列をサインとして追加することによって達成されます。アプリケーションは、
サインを見て、クッキーがクライアントサイドで修正されたかどうかを知ることが出来ます。もし、修正されていれば、
そのクッキーは `request` コンポーネントの [[yii\web\Request::cookies|クッキーコレクション]] からはアクセスすることが出来なくなります。
最後の二つの項で示されているように、`request` と `response` のコンポーネントを通じてクッキーを読んだり送信したりする場合には、クッキーがクライアントサイドで修正されるのを防止するクッキー検証という追加のセキュリティを享受することが出来ます。
これは、個々のクッキーにハッシュ文字列をサインとして追加することによって達成されます。
アプリケーションは、サインを見て、クッキーがクライアントサイドで修正されたかどうかを知ることが出来ます。
もし、修正されていれば、そのクッキーは `request` コンポーネントの [[yii\web\Request::cookies|クッキーコレクション]] からはアクセスすることが出来なくなります。
> Note|注意: クッキー検証はクッキーの値が修正されるのを防止するだけです。クッキーが検証に失敗した場合でも、
`$_COOKIE` を通じてそれにアクセスすることは引き続いて可能です。これは、サードパーティのライブラリが、クッキー検証を含まない、ライブラリ自体の方法でクッキーを操作し得るためです。
> Note|注意: クッキー検証はクッキーの値が修正されるのを防止するだけです。
クッキーが検証に失敗した場合でも、`$_COOKIE` を通じてそれにアクセスすることは引き続いて可能です。
これは、サードパーティのライブラリが、クッキー検証を含まない、ライブラリ自体の方法でクッキーを操作し得るためです。
クッキー検証はデフォルトで有効になっています。[[yii\web\Request::enableCookieValidation]] プロパティを false に設定することによって無効にすることが出来ますが、
無効にしないことを強く推奨します。
クッキー検証はデフォルトで有効になっています。
[[yii\web\Request::enableCookieValidation]] プロパティを false に設定することによって無効にすることが出来ますが、無効にしないことを強く推奨します。
> Note|注意: `$_COOKIE` と `setcookie()` によって直接に 読み出し/送信 されるクッキーは検証されません。
クッキー検証を使用する場合は、前述のハッシュ文字列を生成するために使用される [[yii\web\Request::cookieValidationKey]] を指定しなければなりません。
アプリケーションのコンフィギュレーションで `request` コンポーネントを構成することによって、そうすることが出来ます。
アプリケーションの構成情報で `request` コンポーネントを構成することによって、そうすることが出来ます。
```php
return [
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment