Commit dc951405 by Nobuo Kihara

docs/guide-ja/structure-controllers.md - reviewd [ci skip]

Conflicts: docs/guide-ja/structure-controllers.md
parent feac9c7f
......@@ -2,16 +2,14 @@
============
コントローラは [MVC](http://ja.wikipedia.org/wiki/Model_View_Controller) アーキテクチャの一部を成すものです。
これは [[yii\base\Controller]] を拡張したクラスのオブジェクトであり、リクエストの処理とレスポンスの生成について責任を負うものです。
具体的には、[アプリケーション](structure-applications.md) から制御を引き継いだ後、コントローラは入ってきたリクエストのデータを分析し、それを [モデル](structure-models.md)
に引き渡して、モデルが生成した結果を [ビュー](structure-views.md) に投入し、最終的に外に出て行くレスポンスを生成します。
それは [[yii\base\Controller]] を拡張したクラスのオブジェクトであり、リクエストの処理とレスポンスの生成について責任を負います。
具体的には、[アプリケーション](structure-applications.md) から制御を引き継いだ後、コントローラは入ってきたリクエストのデータを分析し、それを [モデル](structure-models.md) に引き渡して、モデルが生成した結果を [ビュー](structure-views.md) に投入し、最終的に外に出て行くレスポンスを生成します。
## アクション<span id="actions"></span>
## アクション <span id="actions"></span>
コントローラは *アクション* から構成されます。
アクションは、エンドユーザがアドレスを指定して実行をリクエストできる最も基本的な構成単位です。
コントローラは一つまたは複数のアクションを持ち得ます。
コントローラは、エンドユーザがアドレスを指定して実行をリクエストできる最も基本的なユニットである *アクション* から構成されます。
コントローラは一つまたは複数のアクションを持つことが出来ます。
次の例は、`view``create` という二つのアクションを持つ `post` コントローラを示すものです。
......@@ -62,15 +60,14 @@ class PostController extends Controller
どちらかが失敗したときは、ユーザが必要なデータを入力できるようにするための `create` ビューを表示します。
## ルート<span id="routes"></span>
## ルート <span id="routes"></span>
エンドユーザは、いわゆる *ルート* によって、アクションのアドレスを指定します。
ルートは、次の部分からなる文字列です。
* モジュール ID: この部分は、コントローラがアプリケーションではなく [モジュール](structure-modules.md) に属する場合にのみ存在します。
* コントローラ ID: 同じアプリケーション (または、コントローラがモジュールに属する場合は、同じモジュール)
に属する全てのコントローラの中から、特定のコントローラを指定するユニークな文字列。
* アクション ID: 同じコントローラに属する全てのアクションの中から、特定のアクションを指定するユニークな文字列。
* モジュール ID: この部分は、コントローラがアプリケーションではない [モジュール](structure-modules.md) に属する場合にのみ存在します。
* コントローラ ID: 同じアプリケーション (または、コントローラがモジュールに属する場合は、同じモジュール) に属する全てのコントローラの中から、コントローラを一意に特定する文字列。
* アクション ID: 同じコントローラに属する全てのアクションの中から、アクションを一意に特定する文字列。
ルートは次の形式を取ります。
......@@ -88,10 +85,10 @@ ModuleID/ControllerID/ActionID
ルートがどのようにしてアクションとして解決されるかについての詳細は、[ルーティングと URL 生成](runtime-routing.md) の節を参照してください。
## コントローラを作成する<span id="creating-controllers"></span>
## コントローラを作成する <span id="creating-controllers"></span>
[[yii\web\Application|ウェブアプリケーション]] では、コントローラは [[yii\web\Controller]] またはその子クラスから派生させるべきものです
同様に、[[yii\console\Application|コンソールアプリケーション]] では、コントローラは [[yii\console\Controller]] またはその子クラスから派生させるべきものです
[[yii\web\Application|ウェブアプリケーション]] では、コントローラは [[yii\web\Controller]] またはその子クラスから派生させなければなりません
同様に、[[yii\console\Application|コンソールアプリケーション]] では、コントローラは [[yii\console\Controller]] またはその子クラスから派生させなければなりません
次のコードは `site` コントローラを定義するものです。
```php
......@@ -105,25 +102,24 @@ class SiteController extends Controller
```
### コントローラの ID<span id="controller-ids"></span>
### コントローラ ID <span id="controller-ids"></span>
通常、コントローラは特定ののリソースに関するリクエストを処理するように設計されます。
この理由により、たいていはコントローラが処理するリソースの型を示す名詞をコントローラの ID として使います。
通常、コントローラは特定のタイプのリソースに関するリクエストを処理するように設計されます。
この理由により、たいていは、処理するリソースのタイプを示す名詞をコントローラの ID として使います。
例えば、記事データを処理するコントローラの ID としては、`article` を使うことが出来ます。
既定では、コントローラの ID は、小文字の英字、数字、アンダースコア、ダッシュ、および、フォワードスラッシュのみを含むべきものです。
例えば、`article``post-comment` はともに有効なコントローラの ID ですが、`article?``PostComment``admin\post` は有効ではありません。
デフォルトでは、コントローラ ID は、小文字の英字、数字、アンダースコア、ダッシュ、および、フォワードスラッシュのみを含むべきものです。
例えば、`article``post-comment` はともに有効なコントローラ ID ですが、`article?``PostComment``admin\post` はそうではありません。
コントローラの ID は、サブディレクトリの接頭辞を含んでも構いません。例えば、`admin/article` は、[[yii\base\Application::controllerNamespace|コントローラ名前空間]]
の下の `admin` サブディレクトリにある `article` コントローラを表します。
サブディレクトリの接頭辞として有効な文字は、小文字または大文字の英字、数字、アンダースコア、そして、
フォワードスラッシュです。
コントローラ ID は、サブディレクトリの接頭辞を含んでも構いません。
例えば、`admin/article` は、[[yii\base\Application::controllerNamespace|コントローラ名前空間]] の下の `admin` サブディレクトリにある `article` コントローラを表します。
サブディレクトリの接頭辞として有効な文字は、小文字または大文字の英字、数字、アンダースコア、そして、フォワードスラッシュです。
フォワードスラッシュは、複数レベルのサブディレクトリの区切り文字として使われます (例えば、`panels/admin`)。
### コントローラクラスの命名規則<span id="controller-class-naming"></span>
### コントローラクラスの命名規則 <span id="controller-class-naming"></span>
コントローラクラスの名前は下記の規則に従ってコントローラ ID から導出することが出来ます。
コントローラクラスの名前は下記の規則に従ってコントローラ ID から導出することが出来ます。
* ダッシュで区切られた各単語の最初の文字を大文字に変える。
コントローラ ID がスラッシュを含む場合、この規則は ID の最後のスラッシュの後ろの部分にのみ適用されることに注意。
......@@ -139,18 +135,16 @@ class SiteController extends Controller
* `adminPanels/post-comment` から `app\controllers\adminPanels\PostCommentController` が導出される。
コントローラクラスは [オートロード可能](concept-autoloading.md) でなければなりません。
この理由により、上記の例の `aritcle` コントローラクラスは [エイリアス](concept-aliases.md)`@app/controllers/ArticleController.php`
であるファイルに保存されるべきものとなります。一方、`admin/post2-comment` コントローラは `@app/controllers/admin/Post2CommentController.php`
というエイリアスのファイルに保存されるべきものとなります。
この理由により、上記の例の `aritcle` コントローラクラスは [エイリアス](concept-aliases.md)`@app/controllers/ArticleController.php` であるファイルに保存されるべきものとなります。
一方、`admin/post2-comment` コントローラは `@app/controllers/admin/Post2CommentController.php` というエイリアスのファイルに保存されるべきものとなります。
> Info|情報: 最後の例である `admin/post2-comment` は、どうすれば [[yii\base\Application::controllerNamespace|コントローラ名前空間]]
のサブディレクトリにコントローラを置くことが出来るかを示しています。
> Info|情報: 最後の例である `admin/post2-comment` は、どうすれば [[yii\base\Application::controllerNamespace|コントローラ名前空間]] のサブディレクトリにコントローラを置くことが出来るかを示しています。
この方法は、コントローラをいくつかのカテゴリに分けて整理したい、けれども [モジュール](structure-modules.md) は使いたくない、という場合に役立ちます。
### コントローラマップ<span id="controller-map"></span>
### コントローラマップ <span id="controller-map"></span>
[[yii\base\Application::controllerMap|コントローラマップ]] を構成すると、上で述べたコントローラ ID とクラス名の制約を乗り越えることが出来ます。
[[yii\base\Application::controllerMap|コントローラマップ]] を構成すると、上で述べたコントローラ ID とクラス名の制約を乗り越えることが出来ます。
これは、主として、クラス名に対する制御が及ばないサードパーティのコントローラを使おうとする場合に有用です。
[[yii\base\Application::controllerMap|コントローラマップ]] は [アプリケーションの構成情報](structure-applications.md#application-configurations) の中で、次のように構成することが出来ます。
......@@ -171,10 +165,10 @@ class SiteController extends Controller
```
### デフォルトコントローラ<span id="default-controller"></span>
### デフォルトコントローラ <span id="default-controller"></span>
全てのアプリケーションは、それぞれ、[[yii\base\Application::defaultRoute]] プロパティを通じて規定されるデフォルトコントローラを持ちます。
リクエストが [ルート](#ids-routes) を指定しない場合、このプロパティによって指定されたルートが使われます。
全てのアプリケーションは、それぞれ、[[yii\base\Application::defaultRoute]] プロパティによって指定されるデフォルトコントローラを持ちます。
リクエストが [ルート](#routes) を指定していない場合、このプロパティによって指定されたルートが使われます。
[[yii\web\Application|ウェブアプリケーション]] では、この値は `'site'` であり、一方、[[yii\console\Application|コンソールアプリケーション]] では、`help` です。
従って、URL が `http://hostname/index.php` である場合は、`site` コントローラがリクエストを処理することになります。
......@@ -187,9 +181,9 @@ class SiteController extends Controller
```
## アクションを作成する<span id="creating-actions"></span>
## アクションを作成する <span id="creating-actions"></span>
アクションの作成は、コントローラクラスの中にいわゆる *アクションメソッド* を定義するだけの簡単なことです。
アクションは、コントローラクラスの中にいわゆる *アクションメソッド* を定義するだけで簡単に作成することが出来ます。
アクションメソッドとは、`action` という語で始まる名前を持つ *public* メソッドのことです。
アクションメソッドの返り値がエンドユーザに送信されるレスポンスデータを表します。
次のコードは、`index``hello-world` という二つのアクションを定義するものです。
......@@ -214,53 +208,49 @@ class SiteController extends Controller
```
### アクション ID<span id="action-ids"></span>
### アクション ID <span id="action-ids"></span>
アクションは、たいてい、あるリソースについて特定の操作を実行するように設計されます。
この理由により、アクション ID は、通常、`view``update` などのような動詞になります。
既定では、アクション ID は、小文字の英字、数字、アンダースコア、そして、ダッシュのみを含むべきものです。
デフォルトでは、アクション ID は、小文字の英字、数字、アンダースコア、そして、ダッシュのみを含むべきものです。
アクション ID の中のダッシュは単語を分けるために使われます。
例えば、`view``update2``comment-post` は全て有効なアクション ID ですが、`view?``Update`有効ではありません。
例えば、`view``update2``comment-post` は全て有効なアクション ID ですが、`view?``Update`そうではありません。
アクションは二つの方法で作成することが出来ます。すなわち、インラインアクションとスタンドアロンアクションです。
インラインアクションはコントローラクラスのメソッドとして定義されるものであり、一方、スタンドアロンアクションは
[[yii\base\Action]] またはその子クラスから派生させたクラスです。
インラインアクションは作成するのにより少ない労力を要し、アクションを再利用する意図がない場合によく推奨されます。
もう一方で、スタンドアロンアクションは、主として、さまざまなコントローラの中で使われることや、[エクステンション](structure-extensions.md)
として再配布されることを意図して作成されます。
アクションは二つの方法、すなわち、インラインアクションまたはスタンドアロンアクションとして作成することが出来ます。
インラインアクションはコントローラクラスのメソッドとして定義されるものであり、一方、スタンドアロンアクションは [[yii\base\Action]] またはその子クラスを拡張するクラスです。
インラインアクションは作成するのにより少ない労力を要するため、通常は、アクションを再利用する意図がない場合に推奨されます。
もう一方のスタンドアロンアクションは、主として、さまざまなコントローラの中で使われることや、[エクステンション](structure-extensions.md) として再配布されることを目的として作成されます。
### インラインアクション<span id="inline-actions"></span>
### インラインアクション <span id="inline-actions"></span>
インラインアクションは、たった今説明したように、アクションメソッドとして定義されるアクションを指します。
インラインアクションは、たった今説明したように、アクションメソッドの形で定義されるアクションを指します。
アクションメソッドの名前は、次の基準に従って、アクション ID から導出されます。
* アクション ID に含まれる各単語の最初の文字を大文字に変換する。
* ダッシュを削除する。
* 接頭辞 `action`前に付ける。
* 接頭辞 `action` を付ける。
例えば、`index``actionIndex` となり、`hello-world``actionHelloWorld` となります。
> Note|注意: アクションメソッドの名前は、*大文字と小文字を区別* します。`ActionIndex`
という名前のメソッドがあっても、 それはアクションメソッドとは見なされず、結果として、`index`
アクションに対するリクエストは例外に帰結します。
> Note|注意: アクションメソッドの名前は、*大文字と小文字を区別* します。
`ActionIndex` という名前のメソッドがあっても、それはアクションメソッドとは見なされず、結果として、`index` アクションに対するリクエストは例外に帰結します。
アクションメソッドが public でなければならない事にも注意してください。
private や protected なメソッドがインラインアクションを定義することはありません。
インラインアクションは作成するのにほとんど労力を要さないため、たいていのアクションはインラインアクションとして定義されます。
しかし、同じアクションを別の場所で再利用する計画を持っていたり、また、アクションを再配布したいと思っていたりする場合は、アクションを *スタンドアロンアクション* として定義することを考慮すべきです。
しかし、同じアクションを別の場所で再利用する計画を持っていたり、また、アクションを再配布したいと思っていたりする場合は、アクションを *スタンドアロンアクション* として定義することを検討すべきです。
### スタンドアロンアクション<span id="standalone-actions"></span>
### スタンドアロンアクション <span id="standalone-actions"></span>
スタンドアロンアクションは、[[yii\base\Action]] またはその子クラスを拡張したクラスとして定義されるものです。
スタンドアロンアクションは、[[yii\base\Action]] またはその子クラスを拡張するアクションクラスの形で定義されるものです。
例えば、Yii のリリースに [[yii\web\ViewAction]] と [[yii\web\ErrorAction]] が含まれていますが、これらは両方ともスタンドアロンアクションです。
スタンドアロンアクションを使用するためには、下記のように、コントローラの [[yii\base\Controller::actions()]]
メソッドをオーバーライドして、スタンドアロンアクションを *アクションマップ* の中で宣言します。
スタンドアロンアクションを使用するためには、下記のように、コントローラの [[yii\base\Controller::actions()]] メソッドをオーバーライドして、*アクションマップ* の中でスタンドアロンアクションを宣言しなければなりません。
```php
public function actions()
......@@ -278,12 +268,10 @@ public function actions()
}
```
見ると分かるように、`actions()` メソッドは、キーがアクション ID であり、値が対応するアクションのクラス名または [構成情報](concept-configurations.md) である配列を返すべきものです
ご覧のように、`actions()` メソッドは、キーがアクション ID であり、値が対応するアクションのクラス名または [構成情報](concept-configurations.md) である配列を返さなければなりません
インラインアクションと違って、スタンドアロンアクションのアクション ID は、`actions()` メソッドにおいて宣言される限りにおいて、任意の文字を含むことが出来ます。
スタンドアロンアクションクラスを作成するためには、[[yii\base\Action]] またはその子クラスを拡張して、
`run()` という名前の public メソッドを実装しなければなりません。
スタンドアロンアクションクラスを作成するためには、[[yii\base\Action]] またはその子クラスを拡張して、`run()` という名前の public メソッドを実装しなければなりません。
`run()` メソッドの役割はアクションメソッドのそれと似たようなものです。例えば、
```php
......@@ -302,14 +290,14 @@ class HelloWorldAction extends Action
```
### アクションの結果<span id="action-results"></span>
### アクションの結果 <span id="action-results"></span>
アクションメソッド、または、スタンドアロンアクションの `run()` メソッドの返り値は、重要な意味を持ちます。
それは、対応するアクションの結果を表すものです。
返り値は、エンドユーザにレスポンスとして送信される [レスポンス](runtime-responses.md) オブジェクトとすることが出来ます。
* [[yii\web\Application|ウェブアプリケーション]] では、[[yii\web\Response::data]] に割り当てられて後にレスポンスの本文を表す文字列へと変換される、任意のデータとすることも出来ます。
* [[yii\web\Application|ウェブアプリケーション]] では、返り値を [[yii\web\Response::data]] に割り当てられる任意のデータとすることも出来ます。このデータは、後に、レスポンスの本文を表す文字列へと変換されます。
* [[yii\console\Application|コンソールアプリケーション]] では、返り値をコマンド実行の [[yii\console\Response::exitStatus|終了ステータス]] を示す整数とすることも出来ます。
これまでに示した例においては、アクションの結果はすべて文字列であり、エンドユーザに送信されるレスポンスの本文として扱われるものでした。
......@@ -325,9 +313,9 @@ public function actionForward()
```
### アクションパラメータ<span id="action-parameters"></span>
### アクションパラメータ <span id="action-parameters"></span>
インラインアクションのアクションメソッドと、スタンドアロンアクションの `run()` メソッドは、*アクションパラメータ* と呼ばれる引数を取ることが出来ます。
インラインアクションのアクションメソッドと、スタンドアロンアクションの `run()` メソッドは、*アクションパラメータ* と呼ばれるパラメータを取ることが出来ます。
パラメータの値はリクエストから取得されます。
[[yii\web\Application|ウェブアプリケーション]] では、各アクションパラメータの値は `$_GET` からパラメータ名をキーとして読み出されます。
[[yii\console\Application|コンソールアプリケーション]] では、アクションパラメータはコマンドライン引数に対応します。
......@@ -348,15 +336,15 @@ class PostController extends Controller
}
```
アクションパラメータは、次のように、さまざまなリクエストに応じて値を投入されます。
アクションパラメータには、次のように、さまざまなリクエストに応じて異なる値が投入されます。
* `http://hostname/index.php?r=post/view&id=123`: `$id` パラメータには `'123'` という値が入れられますが、`version`
というクエリパラメータは無いので、`$version` は null のままになります。
* `http://hostname/index.php?r=post/view&id=123`: `$id` パラメータには `'123'` という値が入れられます
一方、`version` というクエリパラメータは無いので、`$version` は null のままになります。
* `http://hostname/index.php?r=post/view&id=123&version=2`: `$id` および `$version` パラメータに、それぞれ、`'123'``'2'` が入ります。
* `http://hostname/index.php?r=post/view`: 必須の `$id` パラメータがリクエストで提供されていないため、 [[yii\web\BadRequestHttpException]] 例外が投げられます。
* `http://hostname/index.php?r=post/view&id[]=123`: `$id` パラメータが予期しない配列値 `['123']` を受け取ろうとするため、[[yii\web\BadRequestHttpException]] 例外が投げられます。
アクションパラメータに配列値を受け取らせたい場合は、以下のように、パラメータに `array` の型ヒントを付けなければなりません。
アクションパラメータに配列値を受け取らせたい場合は、のように、パラメータに `array` の型ヒントを付けなければなりません。
```php
public function actionView(array $id, $version = null)
......@@ -365,19 +353,19 @@ public function actionView(array $id, $version = null)
}
```
このようにすると、リクエストが `http://hostname/index.php?r=post/view&id[]=123` である場合`$id` パラメータは `['123']` という値を受け取るようになります。
このようにすると、リクエストが `http://hostname/index.php?r=post/view&id[]=123` である場合は、`$id` パラメータは `['123']` という値を受け取ります。
リクエストが `http://hostname/index.php?r=post/view&id=123` である場合も、スカラ値 `'123'` が自動的に配列に変換されるため、`$id` パラメータは引き続き同じ配列値を受け取ります。
上記の例は主としてウェブアプリケーションでのアクションパラメータの動作を示すものです。
コンソールアプリケーションについては、[コンソールコマンド](tutorial-console.md) の節で詳細を参照してください。
### デフォルトアクション<span id="default-action"></span>
### デフォルトアクション <span id="default-action"></span>
すべてのコントローラは、それぞれ、[[yii\base\Controller::defaultAction]] によって定されるデフォルトアクションを持ちます。
[ルート](#ids-routes) がコントローラ ID のみを含む場合は、指定されたコントローラのデフォルトアクションがリクエストされたことを意味します。
すべてのコントローラは、それぞれ、[[yii\base\Controller::defaultAction]] によって定されるデフォルトアクションを持ちます。
[ルート](#routes) がコントローラ ID のみを含む場合は、指定されたコントローラのデフォルトアクションがリクエストされたことを意味します。
既定では、デフォルトアクションは `index` と設定されます。
デフォルトでは、デフォルトアクションは `index` と設定されます。
このデフォルト値を変更したい場合は、以下のように、コントローラクラスでこのプロパティをオーバーライドするだけです。
```php
......@@ -397,7 +385,7 @@ class SiteController extends Controller
```
## コントローラのライフサイクル<span id="controller-lifecycle"></span>
## コントローラのライフサイクル <span id="controller-lifecycle"></span>
リクエストを処理するときに、[アプリケーション](structure-applications.md) はリクエストされた [ルート](#routes) に基いてコントローラを作成します。
そして、次に、コントローラはリクエストに応じるために以下のライフサイクルを経過します。
......@@ -407,18 +395,18 @@ class SiteController extends Controller
* アクション ID が指定されていないときは、[[yii\base\Controller::defaultAction|デフォルトアクション ID]] が使われる。
* アクション ID が [[yii\base\Controller::actions()|アクションマップ]] の中に見つかった場合は、スタンドアロンアクションが作成される。
* アクション ID に合致するアクションメソッドが見つかった場合は、インラインアクションが作成される。
* アクションが見つからないと[[yii\base\InvalidRouteException]] 例外が投げられる。
* 上記以外の場合は[[yii\base\InvalidRouteException]] 例外が投げられる。
3. コントローラは、アプリケーション、(コントローラがモジュールに属する場合は) モジュール、そしてコントローラの `beforeAction()` メソッドをこの順で呼び出す。
* どれか一つの呼び出しが false を返した場合は、残りのまだ呼ばれていない `beforeAction()` はスキップされ、アクションの実行はキャンセルされる。
* 既定では、それぞれの `beforeAction()` メソッドは、ハンドラをアタッチすることが可能な `beforeAction` イベントをトリガする。
4. コントローラがアクションを走らせる。
* デフォルトでは、それぞれの `beforeAction()` メソッドは、ハンドラをアタッチすることが可能な `beforeAction` イベントをトリガする。
4. コントローラがアクションを実行する。
* リクエストデータが解析されて、アクションパラメータにデータが投入される。
5. コントローラは、コントローラ、(コントローラがモジュールに属する場合は) モジュール、そしてアプリケーションの `afterAction()` メソッドをこの順で呼び出す。
* 既定では、それぞれの `afterAction()` メソッドは、ハンドラをアタッチすることが可能な `afterAction` イベントをトリガする。
* デフォルトでは、それぞれの `afterAction()` メソッドは、ハンドラをアタッチすることが可能な `afterAction` イベントをトリガする。
6. アプリケーションはアクションの結果を受け取り、それを [レスポンス](runtime-responses.md) に割り当てる。
## ベストプラクティス<span id="best-practices"></span>
## ベストプラクティス <span id="best-practices"></span>
良く設計されたアプリケーションでは、コントローラはたいてい非常に軽いものになり、それぞれのアクションは数行のコードしか含まないものになります。
あなたのコントローラが少々複雑になっている場合、そのことは、通常、コントローラをリファクタして、コードの一部を他のクラスに移動すべきことを示すものです。
......
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