Commit e70e0b34 by Alexander Makarov

Merge pull request #6330 from softark/docs-guide-ja-structure-revised

Docs guide ja structure revised [ci skip]
parents b1c69c47 03e1d93c
決定版 Yii 2.0 ガイド Yii 2.0 決定版ガイド
===================== ====================
このチュートリアルは [Yii ドキュメント規約](http://www.yiiframework.com/doc/terms/) の下にリリースされています。 このチュートリアルは [Yii ドキュメント規約](http://www.yiiframework.com/doc/terms/) の下にリリースされています。
...@@ -54,7 +54,7 @@ All Rights Reserved. ...@@ -54,7 +54,7 @@ All Rights Reserved.
* [レスポンス](runtime-responses.md) * [レスポンス](runtime-responses.md)
* [セッションとクッキー](runtime-sessions-cookies.md) * [セッションとクッキー](runtime-sessions-cookies.md)
* [エラー処理](runtime-handling-errors.md) * [エラー処理](runtime-handling-errors.md)
* [ログ](runtime-logging.md) * [ギン](runtime-logging.md)
鍵となる概念 鍵となる概念
......
...@@ -3,11 +3,10 @@ ...@@ -3,11 +3,10 @@
アプリケーションは [サービスロケータ](concept-service-locator.md) です。 アプリケーションは [サービスロケータ](concept-service-locator.md) です。
アプリケーションは、リクエストを処理するためのいろいろなサービスを提供する一連のオブジェクト、いわゆる *アプリケーションコンポーネント* をホストします。 アプリケーションは、リクエストを処理するためのいろいろなサービスを提供する一連のオブジェクト、いわゆる *アプリケーションコンポーネント* をホストします。
例えば、`urlManager` がウェブリクエストを適切なコントローラにルーティングする役割を負い、 例えば、`urlManager` がウェブリクエストを適切なコントローラにルーティングする役割を負い、`db` コンポーネントが DB 関連のサービスを提供する、等々です。
`db` コンポーネントが DB 関連のサービスを提供する、等々です。
全てのアプリケーションコンポーネントは、それぞれ、同一のアプリケーション内で他のアプリケーションコンポーネントから区別できるように、ユニークな ID を持ちます。 全てのアプリケーションコンポーネントは、それぞれ、同一のアプリケーション内で他のアプリケーションコンポーネントから区別できるように、ユニークな ID を持ちます。
アプリケーションコンポーネントには、次の式によってアクセス出来ます: アプリケーションコンポーネントには、次の式によってアクセス出来ます
```php ```php
\Yii::$app->componentID \Yii::$app->componentID
...@@ -20,7 +19,7 @@ ...@@ -20,7 +19,7 @@
二度目以降のアクセスでは、同じコンポーネントのインスタンスが返されます。 二度目以降のアクセスでは、同じコンポーネントのインスタンスが返されます。
どのようなオブジェクトでも、アプリケーションコンポーネントとすることが可能です。 どのようなオブジェクトでも、アプリケーションコンポーネントとすることが可能です。
[アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) の中で [[yii\base\Application::components]] プロパティを構成することによって、アプリケーションコンポーネントを登録することが出来ます。 [アプリケーションの構成情報](structure-applications.md#application-configurations) の中で [[yii\base\Application::components]] プロパティを構成することによって、アプリケーションコンポーネントを登録することが出来ます。
例えば、 例えば、
```php ```php
...@@ -29,7 +28,7 @@ ...@@ -29,7 +28,7 @@
// クラス名を使って "cache" コンポーネントを登録 // クラス名を使って "cache" コンポーネントを登録
'cache' => 'yii\caching\ApcCache', 'cache' => 'yii\caching\ApcCache',
// コンフィギュレーション配列を使って "db" コンポーネントを登録 // 構成情報の配列を使って "db" コンポーネントを登録
'db' => [ 'db' => [
'class' => 'yii\db\Connection', 'class' => 'yii\db\Connection',
'dsn' => 'mysql:host=localhost;dbname=demo', 'dsn' => 'mysql:host=localhost;dbname=demo',
...@@ -46,20 +45,19 @@ ...@@ -46,20 +45,19 @@
``` ```
> Info|情報: 必要なだけ多くのアプリケーションコンポーネントを登録することが出来ますが、慎重にしなければなりません。 > Info|情報: 必要なだけ多くのアプリケーションコンポーネントを登録することが出来ますが、慎重にしなければなりません。
アプリケーションコンポーネントはグローバル変数のようなものです。あまり多くのアプリケーションコンポーネントを使うと アプリケーションコンポーネントはグローバル変数のようなものです。
コードのテストと保守が困難になるおそれがあります。 あまり多くのアプリケーションコンポーネントを使うと、コードのテストと保守が困難になるおそれがあります。
多くの場合、必要なときにローカルなコンポーネントを作成して使用するだけで十分です。 多くの場合、必要なときにローカルなコンポーネントを作成して使用するだけで十分です。
## コンポーネントをブートストラップに含める<a name="bootstrapping-components"></a> ## コンポーネントをブートストラップに含める<a name="bootstrapping-components"></a>
上述のように、アプリケーションコンポーネントは最初にアクセスされた時に初めてインスタンスが作成されます。 上述のように、アプリケーションコンポーネントは最初にアクセスされた時に初めてインスタンスが作成されます。
リクエストの間に全くアクセスされなかった時は、インスタンスは作成されません。けれども、場合によっては、 リクエストの間に全くアクセスされなかった時は、インスタンスは作成されません。
明示的にアクセスされないときでも、リクエストごとにアプリケーションコンポーネントのインスタンスを作成する必要がある けれども、場合によっては、明示的にアクセスされないときでも、リクエストごとにアプリケーションコンポーネントのインスタンスを作成したいことがあります。
ことがあります。そうするためには、アプリケーションの [[yii\base\Application::bootstrap|bootstrap]] プロパティのリストに そうするためには、アプリケーションの [[yii\base\Application::bootstrap|bootstrap]] プロパティのリストにそのコンポーネントの ID を挙げることが出来ます。
そういうコンポーネントの ID を挙げることが出来ます。
例えば、次のアプリケーションコンフィギュレーションは、`log` コンポーネントが常にロードされることを保証するものです: 例えば、次のアプリケーション構成情報は、`log` コンポーネントが常にロードされることを保証するものです。
```php ```php
[ [
...@@ -68,7 +66,7 @@ ...@@ -68,7 +66,7 @@
], ],
'components' => [ 'components' => [
'log' => [ 'log' => [
// "log" コンポーネントのコンフィギュレーション // "log" コンポーネントの構成情報
], ],
], ],
] ]
...@@ -77,43 +75,43 @@ ...@@ -77,43 +75,43 @@
## コアアプリケーションコンポーネント<a name="core-application-components"></a> ## コアアプリケーションコンポーネント<a name="core-application-components"></a>
Yii は固定の ID とデフォルトのコンフィギュレーションを持つ一連の *コア* アプリケーションコンポーネントを定義しています。 Yii は固定の ID とデフォルトの構成情報を持つ一連の *コア* アプリケーションコンポーネントを定義しています。
例えば、[[yii\web\Application::request|request]] コンポーネントは、ユーザリクエストに関する情報を収集し 例えば、[[yii\web\Application::request|request]] コンポーネントは、ユーザリクエストに関する情報を収集して、それを [ルート](runtime-routing.md) として解決するために使用されます。
それを [ルート](runtime-routing.md) として解決します。 また、[[yii\base\Application::db|db]] コンポーネントは、それを通じてデータベースクエリを実行できるデータベース接続を表現します。
[[yii\base\Application::db|db]] コンポーネントは、それを通じてデータベースクエリを実行できるデータベース接続を表現します。 Yii のアプリケーションがユーザリクエストを処理出来るのは、まさにこれらのコアアプリケーションコンポーネントの助けがあってこそです。
Yii のアプリケーションがユーザリクエストを処理することが出来るのは、まさにこれらのコアアプリケーションコンポーネントの助力によります。
下記が事前に定義されたコアアプリケーションコンポーネントです。 下記が事前に定義されたコアアプリケーションコンポーネントです。
通常のアプリケーションコンポーネントに対するのと同様に、これらを構成し、カスタマイズすることが出来ます。 通常のアプリケーションコンポーネントに対するのと同様に、これらを構成し、カスタマイズすることが出来ます。
コアアプリケーションコンポーネントを構成するときは、クラスを指定しなければ、デフォルトのクラスが使用されます。 コアアプリケーションコンポーネントを構成するときは、クラスを指定しない場合は、デフォルトのクラスが使用されます。
* [[yii\web\AssetManager|assetManager]]: アセットバンドルとアセットの発行を管理します。 * [[yii\web\AssetManager|assetManager]]: アセットバンドルとアセットの発行を管理します。
更なる詳細は [アセットを管理する](structure-assets.md) の節を参照してください。 詳細は [アセット](structure-assets.md) の節を参照してください。
* [[yii\db\Connection|db]]: データベース接続を表します。これを通じて、DB クエリを実行することが出来ます。 * [[yii\db\Connection|db]]: データベース接続を表します。これを通じて、DB クエリを実行することが出来ます。
このコンポーネントを構成するときは、コンポーネントのクラスはもちろん、 このコンポーネントを構成するときは、コンポーネントのクラスはもちろん、
[[yii\db\Connection::dsn]] のような必須のコンポーネントプロパティを指定しなければならないことに注意してください。 [[yii\db\Connection::dsn]] のような必須のコンポーネントプロパティを指定しなければならないことに注意してください。
更なる詳細は [データアクセスオブジェクト (DAO)](db-dao.md) の節を参照してください。 詳細は [データアクセスオブジェクト](db-dao.md) の節を参照してください。
* [[yii\base\Application::errorHandler|errorHandler]]: PHP のエラーと例外を処理します。 * [[yii\base\Application::errorHandler|errorHandler]]: PHP のエラーと例外を処理します。
更なる詳細は [エラー処理](runtime-handling-errors.md) の節を参照してください。 詳細は [エラー処理](runtime-handling-errors.md) の節を参照してください。
* [[yii\i18n\Formatter|formatter]]: エンドユーザに表示されるデータに書式を設定します。 * [[yii\i18n\Formatter|formatter]]: エンドユーザに表示されるデータに書式を設定します。
例えば、数字が3桁ごとの区切りを使って表示されたり、日付が長い書式で表示されたりします。 例えば、数字が3桁ごとの区切りを使って表示されたり、日付が長い書式で表示されたりします。
更なる詳細は [データの書式設定](output-formatter.md) の節を参照してください。 詳細は [データの書式設定](output-formatter.md) の節を参照してください。
* [[yii\i18n\I18N|i18n]]: メッセージの翻訳と書式設定をサポートします。 * [[yii\i18n\I18N|i18n]]: メッセージの翻訳と書式設定をサポートします。
更なる詳細は [国際化](tutorial-i18n.md) の節を参照してください。 詳細は [国際化](tutorial-i18n.md) の節を参照してください。
* [[yii\log\Dispatcher|log]]: ログの対象を管理します。 * [[yii\log\Dispatcher|log]]: ログターゲットを管理します。
更なる詳細は [](runtime-logging.md) の節を参照してください。 詳細は [ロギン](runtime-logging.md) の節を参照してください。
* [[yii\swiftmailer\Mailer|mail]]: メールの作成と送信をサポートします。 * [[yii\swiftmailer\Mailer|mail]]: メールの作成と送信をサポートします。
更なる詳細は [メール](tutorial-mailing.md) の節を参照してください。 詳細は [メール](tutorial-mailing.md) の節を参照してください。
* [[yii\base\Application::response|response]]: エンドユーザに送信されるレスポンスを表現します。 * [[yii\base\Application::response|response]]: エンドユーザに送信されるレスポンスを表現します。
更なる詳細は [レスポンス](runtime-responses.md) の節を参照してください。 詳細は [レスポンス](runtime-responses.md) の節を参照してください。
* [[yii\base\Application::request|request]]: エンドユーザから受信したリクエストを表現します。 * [[yii\base\Application::request|request]]: エンドユーザから受信したリクエストを表現します。
更なる詳細は [リクエスト](runtime-requests.md) の節を参照してください。 詳細は [リクエスト](runtime-requests.md) の節を参照してください。
* [[yii\web\Session|session]]: セッション情報を表現します。 * [[yii\web\Session|session]]: セッション情報を表現します。
このコンポーネントは、[[yii\web\Application|ウェブアプリケーション]] においてのみ利用できます。. このコンポーネントは、[[yii\web\Application|ウェブアプリケーション]] においてのみ利用できます。.
更なる詳細は [セッションとクッキー](runtime-sessions-cookies.md) の節を参照してください。 詳細は [セッションとクッキー](runtime-sessions-cookies.md) の節を参照してください。
* [[yii\web\UrlManager|urlManager]]: URL の解析と生成をサポートします。 * [[yii\web\UrlManager|urlManager]]: URL の解析と生成をサポートします。
更なる詳細は [URL の解析と生成](runtime-url-handling.md) の節を参照してください。 詳細は [ルーティング と URL 生成](runtime-routing.md) の節を参照してください。
* [[yii\web\User|user]]: ユーザの認証情報を表現します。 * [[yii\web\User|user]]: ユーザの認証情報を表現します。
このコンポーネントは、[[yii\web\Application|ウェブアプリケーション]] においてのみ利用できます。. このコンポーネントは、[[yii\web\Application|ウェブアプリケーション]] においてのみ利用できます。.
更なる詳細は [認証](security-authentication.md) の節を参照してください。 詳細は [認証](security-authentication.md) の節を参照してください。
* [[yii\web\View|view]]: ビューのレンダリングをサポートします。 * [[yii\web\View|view]]: ビューのレンダリングをサポートします。
更なる詳細は [ビュー](structure-views.md) の節を参照してください。 詳細は [ビュー](structure-views.md) の節を参照してください。
...@@ -4,36 +4,35 @@ ...@@ -4,36 +4,35 @@
アプリケーションは Yii アプリケーションシステム全体の構造とライフサイクルを統制するオブジェクトです。 アプリケーションは Yii アプリケーションシステム全体の構造とライフサイクルを統制するオブジェクトです。
全ての Yii アプリケーションシステムは、それぞれ、[エントリスクリプト](structure-entry-scripts.md) において作成され、`\Yii::$app` という式でグローバルにアクセス可能な、単一のアプリケーションオブジェクトを持ちます。 全ての Yii アプリケーションシステムは、それぞれ、[エントリスクリプト](structure-entry-scripts.md) において作成され、`\Yii::$app` という式でグローバルにアクセス可能な、単一のアプリケーションオブジェクトを持ちます。
> Info|情報: ガイドの中で「アプリケーション」という言葉は、文脈に応じて、 > Info|情報: ガイドの中で「アプリケーション」という言葉は、文脈に応じて、アプリケーションオブジェクトを意味したり、アプリケーションシステムを意味したりします。
アプリケーションオブジェクトを意味したり、アプリケーションシステムを意味したりします。
二種類のアプリケーションがあります: すなわち、[[yii\web\Application|ウェブアプリケーション]] と [[yii\console\Application|コンソールアプリケーション]] です。 二種類のアプリケーション、すなわち、[[yii\web\Application|ウェブアプリケーション]] と [[yii\console\Application|コンソールアプリケーション]] があります。
名前が示すように、前者は主にウェブのリクエストを処理し、後者はコンソールコマンドのリクエストを処理します。 名前が示すように、前者は主にウェブのリクエストを処理し、後者はコンソールコマンドのリクエストを処理します。
## アプリケーションのコンフィギュレーション<a name="application-configurations"></a> ## アプリケーションの構成情報<a name="application-configurations"></a>
[エントリスクリプト](structure-entry-scripts.md) は、アプリケーションを作成するときに、 [エントリスクリプト](structure-entry-scripts.md) は、アプリケーションを作成するときに、下記のように、[構成情報](concept-configurations.md)
下記のように、[コンフィギュレーション](concept-configurations.md) を読み込んで、それをアプリケーションに適用します: を読み込んで、それをアプリケーションに適用します。
```php ```php
require(__DIR__ . '/../vendor/autoload.php'); require(__DIR__ . '/../vendor/autoload.php');
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php'); require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
// アプリケーションのコンフィギュレーションを読み込む // アプリケーションの構成情報を読み込
$config = require(__DIR__ . '/../config/web.php'); $config = require(__DIR__ . '/../config/web.php');
// アプリケーションのインスタンスを作成し、コンフィギュレーションを適用す // アプリケーションのインスタンスを作成し、構成情報を適用する
(new yii\web\Application($config))->run(); (new yii\web\Application($config))->run();
``` ```
通常の [コンフィギュレーション](concept-configurations.md) と同じように、アプリケーションのコンフィギュレーションは、アプリケーションオブジェクトのプロパティをどのように初期化するかを規定するものです。 通常の [構成情](concept-configurations.md) と同じように、アプリケーションの構成情報は、アプリケーションオブジェクトのプロパティをどのように初期化するかを指定するものです。
アプリケーションのコンフィギュレーションは、たいていは非常に複雑なものですから、通常は、上記の例の `web.php` ファイルのように、[コンフィギュレーションファイル](concept-configurations.md#configuration-files) に保管されます。 アプリケーションの構成情報は、たいていは非常に複雑なものですから、通常は、上記の例の `web.php` ファイルのように、[構成情報ファイル](concept-configurations.md#configuration-files) に保管されます。
## アプリケーションのプロパティ<a name="application-properties"></a> ## アプリケーションのプロパティ<a name="application-properties"></a>
アプリケーションのコンフィギュレーションで構成すべき重要なアプリケーションのプロパティは数多くあります。 アプリケーションの構成情報で構成すべき重要なアプリケーションのプロパティは数多くあります。
それらのプロパティの典型的なものは、アプリケーションが走る環境を記述するものです。 それらのプロパティの典型的なものは、アプリケーションが走る環境を記述するものです。
例えば、アプリケーションは、どのようにして [コントローラ](structure-controllers.md) をロードするか、また、どこにテンポラリファイルを保存するかなどを知らなければなりません。 例えば、アプリケーションは、どのようにして [コントローラ](structure-controllers.md) をロードするか、また、どこにテンポラリファイルを保存するかなどを知らなければなりません。
以下において、それらのプロパティを要約します。 以下において、それらのプロパティを要約します。
...@@ -41,7 +40,7 @@ $config = require(__DIR__ . '/../config/web.php'); ...@@ -41,7 +40,7 @@ $config = require(__DIR__ . '/../config/web.php');
### 必須のプロパティ<a name="required-properties"></a> ### 必須のプロパティ<a name="required-properties"></a>
どのアプリケーションでも、最低二つのプロパティは構成しなければなりません: どのアプリケーションでも、最低二つのプロパティは構成しなければなりません。
すなわち、[[yii\base\Application::id|id]] と [[yii\base\Application::basePath|basePath]] です。 すなわち、[[yii\base\Application::id|id]] と [[yii\base\Application::basePath|basePath]] です。
...@@ -49,7 +48,7 @@ $config = require(__DIR__ . '/../config/web.php'); ...@@ -49,7 +48,7 @@ $config = require(__DIR__ . '/../config/web.php');
[[yii\base\Application::id|id]] プロパティは、アプリケーションを他のアプリケーションから区別するユニークな ID を規定します。 [[yii\base\Application::id|id]] プロパティは、アプリケーションを他のアプリケーションから区別するユニークな ID を規定します。
このプロパティは主としてプログラム的に使われます。 このプロパティは主としてプログラム的に使われます。
必須ではありませんが、最良の相互運用性を確保するために、アプリケーション ID を規定するときに英数字だけを使うことが推奨されます。 必須ではありませんが、最良の相互運用性を確保するために、アプリケーション ID を指定するときに英数字だけを使うことが推奨されます。
#### [[yii\base\Application::basePath|basePath]] <a name="basePath"></a> #### [[yii\base\Application::basePath|basePath]] <a name="basePath"></a>
...@@ -71,7 +70,7 @@ $config = require(__DIR__ . '/../config/web.php'); ...@@ -71,7 +70,7 @@ $config = require(__DIR__ . '/../config/web.php');
### 重要なプロパティ<a name="important-properties"></a> ### 重要なプロパティ<a name="important-properties"></a>
この項で説明するプロパティは、アプリケーションが異なるごとに異なってくるものであるため、たいてい、構成する必要が生じます。 この項で説明するプロパティは、アプリケーションごとに異なってくるものであるため、たいてい、構成する必要が生じます。
#### [[yii\base\Application::aliases|aliases]] <a name="aliases"></a> #### [[yii\base\Application::aliases|aliases]] <a name="aliases"></a>
...@@ -89,21 +88,21 @@ $config = require(__DIR__ . '/../config/web.php'); ...@@ -89,21 +88,21 @@ $config = require(__DIR__ . '/../config/web.php');
] ]
``` ```
このプロパティが提供されているのは、[[Yii::setAlias()]] メソッドを呼び出す代りに、アプリケーションのコンフィギュレーションを使ってエイリアスを定義することが出来るようにするためです。 このプロパティが提供されているのは、[[Yii::setAlias()]] メソッドを呼び出す代りに、アプリケーションの構成情報を使ってエイリアスを定義することが出来るようにするためです。
#### [[yii\base\Application::bootstrap|bootstrap]] <a name="bootstrap"></a> #### [[yii\base\Application::bootstrap|bootstrap]] <a name="bootstrap"></a>
これは非常に有用なプロパティです。 これは非常に有用なプロパティです。
これによって、アプリケーションの [[yii\base\Application::bootstrap()|ブートストラップの過程]] において走らせるべきコンポーネントを配列として規定することが出来ます。 これによって、アプリケーションの [[yii\base\Application::bootstrap()|ブートストラップの過程]] において走らせるべきコンポーネントを配列として指定することが出来ます。
例えば、ある [モジュール](structure-modules.md)[URL 規則](runtime-url-handling.md) をカスタマイズさせたいときに、モジュールの ID をこのプロパティの要素として挙げることが出来ます。 例えば、ある [モジュール](structure-modules.md)[URL 規則](runtime-routing.md) をカスタマイズさせたいときに、モジュールの ID をこのプロパティの要素として挙げることが出来ます。
このプロパティに挙げるコンポーネントは、それぞれ、以下の形式のいずれかによって規定することが出来ます: このプロパティに挙げるコンポーネントは、それぞれ、以下の形式のいずれかによって指定することが出来ます。
- [components](#components) によって規定されるアプリケーションコンポーネントの ID。 - [components](#components) によって指定されているアプリケーションコンポーネントの ID。
- [modules](#modules) によって規定されるモジュールの ID。 - [modules](#modules) によって指定されているモジュールの ID。
- クラス名。 - クラス名。
- コンフィギュレーション配列。 - 構成情報の配列。
- コンポーネントを作成して返す無名関数。 - コンポーネントを作成して返す無名関数。
例えば、 例えば、
...@@ -117,7 +116,7 @@ $config = require(__DIR__ . '/../config/web.php'); ...@@ -117,7 +116,7 @@ $config = require(__DIR__ . '/../config/web.php');
// クラス名 // クラス名
'app\components\Profiler', 'app\components\Profiler',
// コンフィギュレーション配列 // 構成情報の配
[ [
'class' => 'app\components\Profiler', 'class' => 'app\components\Profiler',
'level' => 3, 'level' => 3,
...@@ -132,7 +131,7 @@ $config = require(__DIR__ . '/../config/web.php'); ...@@ -132,7 +131,7 @@ $config = require(__DIR__ . '/../config/web.php');
``` ```
> Info|情報: モジュール ID と同じ ID のアプリケーションコンポーネントがある場合は、ブートストラップの過程ではアプリケーションコンポーネントが使われます。 > Info|情報: モジュール ID と同じ ID のアプリケーションコンポーネントがある場合は、ブートストラップの過程ではアプリケーションコンポーネントが使われます。
代りにモジュールを使いたいときは、次のように、無名関数を使って指定することが出来ます: 代りにモジュールを使いたいときは、次のように、無名関数を使って指定することが出来ます。
> ```php > ```php
[ [
function () { function () {
...@@ -144,12 +143,12 @@ $config = require(__DIR__ . '/../config/web.php'); ...@@ -144,12 +143,12 @@ $config = require(__DIR__ . '/../config/web.php');
ブートストラップの過程で、各コンポーネントのインスタンスが作成されます。 ブートストラップの過程で、各コンポーネントのインスタンスが作成されます。
そして、コンポーネントクラスが [[yii\base\BootstrapInterface]] を実装している場合は、その [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] メソッドも呼び出されます。 そして、コンポーネントクラスが [[yii\base\BootstrapInterface]] を実装している場合は、その [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] メソッドも呼び出されます。
もう一つの実用的な例が [ベーシックアプリケーションテンプレート](start-installation.md) のアプリケーションのコンフィギュレーションの中にあります。 もう一つの実用的な例が [ベーシックアプリケーションテンプレート](start-installation.md) のアプリケーションの構成情報の中にあります。
そこでは、アプリケーションが開発環境で走るときには `debug` モジュールと `gii` モジュールがブートストラップコンポーネントとして構成されています。 そこでは、アプリケーションが開発環境で走るときには `debug` モジュールと `gii` モジュールがブートストラップコンポーネントとして構成されています。
```php ```php
if (YII_ENV_DEV) { if (YII_ENV_DEV) {
// 'dev' 環境のためのコンフィギュレーションの調整 // 'dev' 環境のための構成情報の調
$config['bootstrap'][] = 'debug'; $config['bootstrap'][] = 'debug';
$config['modules']['debug'] = 'yii\debug\Module'; $config['modules']['debug'] = 'yii\debug\Module';
...@@ -166,10 +165,10 @@ if (YII_ENV_DEV) { ...@@ -166,10 +165,10 @@ if (YII_ENV_DEV) {
#### [[yii\web\Application::catchAll|catchAll]] <a name="catchAll"></a> #### [[yii\web\Application::catchAll|catchAll]] <a name="catchAll"></a>
このプロパティは [[yii\web\Application|ウェブアプリケーション]] においてのみサポートされます。 このプロパティは [[yii\web\Application|ウェブアプリケーション]] においてのみサポートされます。
これは、全てのユーザリクエストを処理すべき [コントローラアクション](structure-controllers.md) を規定します。 これは、全てのユーザリクエストを処理すべき [コントローラアクション](structure-controllers.md) を指定するものです。
これは主としてアプリケーションがメンテナンスモードにあって、入ってくる全てのリクエストを単一のアクションで処理する必要があるときに使われます。 これは主としてアプリケーションがメンテナンスモードにあって、入ってくる全てのリクエストを単一のアクションで処理する必要があるときに使われます。
コンフィギュレーションは配列の形を取り、最初の要素はアクションのルートを指定します。 構成情報は配列の形を取り、最初の要素はアクションのルートを指定します。
そして、配列の残りの要素 (キー・値のペア) は、アクションに渡されるパラメータを指定します。 そして、配列の残りの要素 (キー・値のペア) は、アクションに渡されるパラメータを指定します。
例えば、 例えば、
...@@ -186,7 +185,8 @@ if (YII_ENV_DEV) { ...@@ -186,7 +185,8 @@ if (YII_ENV_DEV) {
#### [[yii\base\Application::components|components]] <a name="components"></a> #### [[yii\base\Application::components|components]] <a name="components"></a>
これが唯一最重要なプロパティです。これによって、[アプリケーションコンポーネント](structure-application-components.md) と呼ばれる一連の名前付きのコンポーネントを登録して、それらを他の場所で使うことが出来るようになります。 これこそが、唯一最重要なプロパティです。
これによって、[アプリケーションコンポーネント](structure-application-components.md) と呼ばれる一連の名前付きのコンポーネントを登録して、それらを他の場所で使うことが出来るようになります。
例えば、 例えば、
```php ```php
...@@ -204,12 +204,12 @@ if (YII_ENV_DEV) { ...@@ -204,12 +204,12 @@ if (YII_ENV_DEV) {
``` ```
全てのアプリケーションコンポーネントは、それぞれ、配列の中で「キー・値」のペアとして規定されます。 全てのアプリケーションコンポーネントは、それぞれ、配列の中で「キー・値」のペアとして規定されます。
キーはコンポーネントの ID を示し、値はコンポーネントのクラス名または [コンフィギュレーション](concept-configurations.md) を示します。 キーはコンポーネントの ID を示し、値はコンポーネントのクラス名または [構成情報](concept-configurations.md) を示します。
どのようなコンポーネントでもアプリケーションとともに登録することが出来ます。 どのようなコンポーネントでもアプリケーションとともに登録することが出来ます。
そして登録されたコンポーネントは、後で、`\Yii::$app->ComponentID` という式を使ってグローバルにアクセスすることが出来ます。 そして登録されたコンポーネントは、後で、`\Yii::$app->ComponentID` という式を使ってグローバルにアクセスすることが出来ます。
詳細は [アプリケーションコンポーネント](structure-application-components.md) の節を呼んでください。 詳細は [アプリケーションコンポーネント](structure-application-components.md) の節を読んでください。
#### [[yii\base\Application::controllerMap|controllerMap]] <a name="controllerMap"></a> #### [[yii\base\Application::controllerMap|controllerMap]] <a name="controllerMap"></a>
...@@ -218,8 +218,7 @@ if (YII_ENV_DEV) { ...@@ -218,8 +218,7 @@ if (YII_ENV_DEV) {
既定では、Yii は [規約](#controllerNamespace) に基づいてコントローラ ID をコントローラクラスに割り付けます 既定では、Yii は [規約](#controllerNamespace) に基づいてコントローラ ID をコントローラクラスに割り付けます
(例えば、`post` という ID は `app\controllers\PostController` に割り付けられます)。 (例えば、`post` という ID は `app\controllers\PostController` に割り付けられます)。
このプロパティを構成することによって、特定のコントローラに対する規約を破ることが出来ます。 このプロパティを構成することによって、特定のコントローラに対する規約を破ることが出来ます。
下記の例では、`account` は `app\controllers\UserController` に割り付けられ、 下記の例では、`account` は `app\controllers\UserController` に割り付けられ、`article` は `app\controllers\PostController` に割り付けられることになります。
`article` は `app\controllers\PostController` に割り付けられることになります。
```php ```php
[ [
...@@ -235,22 +234,21 @@ if (YII_ENV_DEV) { ...@@ -235,22 +234,21 @@ if (YII_ENV_DEV) {
] ]
``` ```
このプロパティの配列のキーはコントローラ ID を表し、配列の値は対応するコントローラクラスの名前または [コンフィギュレーション](concept-configurations.md) を表します。 このプロパティの配列のキーはコントローラ ID を表し、配列の値は対応するコントローラクラスの名前または [構成情報](concept-configurations.md) を表します。
#### [[yii\base\Application::controllerNamespace|controllerNamespace]] <a name="controllerNamespace"></a> #### [[yii\base\Application::controllerNamespace|controllerNamespace]] <a name="controllerNamespace"></a>
このプロパティは、コントローラクラスが配置されるべき既定の名前空間を指定するものです。 このプロパティは、コントローラクラスが配置されるべき既定の名前空間を指定するものです。
デフォルト値は `app\controllers` です。 デフォルト値は `app\controllers` です。
コントローラ ID が `post` である場合、規約によって対応するコントローラの (名前空間を略した) クラス名は `PostController` となり、 コントローラ ID が `post` である場合、規約によって対応するコントローラの (名前空間を略した) クラス名は `PostController`
全修飾クラス名は `app\controllers\PostController` となります。 となり、完全修飾クラス名は `app\controllers\PostController` となります。
コントローラクラスは、この名前空間に対応するディレクトリのサブディレクトリに配置されても構いません。 コントローラクラスは、この名前空間に対応するディレクトリのサブディレクトリに配置されても構いません。
例えば、コントローラ ID として `admin/post` を仮定すると、対応するコントローラの完全修飾クラス名は `app\controllers\admin\PostController` となります。 例えば、コントローラ ID として `admin/post` を仮定すると、対応するコントローラの完全修飾クラス名は `app\controllers\admin\PostController` となります。
完全修飾のコントローラクラスが [オートロード可能](concept-autoloading.md) でなければならず、 重要なことは、完全修飾されたコントローラクラスが [オートロード可能](concept-autoloading.md) でなければならず、
コントローラクラスの実際の名前空間がこのプロパティと合致していなければならない、 コントローラクラスの実際の名前空間がこのプロパティと合致していなければならない、ということです。
ということは非常に重要なことです。
そうでないと、アプリケーションにアクセスしたときに "ページがみつかりません" というエラーを受け取ることになります。 そうでないと、アプリケーションにアクセスしたときに "ページがみつかりません" というエラーを受け取ることになります。
上述の規約を破りたい場合は、[controllerMap](#controllerMap) プロパティを構成することが出来ます。 上述の規約を破りたい場合は、[controllerMap](#controllerMap) プロパティを構成することが出来ます。
...@@ -268,15 +266,15 @@ if (YII_ENV_DEV) { ...@@ -268,15 +266,15 @@ if (YII_ENV_DEV) {
言語を指定するのには、[IETF 言語タグ](http://ja.wikipedia.org/wiki/IETF%E8%A8%80%E8%AA%9E%E3%82%BF%E3%82%B0) に従うことが推奨されます。 言語を指定するのには、[IETF 言語タグ](http://ja.wikipedia.org/wiki/IETF%E8%A8%80%E8%AA%9E%E3%82%BF%E3%82%B0) に従うことが推奨されます。
例えば、`en` は英語を意味し、`en-US` はアメリカ合衆国の英語を意味します。 例えば、`en` は英語を意味し、`en-US` はアメリカ合衆国の英語を意味します。
このプロパティに関する更なる詳細は [国際化](tutorial-i18n.md) の節で読むことが出来ます。 このプロパティに関する詳細は [国化](tutorial-i18n.md) の節で読むことが出来ます。
#### [[yii\base\Application::modules|modules]] <a name="modules"></a> #### [[yii\base\Application::modules|modules]] <a name="modules"></a>
このプロパティはアプリケーションが含む [モジュール](structure-modules.md) を規定します。 このプロパティはアプリケーションが含む [モジュール](structure-modules.md) を規定します。
このプロパティは、モジュールのクラスまたは [コンフィギュレーション](concept-configurations.md) の配列であり、 このプロパティは、モジュールの ID をキーとする、モジュールのクラスまたは [構成情報](concept-configurations.md) の配列です。
その配列のキーはモジュールの ID です。例えば、 えば、
```php ```php
[ [
...@@ -284,7 +282,7 @@ if (YII_ENV_DEV) { ...@@ -284,7 +282,7 @@ if (YII_ENV_DEV) {
// モジュールクラスで規定された "booking" モジュール // モジュールクラスで規定された "booking" モジュール
'booking' => 'app\modules\booking\BookingModule', 'booking' => 'app\modules\booking\BookingModule',
// コンフィギュレーション配列で規定された "comment" モジュール // 構成情報の配列で規定された "comment" モジュール
'comment' => [ 'comment' => [
'class' => 'app\modules\comment\CommentModule', 'class' => 'app\modules\comment\CommentModule',
'db' => 'db', 'db' => 'db',
...@@ -298,9 +296,8 @@ if (YII_ENV_DEV) { ...@@ -298,9 +296,8 @@ if (YII_ENV_DEV) {
#### [[yii\base\Application::name|name]] <a name="name"></a> #### [[yii\base\Application::name|name]] <a name="name"></a>
このプロパティはアプリケーション名を規定します。これは、エンドユーザに対して表示されるかも知れません。 このプロパティはアプリケーション名を規定します。これは、エンドユーザに対して表示されるかも知れません。[[yii\base\Application::id|id]]
[[yii\base\Application::id|id]] プロパティがユニークな値でなければならないのとは違って、このプロパティの値は プロパティがユニークな値でなければならないのとは違って、このプロパティの値は主として表示目的であり、ユニークである必要はありません。
主として表示目的であり、ユニークである必要はありません。
コードで使わないのであれば、このプロパティを構成する必要はありません。 コードで使わないのであれば、このプロパティを構成する必要はありません。
...@@ -308,9 +305,8 @@ if (YII_ENV_DEV) { ...@@ -308,9 +305,8 @@ if (YII_ENV_DEV) {
#### [[yii\base\Application::params|params]] <a name="params"></a> #### [[yii\base\Application::params|params]] <a name="params"></a>
このプロパティは、グローバルにアクセス可能なアプリケーションパラメータの配列を規定します。 このプロパティは、グローバルにアクセス可能なアプリケーションパラメータの配列を規定します。
コードの中のいたる処でハードコードされた数値や文字列を使う代りに、それらをアプリケーションパラメータとして コードの中のいたる処でハードコードされた数値や文字列を使う代りに、それらをアプリケーションパラメータとして一ヶ所で定義し、必要な場所ではそのパラメータを使うというのが良い慣行です。
一ヶ所で定義し、必要な場所ではそのパラメータを使うというのが良い慣行です。 例えば、次のように、サムネール画像のサイズをパラメータとして定義することが出来ます。
例えば、次のように、サムネール画像のサイズをパラメータとして定義することが出来ます:
```php ```php
[ [
...@@ -320,15 +316,14 @@ if (YII_ENV_DEV) { ...@@ -320,15 +316,14 @@ if (YII_ENV_DEV) {
] ]
``` ```
そして、このサイズの値を使う必要があるコードにおいては、ただ単に下記のようなコードを使うことが出来ます: そして、このサイズの値を使う必要があるコードにおいては、下記のようなコードを使うだけで済ませることが出来ます。
```php ```php
$size = \Yii::$app->params['thumbnail.size']; $size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0]; $width = \Yii::$app->params['thumbnail.size'][0];
``` ```
後でサムネールのサイズを変更すると決めたときは、アプリケーションのコンフィギュレーションにおいてのみサイズを修正すればよく、 後でサムネールのサイズを変更すると決めたときは、アプリケーションの構成情報においてのみサイズを修正すればよく、これに依存するコードには少しも触れる必要がありません。
これに依存するコードには少しも触れる必要がありません。
#### [[yii\base\Application::sourceLanguage|sourceLanguage]] <a name="sourceLanguage"></a> #### [[yii\base\Application::sourceLanguage|sourceLanguage]] <a name="sourceLanguage"></a>
...@@ -339,7 +334,7 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ...@@ -339,7 +334,7 @@ $width = \Yii::$app->params['thumbnail.size'][0];
[language](#language) プロパティと同様に、このプロパティは [IETF 言語タグ](http://ja.wikipedia.org/wiki/IETF%E8%A8%80%E8%AA%9E%E3%82%BF%E3%82%B0) に従って構成すべきです。 [language](#language) プロパティと同様に、このプロパティは [IETF 言語タグ](http://ja.wikipedia.org/wiki/IETF%E8%A8%80%E8%AA%9E%E3%82%BF%E3%82%B0) に従って構成すべきです。
例えば、`en` は英語を意味し、`en-US` はアメリカ合衆国の英語を意味します。 例えば、`en` は英語を意味し、`en-US` はアメリカ合衆国の英語を意味します。
このプロパティに関する更なる詳細は [国際化](tutorial-i18n.md) の節で読むことが出来ます。 このプロパティに関する詳細は [国化](tutorial-i18n.md) の節で読むことが出来ます。
#### [[yii\base\Application::timeZone|timeZone]] <a name="timeZone"></a> #### [[yii\base\Application::timeZone|timeZone]] <a name="timeZone"></a>
...@@ -363,27 +358,26 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ...@@ -363,27 +358,26 @@ $width = \Yii::$app->params['thumbnail.size'][0];
### 有用なプロパティ <a name="useful-properties"></a> ### 有用なプロパティ <a name="useful-properties"></a>
この項で説明されるプロパティは通常は構成されません。というのは、そのデフォルト値が通常の規約を規定するものだからです。 この項で説明されるプロパティは通常は構成されません。というのは、そのデフォルト値が通常の規約を指定しているからです。
しかしながら、規約を破る必要がある場合には、これらのプロパティを構成することが出来ます。 しかしながら、規約を破る必要がある場合には、これらのプロパティを構成することが出来ます。
#### [[yii\base\Application::charset|charset]] <a name="charset"></a> #### [[yii\base\Application::charset|charset]] <a name="charset"></a>
このプロパティはアプリケーションが使う文字セットを規定します。デフォルト値は `'UTF-8'` であり、 このプロパティはアプリケーションが使う文字セットを規定します。
あなたのアプリケーションが多数の非ユニコードデータを使うレガシーシステムと連携するのでなければ、 デフォルト値は `'UTF-8'` であり、あなたのアプリケーションが多数の非ユニコードデータを使うレガシーシステムと連携するのでなければ、そのままにしておくべきです。
そのままにしておくべきです。
#### [[yii\base\Application::defaultRoute|defaultRoute]] <a name="defaultRoute"></a> #### [[yii\base\Application::defaultRoute|defaultRoute]] <a name="defaultRoute"></a>
このプロパティは、リクエストがルートを指定していないときにアプリケーションが使用すべき [route](runtime-routing.md) を規定します。 このプロパティは、リクエストがルートを指定していないときにアプリケーションが使用すべき [ルート](runtime-routing.md) を規定します
ルートは、チャイルドモジュール ID、コントローラ ID、および/または アクション ID を構成要素とすることが出来ます。 ルートは、チャイルドモジュール ID、コントローラ ID、および/または アクション ID を構成要素とすることが出来ます。
例えば、`help`、`post/create`、`admin/post/create` などです。 例えば、`help`、`post/create`、`admin/post/create` などです。
アクション ID が与えられていない場合は、[[yii\base\Controller::defaultAction]] で規定されるデフォルト値を取ります。 アクション ID が与えられていない場合は、[[yii\base\Controller::defaultAction]] で規定されるデフォルト値を取ります。
[[yii\web\Application|ウェブアプリケーション]] では、このプロパティのデフォルト値は `'site'` であり、 [[yii\web\Application|ウェブアプリケーション]] では、このプロパティのデフォルト値は `'site'` であり、その意味するところは、`SiteController`
その意味するところは、`SiteController` コントローラとそのデフォルトアクションが使用されるべきである、ということです。 コントローラとそのデフォルトアクションが使用されるべきである、ということです。結果として、ルートを指定せずにアプリケーションにアクセスすると、`app\controllers\SiteController::actionIndex()`
結果として、ルートを指定せずにアプリケーションにアクセスすると、`app\controllers\SiteController::actionIndex()` の結果が表示されます。 の結果が表示されます。
[[yii\console\Application|コンソールアプリケーション]] では、デフォルト値は `'help'` であり、コアコマンドの [[yii\console\controllers\HelpController::actionIndex()]] が使用されるべきであるという意味です。 [[yii\console\Application|コンソールアプリケーション]] では、デフォルト値は `'help'` であり、コアコマンドの [[yii\console\controllers\HelpController::actionIndex()]] が使用されるべきであるという意味です。
結果として、引数を与えずに `yii` というコマンドを走らせると、ヘルプ情報が表示されることになります。 結果として、引数を与えずに `yii` というコマンドを走らせると、ヘルプ情報が表示されることになります。
...@@ -396,7 +390,7 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ...@@ -396,7 +390,7 @@ $width = \Yii::$app->params['thumbnail.size'][0];
`extensions.php` は、[Composer](http://getcomposer.org) を使ってエクステンションをインストールすると、自動的に生成され保守されます。 `extensions.php` は、[Composer](http://getcomposer.org) を使ってエクステンションをインストールすると、自動的に生成され保守されます。
ですから、たいていの場合、このプロパティをあなたが構成する必要はありません。 ですから、たいていの場合、このプロパティをあなたが構成する必要はありません。
エクステンションを手作業で保守したいという特殊なケースにおいては、次のようにしてこのプロパティを構成することが出来ます: エクステンションを手作業で保守したいという特殊なケースにおいては、次のようにしてこのプロパティを構成することが出来ます。
```php ```php
[ [
...@@ -404,7 +398,7 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ...@@ -404,7 +398,7 @@ $width = \Yii::$app->params['thumbnail.size'][0];
[ [
'name' => 'extension name', 'name' => 'extension name',
'version' => 'version number', 'version' => 'version number',
'bootstrap' => 'BootstrapClassName', // オプション、コンフィギュレーション配列でもよい 'bootstrap' => 'BootstrapClassName', // オプション、構成情報の配列でもよい
'alias' => [ // optional 'alias' => [ // optional
'@alias1' => 'to/path1', '@alias1' => 'to/path1',
'@alias2' => 'to/path2', '@alias2' => 'to/path2',
...@@ -419,17 +413,16 @@ $width = \Yii::$app->params['thumbnail.size'][0]; ...@@ -419,17 +413,16 @@ $width = \Yii::$app->params['thumbnail.size'][0];
見て分かるように、このプロパティはエクステンションの仕様を示す配列を取ります。 見て分かるように、このプロパティはエクステンションの仕様を示す配列を取ります。
それぞれのエクステンションは、`name` と `version` の要素を含む配列によって規定されます。 それぞれのエクステンションは、`name` と `version` の要素を含む配列によって規定されます。
エクステンションが [ブートストラップ](runtime-bootstrapping.md) の過程で走る必要がある場合には、 エクステンションが [ブートストラップ](runtime-bootstrapping.md) の過程で走る必要がある場合には、`bootstrap` 要素をブートストラップのクラス名または [構成情報](concept-configurations.md)
`bootstrap` 要素をブートストラップのクラス名または [コンフィギュレーション](concept-configurations.md) 配列によって規定することが出来ます。 の配列によって規定することが出来ます。また、エクステンションはいくつかの [エイリアス](concept-aliases.md) を定義することも出来ます。
また、エクステンションはいくつかの [エイリアス](concept-aliases.md) を定義することも出来ます。
#### [[yii\base\Application::layout|layout]] <a name="layout"></a> #### [[yii\base\Application::layout|layout]] <a name="layout"></a>
このプロパティは、[ビュー](structure-views.md) をレンダリングするときに使われるべきデフォルトのレイアウトを規定します。 このプロパティは、[ビュー](structure-views.md) をレンダリングするときに使われるべきデフォルトのレイアウトを規定します。
デフォルト値は `'main'` であり、[レイアウトパス](#layoutPath) の下にある `main.php` というファイルが使われるべき事を意味します。 デフォルト値は `'main'` であり、[レイアウトパス](#layoutPath) の下にある `main.php` というファイルが使われるべき事を意味します。
[レイアウトパス](#layoutPath) と [ビューパス](#viewPath) の両方がデフォルト値を取る場合、 [レイアウトパス](#layoutPath) と [ビューパス](#viewPath) の両方がデフォルト値を取る場合、デフォルトのレイアウトファイルは
デフォルトのレイアウトファイルは `@app/views/layouts/main.php` というパスエイリアスとして表すことが出来ます。 `@app/views/layouts/main.php` というパスエイリアスとして表すことが出来ます。
滅多には無いことですが、レイアウトをデフォルトで無効にしたい場合は、このプロパティを `false` として構成することが出来ます。 滅多には無いことですが、レイアウトをデフォルトで無効にしたい場合は、このプロパティを `false` として構成することが出来ます。
...@@ -483,7 +476,7 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪° ...@@ -483,7 +476,7 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪°
## アプリケーションのイベント<a name="application-events"></a> ## アプリケーションのイベント<a name="application-events"></a>
アプリケーションはリクエストを処理するライフサイクルの中でいくつかのイベントをトリガします。 アプリケーションはリクエストを処理するライフサイクルの中でいくつかのイベントをトリガします。
これらのイベントに対して、下記のようにして、アプリケーションのコンフィギュレーションの中でイベントハンドラを取り付けることが出来ます。 これらのイベントに対して、下記のようにして、アプリケーションの構成情報の中でイベントハンドラをアタッチすることが出来ます。
```php ```php
[ [
...@@ -493,9 +486,9 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪° ...@@ -493,9 +486,9 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪°
] ]
``` ```
`on eventName` という構文の使い方については、[コンフィギュレーション](concept-configurations.md#configuration-format) の節で説明されています。 `on eventName` という構文の使い方については、[構成情報](concept-configurations.md#configuration-format) の節で説明されています。
別の方法として、アプリケーションのインスタンスが生成された後、[ブートストラップの過程](runtime-bootstrapping.md) の中でイベントハンドラを取り付けることも出来ます。 別の方法として、アプリケーションのインスタンスが生成された後、[ブートストラップの過程](runtime-bootstrapping.md) の中でイベントハンドラをアタッチすることも出来ます。
例えば、 例えば、
```php ```php
...@@ -545,8 +538,7 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪° ...@@ -545,8 +538,7 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪°
] ]
``` ```
同じ `beforeAction` イベントが、[モジュール](structure-modules.md) と [コントローラ](structure-controllers.md) 同じ `beforeAction` イベントが、[モジュール](structure-modules.md) と [コントローラ](structure-controllers.md) からもトリガされることに注意してください。
からもトリガされることに注意してください。
アプリケーションオブジェクトが最初にこのイベントをトリガし、次に (もし有れば) モジュールが、そして最後にコントローラがこのイベントをトリガします。 アプリケーションオブジェクトが最初にこのイベントをトリガし、次に (もし有れば) モジュールが、そして最後にコントローラがこのイベントをトリガします。
イベントハンドラが [[yii\base\ActionEvent::isValid]] を `false` にセットすると、後続のイベントはトリガされません。 イベントハンドラが [[yii\base\ActionEvent::isValid]] を `false` にセットすると、後続のイベントはトリガされません。
...@@ -571,8 +563,7 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪° ...@@ -571,8 +563,7 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪°
] ]
``` ```
同じ `afterAction` イベントが、[モジュール](structure-modules.md)[コントローラ](structure-controllers.md) 同じ `afterAction` イベントが、[モジュール](structure-modules.md)[コントローラ](structure-controllers.md) からもトリガされることに注意してください。
からもトリガされることに注意してください。
これらのオブジェクトは、`beforeAction` の場合とは逆の順でイベントをトリガします。 これらのオブジェクトは、`beforeAction` の場合とは逆の順でイベントをトリガします。
すなわち、コントローラオブジェクトが最初にこのイベントをトリガし、次に (もし有れば) モジュールが、そして最後にアプリケーションがこのイベントをトリガします。 すなわち、コントローラオブジェクトが最初にこのイベントをトリガし、次に (もし有れば) モジュールが、そして最後にアプリケーションがこのイベントをトリガします。
...@@ -581,18 +572,17 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪° ...@@ -581,18 +572,17 @@ Yii 繝ェ繝ェ繝シ繧ケ縺ォ蜷ォ縺セ繧後※縺k繧ウ繧「繧ウ繝槭Φ繝峨r譛牙柑縺ォ縺吶∋縺阪°
![アプリケーションのライフサイクル](images/application-lifecycle.png) ![アプリケーションのライフサイクル](images/application-lifecycle.png)
[エントリスクリプト](structure-entry-scripts.md) が実行されて、リクエストが処理されるとき、 [エントリスクリプト](structure-entry-scripts.md) が実行されて、リクエストが処理されるとき、アプリケーションは次のようなライフサイクルを経ます。
アプリケーションは次のようなライフサイクルを経ます:
1. エントリスクリプトがアプリケーションのコンフィギュレーションを配列として読み出す。 1. エントリスクリプトがアプリケーションの構成情報を配列として読み出す。
2. エントリスクリプトがアプリケーションの新しいインスタンスを作成する: 2. エントリスクリプトがアプリケーションの新しいインスタンスを作成する。
* [[yii\base\Application::preInit()|preInit()]] が呼び出されて、[[yii\base\Application::basePath|basePath]] * [[yii\base\Application::preInit()|preInit()]] が呼び出されて、[[yii\base\Application::basePath|basePath]]
のような、優先度の高いアプリケーションプロパティを構成する。 のような、優先度の高いアプリケーションプロパティを構成する。
* [[yii\base\Application::errorHandler|エラーハンドラ]] を登録する。 * [[yii\base\Application::errorHandler|エラーハンドラ]] を登録する。
* アプリケーションのプロパティを構成する。 * アプリケーションのプロパティを構成する。
* [[yii\base\Application::init()|init()]] が呼ばれ、そこから更に、ブートストラップコンポーネントを * [[yii\base\Application::init()|init()]] が呼ばれ、そこから更に、ブートストラップコンポーネントを
走らせるために、[[yii\base\Application::bootstrap()|bootstrap()]] が呼ばれる。 走らせるために、[[yii\base\Application::bootstrap()|bootstrap()]] が呼ばれる。
3. エントリスクリプトが [[yii\base\Application::run()]] を呼んで、アプリケーションを走らせる: 3. エントリスクリプトが [[yii\base\Application::run()]] を呼んで、アプリケーションを走らせる。
* [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] イベントをトリガする。 * [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] イベントをトリガする。
* リクエストを処理する: リクエストを [ルート](runtime-routing.md) とそれに結び付くパラメータとして解決する; * リクエストを処理する: リクエストを [ルート](runtime-routing.md) とそれに結び付くパラメータとして解決する;
ルートによって指定されたモジュール、コントローラ、および、アクションを作成する; そしてアクションを走らせる。 ルートによって指定されたモジュール、コントローラ、および、アクションを作成する; そしてアクションを走らせる。
......
アセット アセット
======== ========
Yii では、アセットは、ウェブページで参照できるファイルを意味します。CSS ファイルであったり、JavaScript ファイルであったり、 Yii では、アセットは、ウェブページで参照できるファイルを意味します。
画像やビデオのファイルであったりします。アセットはウェブでアクセス可能なディレクトリに配置され、 アセットは CSS ファイルであったり、JavaScript ファイルであったり、画像やビデオのファイルであったりします。
ブサーバによって直接に提供されます。 セットはウェブでアクセス可能なディレクトリに配置され、ウェブサーバによって直接に提供されます。
たいていの場合、アセットはプログラム的に管理する方が望ましいものです。例えば、ページの中で [[yii\jui\DatePicker]] たいていの場合、アセットはプログラム的に管理する方が望ましいものです。
ウィジェットを使うとき、ウィジェットが必要な CSS と JavaScript のファイルを自動的にインクルードします。あなたに対して、 例えば、ページの中で [[yii\jui\DatePicker]] ウィジェットを使うとき、ウィジェットが必要な CSS と JavaScript のファイルを自動的にインクルードします。
手作業で必要なファイルを探してインクルードするように要求したりはしません。そして、ウィジェットを新しいバージョンに あなたに対して、手作業で必要なファイルを探してインクルードするように要求したりはしません。
アップグレードしたときは、ウィジェットが自動的に新しいバージョンのアセットファイルを使用するようになります。 そして、ウィジェットを新しいバージョンにアップグレードしたときは、ウィジェットが自動的に新しいバージョンのアセットファイルを使用するようになります。
このチュートリアルでは、Yii によって提供される強力なアセット管理機能について説明します。 このチュートリアルでは、Yii によって提供される強力なアセット管理機能について説明します。
## アセットバンドル <a name="asset-bundles"></a> ## アセットバンドル <a name="asset-bundles"></a>
Yii はアセットを *アセットバンドル* を単位として管理します。アセットバンドルは、単にあるディレクトリの下に集められた Yii はアセットを *アセットバンドル* を単位として管理します。アセットバンドルは、簡単に言えば、あるディレクトリの下に集められた一群のアセットです。
一群のアセットに過ぎません。[ビュー](structure-views.md) の中でアセットバンドルを登録すると、バンドルの中の CSS や [ビュー](structure-views.md) の中でアセットバンドルを登録すると、バンドルの中の CSS や JavaScript のファイルがレンダリングされるウェブページに挿入されます。
JavaScript のファイルがレンダリングされるウェブページに挿入されます。
## アセットバンドルを定義する <a name="defining-asset-bundles"></a> ## アセットバンドルを定義する <a name="defining-asset-bundles"></a>
アセットバンドルは [[yii\web\AssetBundle]] から拡張された PHP クラスとして定義されます。バンドルの名前は、対応する PHP アセットバンドルは [[yii\web\AssetBundle]] から拡張された PHP クラスとして定義されます。
クラスの完全修飾名 (先頭のバックスラッシュを除く) です。アセットバンドルクラスは [オートロード可能](concept-autoloading.md) バンドルの名前は、対応する PHP クラスの完全修飾名 (先頭のバックスラッシュを除く) です。
でなければなりません。アセットバンドルクラスは、通常、アセットがどこに置かれているか、バンドルがどういう CSS や JavaScript アセットバンドルクラスは [オートロード可能](concept-autoloading.md) でなければなりません。
のファイルを含んでいるか、そして、バンドルが他のバンドルにどのように依存しているかを定義します。 アセットバンドルクラスは、通常、アセットがどこに置かれているか、バンドルがどういう CSS や JavaScript のファイルを含んでいるか、そして、バンドルが他のバンドルにどのように依存しているかを定義します。
以下のコードは [ベーシックアプリケーションテンプレート](start-installation.md) によって使用されているメインのアセットバンドルを定義するものです: 以下のコードは [ベーシックアプリケーションテンプレート](start-installation.md) によって使用されているメインのアセットバンドルを定義するものです。
```php ```php
<?php <?php
...@@ -51,35 +50,33 @@ class AppAsset extends AssetBundle ...@@ -51,35 +50,33 @@ class AppAsset extends AssetBundle
} }
``` ```
上の `AppAsset` クラスは、アセットファイルが `@webroot` ディレクトリの下に配置されており、それが URL `@web` に対応することを 上の `AppAsset` クラスは、アセットファイルが `@webroot` ディレクトリの下に配置されており、それが URL `@web` に対応することを定義しています。
定義しています。バンドルは一つだけ CSS ファイル `css/site.css` を含み、JavaScript ファイルは含みません。バンドルは、 バンドルは一つだけ CSS ファイル `css/site.css` を含み、JavaScript ファイルは含みません。
の二つのバンドル、すなわち [[yii\web\YiiAsset]] と [[yii\bootstrap\BootstrapAsset]] に依存しています。 バンドルは、他の二つのバンドル、すなわち [[yii\web\YiiAsset]] と [[yii\bootstrap\BootstrapAsset]] に依存しています。
以下、[[yii\web\AssetBundle]] のプロパティに関して、更に詳細に説明します。 以下、[[yii\web\AssetBundle]] のプロパティに関して、更に詳細に説明します。
* [[yii\web\AssetBundle::sourcePath|sourcePath]]: このバンドルのアセットファイルを含むルートディレクトリを指定します。 * [[yii\web\AssetBundle::sourcePath|sourcePath]]: このバンドルのアセットファイルを含むルートディレクトリを指定します。
ルートディレクトリがウェブからアクセス可能でない場合はこのプロパティをセットしなければなりません。ウェブからアクセス可能な場合は、 ルートディレクトリがウェブからアクセス可能でない場合に、このプロパティをセットしなければなりません。
かわりに [[yii\web\AssetBundle::basePath|basePath]] と [[yii\web\AssetBundle::baseUrl|baseUrl]] のプロパティをセットすべきです。 ルートディレクトリがウェブからアクセス可能な場合は、このプロパティではなく、[[yii\web\AssetBundle::basePath|basePath]] と [[yii\web\AssetBundle::baseUrl|baseUrl]] のプロパティをセットすべきです。
[パスエイリアス](concept-aliases.md) をここで使うことが出来ます。 [パスエイリアス](concept-aliases.md) をここで使うことが出来ます。
* [[yii\web\AssetBundle::basePath|basePath]]: このバンドルのアセットファイルを含むウェブからアクセス可能なディレクトリを指定します。 * [[yii\web\AssetBundle::basePath|basePath]]: このバンドルのアセットファイルを含むウェブからアクセス可能なディレクトリを指定します。
[[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティをセットした場合は、[アセットマネージャ](#asset-manager) がバンドルに [[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティをセットした場合は、[アセットマネージャ](#asset-manager) がバンドルに含まれるファイルをウェブからアクセス可能なディレクトリに発行して、その結果、このプロパティを上書きします。
含まれるファイルをウェブからアクセス可能なディレクトリに発行して、その結果に応じてこのプロパティを上書きします。
アセットファイルが既にウェブからアクセス可能なディレクトリにあり、アセットの発行が必要でない場合に、このプロパティをセットすべきです。 アセットファイルが既にウェブからアクセス可能なディレクトリにあり、アセットの発行が必要でない場合に、このプロパティをセットすべきです。
[パスエイリアス](concept-aliases.md) をここで使うことが出来ます。 [パスエイリアス](concept-aliases.md) をここで使うことが出来ます。
* [[yii\web\AssetBundle::baseUrl|baseUrl]]: [[yii\web\AssetBundle::basePath|basePath]] ディレクトリに対応する URL を指定します。 * [[yii\web\AssetBundle::baseUrl|baseUrl]]: [[yii\web\AssetBundle::basePath|basePath]] ディレクトリに対応する URL を指定します。
[[yii\web\AssetBundle::basePath|basePath]] と同じように、[[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティをセットした場合は、 [[yii\web\AssetBundle::basePath|basePath]] と同じように、[[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティをセットした場合は、[アセットマネージャ](#asset-manager) がアセットを発行して、その結果、このプロパティを上書きします。
[アセットマネージャ](#asset-manager) がアセットを発行して、その結果に応じてこのプロパティを上書きします。
[パスエイリアス](concept-aliases.md) をここで使うことが出来ます。 [パスエイリアス](concept-aliases.md) をここで使うことが出来ます。
* [[yii\web\AssetBundle::js|js]]: このバンドルに含まれる JavaScript ファイルをリストする配列です。ディレクトリの区切りとして * [[yii\web\AssetBundle::js|js]]: このバンドルに含まれる JavaScript ファイルをリストする配列です。
ォワードスラッシュ "/" だけを使うべきことに注意してください。それぞれの JavaScript ファイルは、以下の二つの形式のどちらかによって ィレクトリの区切りとしてフォワードスラッシュ "/" だけを使うべきことに注意してください。
指定することが出来ます。 それぞれの JavaScript ファイルは、以下の二つの形式のどちらかによって指定することが出来ます。
- ローカルの JavaScript ファイルを表す相対パス (例えば `js/main.js`)。実際のファイルのパスは、この相対パスの前に - ローカルの JavaScript ファイルを表す相対パス (例えば `js/main.js`)。
[[yii\web\AssetManager::basePath]] を付けることによって決定されます。また、実際の URL は、この相対パスの前に 実際のファイルのパスは、この相対パスの前に [[yii\web\AssetManager::basePath]] を付けることによって決定されます。
[[yii\web\AssetManager::baseUrl]] を付けることによって決定されます。 また、実際の URL は、この相対パスの前に [[yii\web\AssetManager::baseUrl]] を付けることによって決定されます。
- 外部の JavaScript ファイルを表す絶対 URL。例えば、 - 外部の JavaScript ファイルを表す絶対 URL。
`http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js` 例えば、`http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js`
`//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js` など。 `//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js` など。
* [[yii\web\AssetBundle::css|css]]: このバンドルに含まれる CSS ファイルをリストする配列です。この配列の形式は、 * [[yii\web\AssetBundle::css|css]]: このバンドルに含まれる CSS ファイルをリストする配列です。
[[yii\web\AssetBundle::js|js]] の形式と同じです。 この配列の形式は、[[yii\web\AssetBundle::js|js]] の形式と同じです。
* [[yii\web\AssetBundle::depends|depends]]: このバンドルが依存しているアセットバンドルの名前をリストする配列です * [[yii\web\AssetBundle::depends|depends]]: このバンドルが依存しているアセットバンドルの名前をリストする配列です
(バンドルの依存関係については、すぐ後で説明します)。 (バンドルの依存関係については、すぐ後で説明します)。
* [[yii\web\AssetBundle::jsOptions|jsOptions]]: [[yii\web\View::registerJsFile()]] メソッドに渡されるオプションを指定します。 * [[yii\web\AssetBundle::jsOptions|jsOptions]]: [[yii\web\View::registerJsFile()]] メソッドに渡されるオプションを指定します。
...@@ -93,7 +90,7 @@ class AppAsset extends AssetBundle ...@@ -93,7 +90,7 @@ class AppAsset extends AssetBundle
### アセットの配置場所 <a name="asset-locations"></a> ### アセットの配置場所 <a name="asset-locations"></a>
アセットは、配置場所を基準にして、次のように分類することが出来ます: アセットは、配置場所を基準にして、次のように分類することが出来ます。
* ソースアセット: アセットファイルは、ウェブ経由で直接にアクセスすることが出来ない PHP ソースコードと一緒に配置されています。 * ソースアセット: アセットファイルは、ウェブ経由で直接にアクセスすることが出来ない PHP ソースコードと一緒に配置されています。
ページの中でソースアセットを使用するためには、ウェブディレクトリにコピーして、いわゆる発行されたアセットに変換しなければなりません。 ページの中でソースアセットを使用するためには、ウェブディレクトリにコピーして、いわゆる発行されたアセットに変換しなければなりません。
...@@ -101,35 +98,30 @@ class AppAsset extends AssetBundle ...@@ -101,35 +98,30 @@ class AppAsset extends AssetBundle
* 発行されたアセット: アセットファイルはウェブディレクトリに配置されており、したがってウェブ経由で直接にアクセスすることが出来ます。 * 発行されたアセット: アセットファイルはウェブディレクトリに配置されており、したがってウェブ経由で直接にアクセスすることが出来ます。
* 外部アセット: アセットファイルは、あなたのウェブアプリケーションをホストしているのとは別のウェブサーバ上に配置されています。 * 外部アセット: アセットファイルは、あなたのウェブアプリケーションをホストしているのとは別のウェブサーバ上に配置されています。
アセットバンドルクラスを定義するときに、[[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティを指定した場合は、 アセットバンドルクラスを定義するときに、[[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティを指定した場合は、相対パスを使ってリストに挙げられたアセットは全てソースアセットであると見なされます。
相対パスを使ってリストに挙げられたアセットは全てソースアセットであると見なされます。このプロパティを指定しなかった場合は、 このプロパティを指定しなかった場合は、アセットは発行されたアセットであることになります
アセットは発行されたアセットであることになります (したがって、[[yii\web\AssetBundle::basePath|basePath]] と (したがって、[[yii\web\AssetBundle::basePath|basePath]] と [[yii\web\AssetBundle::baseUrl|baseUrl]] を指定して、アセットがどこに配置されているかを Yii に知らせなければなりません)。
[[yii\web\AssetBundle::baseUrl|baseUrl]] を指定して、アセットがどこに配置されているかを Yii に知らせなければなりません)。
アプリケーションに属するアセットは、不要なアセット発行プロセスを避けるために、ウェブディレクトリに置くことが推奨されます。 アプリケーションに属するアセットは、不要なアセット発行プロセスを避けるために、ウェブディレクトリに置くことが推奨されます。
前述の例において `AppAsset`[[yii\web\AssetBundle::sourcePath|sourcePath]] ではなく [[yii\web\AssetBundle::basePath|basePath]] 前述の例において `AppAsset`[[yii\web\AssetBundle::sourcePath|sourcePath]] ではなく [[yii\web\AssetBundle::basePath|basePath]] を指定しているのは、これが理由です。
を指定しているのは、これが理由です。
[エクステンション](structure-extensions.md) の場合は、アセットがソースコードと一緒にウェブからアクセス出来ないディレクトリに [エクステンション](structure-extensions.md) の場合は、アセットがソースコードと一緒にウェブからアクセス出来ないディレクトリに配置されているため、
配置されているため、アセットバンドルクラスを定義するときには [[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティを アセットバンドルクラスを定義するときには [[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティを指定しなければなりません。
指定しなければなりません。
> Note|注意: `@webroot/assets` を [[yii\web\AssetBundle::sourcePath|ソースパス]] として使ってはいけません。 > Note|注意: `@webroot/assets` を [[yii\web\AssetBundle::sourcePath|ソースパス]] として使ってはいけません。
このディレクトリは、既定では、[[yii\web\AssetManager|アセットマネージャ]] がソースの配置場所から発行されたアセットファイルを このディレクトリは、既定では、[[yii\web\AssetManager|アセットマネージャ]] がソースの配置場所から発行されたアセットファイルを保存する場所として使われます。
保存する場所として使われます。このディレクトリの中のファイルはすべて一時的なものと見なされており、削除されることがあります。 このディレクトリの中のファイルはすべて一時的なものと見なされており、削除されることがあります。
### アセットの依存関係 <a name="asset-dependencies"></a> ### アセットの依存関係 <a name="asset-dependencies"></a>
ウェブページに複数の CSS や JavaScript ファイルをインクルードするときは、オーバーライドの問題を避けるために、 ウェブページに複数の CSS や JavaScript ファイルをインクルードするときは、オーバーライドの問題を避けるために、一定の順序に従わなければなりません。
一定の順序に従わなければなりません。例えば、ウェブページで jQuery UI ウィジェットを使おうとするときは、jQuery JavaScript 例えば、ウェブページで jQuery UI ウィジェットを使おうとするときは、jQuery JavaScript ファイルが jQuery UI JavaScript ファイルより前にインクルードされることを保証しなければなりません。
ファイルが jQuery UI JavaScript ファイルより前にインクルードされることを保証しなければなりません。
このような順序付けをアセット間の依存関係と呼びます。 このような順序付けをアセット間の依存関係と呼びます。
アセットの依存関係は、主として、[[yii\web\AssetBundle::depends]] プロパティによって指定されます。`AppAsset` の例では、 アセットの依存関係は、主として、[[yii\web\AssetBundle::depends]] プロパティによって指定されます。
このアセットバンドルは他の二つのアセットバンドル、すなわち、[[yii\web\YiiAsset]] と [[yii\bootstrap\BootstrapAsset]] に依存しています。 `AppAsset` の例では、このアセットバンドルは他の二つのアセットバンドル、すなわち、[[yii\web\YiiAsset]] と [[yii\bootstrap\BootstrapAsset]] に依存しています。
このことは、`AppAsset` の CSS と JavaScript ファイルが、依存している二つのアセットバンドルにあるファイルの *後に* このことは、`AppAsset` の CSS と JavaScript ファイルが、依存している二つのアセットバンドルにあるファイルの *後に* インクルードされることを意味します。
インクルードされることを意味します。
アセットの依存関係は中継されます。つまり、バンドル A が B に依存し、B が C に依存していると、A は C にも依存していることになります。 アセットの依存関係は中継されます。つまり、バンドル A が B に依存し、B が C に依存していると、A は C にも依存していることになります。
...@@ -137,21 +129,20 @@ class AppAsset extends AssetBundle ...@@ -137,21 +129,20 @@ class AppAsset extends AssetBundle
### アセットのオプション <a name="asset-options"></a> ### アセットのオプション <a name="asset-options"></a>
[[yii\web\AssetBundle::cssOptions|cssOptions]] および [[yii\web\AssetBundle::jsOptions|jsOptions]] のプロパティを指定して、 [[yii\web\AssetBundle::cssOptions|cssOptions]] および [[yii\web\AssetBundle::jsOptions|jsOptions]] のプロパティを指定して、
CSS と JavaScript ファイルがページにインクルードされる方法をカスタマイズすることが出来ます。これらのプロパティの値は、 CSS と JavaScript ファイルがページにインクルードされる方法をカスタマイズすることが出来ます。
[ビュー](structure-views.md) が CSS と JavaScript ファイルをインクルードするために、[[yii\web\View::registerCssFile()]] および これらのプロパティの値は、[ビュー](structure-views.md) が CSS と JavaScript ファイルをインクルードするために、[[yii\web\View::registerCssFile()]] および
[[yii\web\View::registerJsFile()]] メソッドを呼ぶときに、それぞれ、オプションとして引き渡されます。 [[yii\web\View::registerJsFile()]] メソッドを呼ぶときに、それぞれ、オプションとして引き渡されます。
> Note|注意: バンドルクラスでセットしたオプションは、バンドルの中の *全て* の CSS/JavaScript ファイルに適用されます。 > Note|注意: バンドルクラスでセットしたオプションは、バンドルの中の *全て* の CSS/JavaScript ファイルに適用されます。
いろいろなファイルに別々のオプションを使用したい場合は、別々のアセットバンドルを作成して、個々のバンドルの中では、 いろいろなファイルに別々のオプションを使用したい場合は、別々のアセットバンドルを作成して、個々のバンドルの中では、一組のオプションを使うようにしなければなりません。
一組のオプションを使うようにしなければなりません。
例えば、IE9 以下のブラウザに対して CSS ファイルを条件的にインクルードするために、次のオプションを使うことが出来ます: 例えば、IE9 以下のブラウザに対して CSS ファイルを条件的にインクルードするために、次のオプションを使うことが出来ます。
```php ```php
public $cssOptions = ['condition' => 'lte IE9']; public $cssOptions = ['condition' => 'lte IE9'];
``` ```
こうすると、バンドルの中の CSS ファイルは下記の HTML タグを使ってインクルードされるようになります: こうすると、バンドルの中の CSS ファイルは下記の HTML タグを使ってインクルードされるようになります。
```html ```html
<!--[if lte IE9]> <!--[if lte IE9]>
...@@ -159,7 +150,7 @@ public $cssOptions = ['condition' => 'lte IE9']; ...@@ -159,7 +150,7 @@ public $cssOptions = ['condition' => 'lte IE9'];
<![endif]--> <![endif]-->
``` ```
生成された CSS のリンクタグを `<noscript>` の中に包むためには、次のように `cssOptions` を構成することが出来ます: 生成された CSS のリンクタグを `<noscript>` の中に包むためには、次のように `cssOptions` を構成することが出来ます。
```php ```php
public $cssOptions = ['noscript' => true]; public $cssOptions = ['noscript' => true];
...@@ -172,10 +163,9 @@ JavaScript 繝輔ぃ繧、繝ォ繧偵繝シ繧ク縺ョ head 繧サ繧ッ繧キ繝ァ繝ウ縺ォ繧、繝ウ繧ッ繝ォ繝シ繝 ...@@ -172,10 +163,9 @@ JavaScript 繝輔ぃ繧、繝ォ繧偵繝シ繧ク縺ョ head 繧サ繧ッ繧キ繝ァ繝ウ縺ォ繧、繝ウ繧ッ繝ォ繝シ繝
public $jsOptions = ['position' => \yii\web\View::POS_HEAD]; public $jsOptions = ['position' => \yii\web\View::POS_HEAD];
``` ```
既定では、アセットバンドルが発行されるときは、[[yii\web\AssetBundle::sourcePath]] で指定されたディレクトリの中にある 既定では、アセットバンドルが発行されるときは、[[yii\web\AssetBundle::sourcePath]] で指定されたディレクトリの中にある全てのコンテンツが発行されます。
全てのコンテンツが発行されます。[[yii\web\AssetBundle::publishOptions|publishOptions]] プロパティを構成することによって [[yii\web\AssetBundle::publishOptions|publishOptions]] プロパティを構成することによって、この振る舞いをカスタマイズすることが出来ます。
この振る舞いをカスタマイズすることが出来ます。例えば、[[yii\web\AssetBundle::sourcePath]] の一個または数個のサブディレクトリ 例えば、[[yii\web\AssetBundle::sourcePath]] の一個または数個のサブディレクトリだけを発行するために、アセットバンドルクラスの中で下記のようにすることが出来ます。
だけを発行するために、アセットバンドルクラスの中で下記のようにすることが出来ます:
```php ```php
<?php <?php
...@@ -201,32 +191,30 @@ class FontAwesomeAsset extends AssetBundle ...@@ -201,32 +191,30 @@ class FontAwesomeAsset extends AssetBundle
} }
``` ```
上記の例は、["fontawesome" パッケージ](http://fontawesome.io/) のためのアセットバンドルを定義するものです。`beforeCopy` 上記の例は、["fontawesome" パッケージ](http://fontawesome.io/) のためのアセットバンドルを定義するものです。
という発行オプションを指定して、`fonts``css` サブディレクトリだけが発行されるようにしています。 `beforeCopy` という発行オプションを指定して、`fonts``css` サブディレクトリだけが発行されるようにしています。
### Bower と NPM のアセット <a name="bower-npm-assets"></a> ### Bower と NPM のアセット <a name="bower-npm-assets"></a>
ほとんどの JavaScript/CSS パッケージは、[Bower](http://bower.io/) および/または [NPM](https://www.npmjs.org/) によって管理されています。 ほとんどの JavaScript/CSS パッケージは、[Bower](http://bower.io/) および/または [NPM](https://www.npmjs.org/) によって管理されています。
あなたのアプリケーションやエクステンションがそのようなパッケージを使っている場合は、以下のステップに従って あなたのアプリケーションやエクステンションがそのようなパッケージを使っている場合は、以下のステップに従って、ライブラリの中のアセットを管理することが推奨されます。
ライブラリの中のアセットを管理することが推奨されます。
1. アプリケーションまたはエクステンションの `composer.json` ファイルを修正して、パッケージを `require` のエントリに入れます。 1. アプリケーションまたはエクステンションの `composer.json` ファイルを修正して、パッケージを `require` のエントリに入れます。
ライブラリを参照するのに、`bower-asset/PackageName` (Bower パッケージ) または `npm-asset/PackageName` (NPM パッケージ) ライブラリを参照するのに、`bower-asset/PackageName` (Bower パッケージ) または `npm-asset/PackageName` (NPM パッケージ) を使わなければなりません。
を使わなければなりません。
2. アセットバンドルクラスを作成して、アプリケーションまたはエクステンションで使う予定の JavaScript/CSS ファイルをリストに挙げます。 2. アセットバンドルクラスを作成して、アプリケーションまたはエクステンションで使う予定の JavaScript/CSS ファイルをリストに挙げます。
[[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティは、`@bower/PackageName` または `@npm/PackageName` としなければなりません。 [[yii\web\AssetBundle::sourcePath|sourcePath]] プロパティは、`@bower/PackageName` または `@npm/PackageName` としなければなりません。
これは、Composer が Bower または NPM パッケージを、このエイリアスに対応するディレクトリにインストールするためです。 これは、Composer が Bower または NPM パッケージを、このエイリアスに対応するディレクトリにインストールするためです。
> Note|注意: パッケージの中には、全ての配布ファイルをサブディレクトリに置くものがあります。その場合には、そのサブディレクトリを > Note|注意: パッケージの中には、全ての配布ファイルをサブディレクトリに置くものがあります。
[[yii\web\AssetBundle::sourcePath|sourcePath]] の値として指定しなければなりません。例えば、[[yii\web\JqueryAsset]] は その場合には、そのサブディレクトリを [[yii\web\AssetBundle::sourcePath|sourcePath]] の値として指定しなければなりません。
`@bower/jquery` ではなく `@bower/jquery/dist` を使います。 例えば、[[yii\web\JqueryAsset]] は `@bower/jquery` ではなく `@bower/jquery/dist` を使います。
## アセットバンドルを使う <a name="using-asset-bundles"></a> ## アセットバンドルを使う <a name="using-asset-bundles"></a>
アセットバンドルを使うためには、[[yii\web\AssetBundle::register()]] メソッドを呼んでアセットバンドルを [ビュー](structure-views.md) アセットバンドルを使うためには、[[yii\web\AssetBundle::register()]] メソッドを呼んでアセットバンドルを [ビュー](structure-views.md) に登録します。
に登録します。例えば、次のようにしてビューテンプレートの中でアセットバンドルを登録することが出来ます: 例えば、次のようにしてビューテンプレートの中でアセットバンドルを登録することが出来ます。
```php ```php
use app\assets\AppAsset; use app\assets\AppAsset;
...@@ -236,25 +224,23 @@ AppAsset::register($this); // $this 縺ッ繝薙Η繝シ繧ェ繝悶ず繧ァ繧ッ繝医r陦ィ縺 ...@@ -236,25 +224,23 @@ AppAsset::register($this); // $this 縺ッ繝薙Η繝シ繧ェ繝悶ず繧ァ繧ッ繝医r陦ィ縺
> Info|情報: [[yii\web\AssetBundle::register()]] メソッドは、[[yii\web\AssetBundle::basePath|basePath]] や > Info|情報: [[yii\web\AssetBundle::register()]] メソッドは、[[yii\web\AssetBundle::basePath|basePath]] や
[[yii\web\AssetBundle::baseUrl|baseUrl]] など、発行されたアセットに関する情報を含むアセットバンドルオブジェクトを返します。 [[yii\web\AssetBundle::baseUrl|baseUrl]] など、発行されたアセットに関する情報を含むアセットバンドルオブジェクトを返します。
他の場所でアセットバンドルを登録しようとするときは、必要とされるビューオブジェクトを提供しなければなりません。例えば、 他の場所でアセットバンドルを登録しようとするときは、必要とされるビューオブジェクトを提供しなければなりません。
[ウィジェット](structure-widgets.md) クラスの中でアセットバンドルを登録するためには、`$this->view` によってビューオブジェクトを 例えば、[ウィジェット](structure-widgets.md) クラスの中でアセットバンドルを登録するためには、`$this->view` によってビューオブジェクトを取得することが出来ます。
取得することが出来ます。
アセットバンドルがビューに登録されるとき、舞台裏では、Yii が依存している全てのアセットバンドルを登録します。 アセットバンドルがビューに登録されるとき、舞台裏では、依存している全てのアセットバンドルが Yii によって登録されます。
そして、アセットバンドルがウェブからはアクセス出来ないディレクトリに配置されている場合は、アセットバンドルはウェブディレクトリに発行されます。 そして、アセットバンドルがウェブからはアクセス出来ないディレクトリに配置されている場合は、アセットバンドルがウェブディレクトリに発行されます。
その後、ビューがページをレンダリングするときに、登録されたバンドルのリストに挙げられている CSS と JavaScript ファイルのための その後、ビューがページをレンダリングするときに、登録されたバンドルのリストに挙げられている CSS と JavaScript ファイルのための `<link>` タグと `<script>` タグが生成されます。
`<link>` タグと `<script>` タグが生成されます。これらのタグの順序は、登録されたバンドル間の依存関係、および、 これらのタグの順序は、登録されたバンドル間の依存関係、および、[[yii\web\AssetBundle::css]] と [[yii\web\AssetBundle::js] のプロパティのリストに挙げられたアセットの順序によって決定されます。
[[yii\web\AssetBundle::css]] と [[yii\web\AssetBundle::js] のプロパティのリストに挙げられたアセットの順序によって決定されます。
### アセットバンドルをカスタマイズする <a name="customizing-asset-bundles"></a> ### アセットバンドルをカスタマイズする <a name="customizing-asset-bundles"></a>
Yii は、[[yii\web\AssetManager]] によって実装されている `assetManager` という名前のアプリケーションコンポーネントを通じて Yii は、[[yii\web\AssetManager]] によって実装されている `assetManager` という名前のアプリケーションコンポーネントを通じてアセットバンドルを管理します。
アセットバンドルを管理します。[[yii\web\AssetManager::bundles]] プロパティを構成することによって、アセットバンドルの振る舞いを [[yii\web\AssetManager::bundles]] プロパティを構成することによって、アセットバンドルの振る舞いを
カスタマイズすることが出来ます。例えば、デフォルト[[yii\web\JqueryAsset]] アセットバンドルはインストールされた jQuery の カスタマイズすることが出来ます。
Bower パッケージにある `jquery.js` ファイルを使用します。あなたは、可用性とパフォーマンスを向上させるために、 例えば、デフォルトの [[yii\web\JqueryAsset]] アセットバンドルはインストールされた jQuery の Bower パッケージにある `jquery.js` ファイルを使用します。
Google によってホストされたバージョンを使いたいと思うかも知れません。次のように、アプリケーションのコンフィギュレーションで あなたは、可用性とパフォーマンスを向上させるために、Google によってホストされたバージョンを使いたいと思うかも知れません。
`assetManager` を構成することによって、それが達成できます。 次のように、アプリケーションの構成情報で `assetManager` を構成することによって、それが達成できます。
```php ```php
return [ return [
...@@ -274,12 +260,11 @@ return [ ...@@ -274,12 +260,11 @@ return [
]; ];
``` ```
複数のアセットバンドルも同様に [[yii\web\AssetManager::bundles]] によって構成することが出来ます。配列のキーは、 複数のアセットバンドルも同様に [[yii\web\AssetManager::bundles]] によって構成することが出来ます。
アセットバンドルのクラス名 (最初のバックスラッシュを除く) とし、配列の値は、 配列のキーは、アセットバンドルのクラス名 (最初のバックスラッシュを除く) とし、配列の値は、対応する [構成情報配列](concept-configurations.md) とします。
対応する [コンフィギュレーション配列](concept-configurations.md) とします。
> Tip|ヒント: アセットバンドルの中で使うアセットを条件的に選択することが出来ます。次の例は、開発環境では > Tip|ヒント: アセットバンドルの中で使うアセットを条件的に選択することが出来ます。
> `jquery.js` を使い、そうでなければ `jquery.min.js` を使う方法を示すものです: > 次の例は、開発環境では `jquery.js` を使い、そうでなければ `jquery.min.js` を使う方法を示すものです。
> >
> ```php > ```php
> 'yii\web\JqueryAsset' => [ > 'yii\web\JqueryAsset' => [
...@@ -290,9 +275,9 @@ return [ ...@@ -290,9 +275,9 @@ return [
> ``` > ```
無効にしたいアセットバンドルの名前に `false` を結びつけることによって、一つまたは複数のアセットバンドルを無効にすることが出来ます。 無効にしたいアセットバンドルの名前に `false` を結びつけることによって、一つまたは複数のアセットバンドルを無効にすることが出来ます。
無効にされたアセットバンドルをビューに登録した場合は、依存するバンドルは一つも登録されません。また、ビューがページを 無効にされたアセットバンドルをビューに登録した場合は、依存するバンドルは一つも登録されません。
レンダリングするときも、バンドルの中のアセットは一つもインクルードされません。例えば、[[yii\web\JqueryAsset]] を無効化するためには、 また、ビューがページをレンダリングするときも、バンドルの中のアセットは一つもインクルードされません。
次のコンフィギュレーションを使用することが出来ます: 例えば、[[yii\web\JqueryAsset]] を無効化するために、次の構成情報を使用することが出来ます。
```php ```php
return [ return [
...@@ -312,10 +297,9 @@ return [ ...@@ -312,10 +297,9 @@ return [
### アセットマッピング <a name="asset-mapping"></a> ### アセットマッピング <a name="asset-mapping"></a>
時として、複数のアセットバンドルで使われている 正しくない/互換でない アセットファイルパスを「修正」したい場合があります。 時として、複数のアセットバンドルで使われている 正しくない/互換でない アセットファイルパスを「修正」したい場合があります。
例えば、バンドル A がバージョン 1.11.1 の `jquery.min.js` を使い、バンドル B がバージョン 2.1.1 の `jquery.js` を使っている 例えば、バンドル A がバージョン 1.11.1 の `jquery.min.js` を使い、バンドル B がバージョン 2.1.1 の `jquery.js` を使っているような場合です。
ような場合です。それぞれのバンドルをカスタマイズすることで問題を修正することも出来ますが、それよりも簡単な方法は、 それぞれのバンドルをカスタマイズすることで問題を修正することも出来ますが、それよりも簡単な方法は、*アセットマップ* 機能を使って、正しくないアセットを望ましいアセットに割り付けることです。
*アセットマップ* 機能を使って、正しくないアセットを望ましいアセットに割り付けることです。そうするためには、以下のように そうするためには、以下のように [[yii\web\AssetManager::assetMap]] プロパティを構成します。
[[yii\web\AssetManager::assetMap]] プロパティを構成します:
```php ```php
return [ return [
...@@ -331,27 +315,24 @@ return [ ...@@ -331,27 +315,24 @@ return [
``` ```
[[yii\web\AssetManager::assetMap|assetMap]] のキーは修正したいアセットの名前であり、値は望ましいアセットのパスです。 [[yii\web\AssetManager::assetMap|assetMap]] のキーは修正したいアセットの名前であり、値は望ましいアセットのパスです。
アセットバンドルをビューに登録するとき、[[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]] の配列に含まれる アセットバンドルをビューに登録するとき、[[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]] の配列に含まれるすべてのアセットファイルの相対パスがこのマップと突き合わせて調べられます。
すべてのアセットファイルの相対パスがこのマップと突き合わせて調べられます。キーのどれかがアセットファイルのパス (利用できる場合は、 キーのどれかがアセットファイルのパス (利用できる場合は、[[yii\web\AssetBundle::sourcePath]] が前置されます) の最後の部分と一致した場合は、対応する値によってアセットが置き換えられ、ビューに登録されます。
[[yii\web\AssetBundle::sourcePath]] が前置されます) の最後の部分と一致した場合は、対応する値によってアセットが置き換えられ、 例えば、`my/path/to/jquery.js` というアセットファイルは `jquery.js` というキーにマッチします。
ビューに登録されます。例えば、`my/path/to/jquery.js` というアセットファイルは `jquery.js` というキーにマッチします。
> Note|注意: 相対パスを使って指定されたアセットだけがアセットマッピングの対象になります。そして、置き換える側のアセットのパスは > Note|注意: 相対パスを使って指定されたアセットだけがアセットマッピングの対象になります。
対 URL であるか、[[yii\web\AssetManager::basePath]] からの相対パスであるかの、どちらかでなければなりません。 そして、置き換える側のアセットのパスは、絶対 URL であるか、[[yii\web\AssetManager::basePath]] からの相対パスであるかの、どちらかでなければなりません。
### アセット発行 <a name="asset-publishing"></a> ### アセット発行 <a name="asset-publishing"></a>
既に述べたように、アセットバンドルがウェブからアクセス出来ないディレクトリに配置されている場合は、バンドルがビューに登録されるときに、 既に述べたように、アセットバンドルがウェブからアクセス出来ないディレクトリに配置されている場合は、バンドルがビューに登録されるときに、アセットがウェブディレクトリにコピーされます。
アセットがウェブディレクトリにコピーされます。このプロセスは *アセット発行* と呼ばれ、[[yii\web\AssetManager|アセットマネージャ]] このプロセスは *アセット発行* と呼ばれ、[[yii\web\AssetManager|アセットマネージャ]] によって自動的に実行されます。
によって自動的に実行されます。
既定では、アセットが発行されるディレクトリは `@webroot/assets` であり、`@web/assets` という URL に対応するものです。 既定では、アセットが発行されるディレクトリは `@webroot/assets` であり、`@web/assets` という URL に対応するものです。
この場所は、[[yii\web\AssetManager::basePath|basePath]] と [[yii\web\AssetManager::baseUrl|baseUrl]] のプロパティを構成して この場所は、[[yii\web\AssetManager::basePath|basePath]] と [[yii\web\AssetManager::baseUrl|baseUrl]] のプロパティを構成してカスタマイズすることが出来ます。
カスタマイズすることが出来ます。
ファイルをコピーすることでアセットを発行する代りに、OS とウェブサーバが許容するなら、シンボリックリンクを使うことを考慮しても良いでしょう。 ファイルをコピーすることでアセットを発行する代りに、OS とウェブサーバが許容するなら、シンボリックリンクを使うことを考慮しても良いでしょう。
この機能は [[yii\web\AssetManager::linkAssets|linkAssets]] を true にセットすることで有効にすることが出来ます: この機能は [[yii\web\AssetManager::linkAssets|linkAssets]] を true にセットすることで有効にすることが出来ます。
```php ```php
return [ return [
...@@ -364,38 +345,35 @@ return [ ...@@ -364,38 +345,35 @@ return [
]; ];
``` ```
上記のコンフィギュレーションによって、アセットマネージャはアセットバンドルを発行するときにソースパスへのシンボリックリンクを 上記の構成によって、アセットマネージャはアセットバンドルを発行するときにソースパスへのシンボリックリンクを作成するようになります。
作成するようになります。この方がファイルのコピーより速く、また、発行されたアセットが常に最新であることを保証することも出来ます。 この方がファイルのコピーより速く、また、発行されたアセットが常に最新であることを保証することも出来ます。
## よく使われるアセットバンドル <a name="common-asset-bundles"></a> ## よく使われるアセットバンドル <a name="common-asset-bundles"></a>
コアの Yii コードは多くのアセットバンドルを定義しています。その中で、下記のバンドルはよく使われるものであり、あなたの コアの Yii コードは多くのアセットバンドルを定義しています。
アプリケーションやエクステンションのコードでも参照することが出来るものです。 その中で、下記のバンドルはよく使われるものであり、あなたのアプリケーションやエクステンションのコードでも参照することが出来るものです。
- [[yii\web\YiiAsset]]: 主として `yii.js` ファイルをインクルードするためのバンドルです。このファイルはモジュール化された - [[yii\web\YiiAsset]]: 主として `yii.js` ファイルをインクルードするためのバンドルです。
JavaScript のコードを組織化するメカニズムを実装しています。また、`data-method``data-confirm` の属性に対する特別な このファイルはモジュール化された JavaScript のコードを組織化するメカニズムを実装しています。
サポートや、その他の有用な機能を提供します。 また、`data-method``data-confirm` の属性に対する特別なサポートや、その他の有用な機能を提供します。
- [[yii\web\JqueryAsset]]: jQuery の bower パッケージから `jquery.js` ファイルをインクルードします。 - [[yii\web\JqueryAsset]]: jQuery の bower パッケージから `jquery.js` ファイルをインクルードします。
- [[yii\bootstrap\BootstrapAsset]]: Twitter Bootstrap フレームワークから CSS ファイルをインクルードします。 - [[yii\bootstrap\BootstrapAsset]]: Twitter Bootstrap フレームワークから CSS ファイルをインクルードします。
- [[yii\bootstrap\BootstrapPluginAsset]]: Bootstrap JavaScript プラグインをサポートするために、Twitter Bootstrap - [[yii\bootstrap\BootstrapPluginAsset]]: Bootstrap JavaScript プラグインをサポートするために、Twitter Bootstrap フレームワークから JavaScript ファイルをインクルードします。
フレームワークから JavaScript ファイルをインクルードします。
- [[yii\jui\JuiAsset]]: jQuery UI ライブラリから CSS と JavaScript のファイルをインクルードします。 - [[yii\jui\JuiAsset]]: jQuery UI ライブラリから CSS と JavaScript のファイルをインクルードします。
あなたのコードが、jQuery や jQuery UI または Bootstrap に依存する場合は、自分自身のバージョンを作るのではなく、これらの あなたのコードが、jQuery や jQuery UI または Bootstrap に依存する場合は、自分自身のバージョンを作るのではなく、これらの定義済みのアセットバンドルを使用すべきです。
定義済みのアセットバンドルを使用すべきです。これらのバンドルのデフォルトの設定があなたの必要を満たさない時は、 これらのバンドルのデフォルトの設定があなたの必要を満たさない時は、[アセットバンドルをカスタマイズする](#customizing-asset-bundles) の項で説明したように、それをカスタマイズすることが出来ます。
[アセットバンドルをカスタマイズする](#customizing-asset-bundles) の項で説明したように、それをカスタマイズすることが出来ます。
## アセット変換 <a name="asset-conversion"></a> ## アセット変換 <a name="asset-conversion"></a>
直接に CSS および/または JavaScript のコードを書く代りに、何らかの拡張構文を使って書いたものを特別なツールを使って 直接に CSS および/または JavaScript のコードを書く代りに、何らかの拡張構文を使って書いたものを特別なツールを使って CSS/JavaScript に変換する、ということを開発者はしばしば行います。
CSS/JavaScript に変換する、ということを開発者はしばしば行います。例えば、CSS コードのためには、[LESS](http://lesscss.org/) 例えば、CSS コードのためには、[LESS](http://lesscss.org/)[SCSS](http://sass-lang.com/) を使うことが出来ます。
[SCSS](http://sass-lang.com/) を使うことが出来ます。また、JavaScript のためには、[TypeScript](http://www.typescriptlang.org/) また、JavaScript のためには、[TypeScript](http://www.typescriptlang.org/) を使うことが出来ます。
を使うことが出来ます。
拡張構文を使ったアセットファイルをアセットバンドルの中の [[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]] 拡張構文を使ったアセットファイルをアセットバンドルの中の [[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]] のリストに挙げることが出来ます。
のリストに挙げることが出来ます。例えば、 えば、
```php ```php
class AppAsset extends AssetBundle class AppAsset extends AssetBundle
...@@ -415,9 +393,8 @@ class AppAsset extends AssetBundle ...@@ -415,9 +393,8 @@ class AppAsset extends AssetBundle
} }
``` ```
このようなアセットバンドルをビューに登録すると、[[yii\web\AssetManager|アセットマネージャ]] が自動的にプリプロセッサツールを このようなアセットバンドルをビューに登録すると、[[yii\web\AssetManager|アセットマネージャ]] が自動的にプリプロセッサツールを走らせて、認識できた拡張構文のアセットを CSS/JavaScript に変換します。
走らせて、認識できた拡張構文のアセットを CSS/JavaScript に変換します。最終的にビューがページをレンダリングするときには、 最終的にビューがページをレンダリングするときには、ビューは元の拡張構文のアセットではなく、変換後の CSS/JavaScript ファイルをページにインクルードします。
ビューは元の拡張構文のアセットではなく、変換後の CSS/JavaScript ファイルをページにインクルードします。
Yii はファイル名の拡張子を使って、アセットが使っている拡張構文を識別します。デフォルトでは、下記の構文とファイル名拡張子を認識します。 Yii はファイル名の拡張子を使って、アセットが使っている拡張構文を識別します。デフォルトでは、下記の構文とファイル名拡張子を認識します。
...@@ -427,11 +404,10 @@ Yii 縺ッ繝輔ぃ繧、繝ォ蜷阪諡。蠑オ蟄舌r菴ソ縺」縺ヲ縲√い繧サ繝ヨ縺御スソ縺」縺ヲ縺k ...@@ -427,11 +404,10 @@ Yii 縺ッ繝輔ぃ繧、繝ォ蜷阪諡。蠑オ蟄舌r菴ソ縺」縺ヲ縲√い繧サ繝ヨ縺御スソ縺」縺ヲ縺k
- [CoffeeScript](http://coffeescript.org/): `.coffee` - [CoffeeScript](http://coffeescript.org/): `.coffee`
- [TypeScript](http://www.typescriptlang.org/): `.ts` - [TypeScript](http://www.typescriptlang.org/): `.ts`
Yii はインストールされたプリプロセッサツールに頼ってアセットを変換します。例えば、[LESS](http://lesscss.org/) を使うためには、 Yii はインストールされたプリプロセッサツールに頼ってアセットを変換します。
`lessc` プリプロセッサコマンドをインストールしなければなりません。 例えば、[LESS](http://lesscss.org/) を使うためには、`lessc` プリプロセッサコマンドをインストールしなければなりません。
下記のように [[yii\web\AssetManager::converter]] を構成することで、プリプロセッサコマンドとサポートされる拡張構文を 下記のように [[yii\web\AssetManager::converter]] を構成することで、プリプロセッサコマンドとサポートされる拡張構文をカスタマイズすることが出来ます。
カスタマイズすることが出来ます:
```php ```php
return [ return [
...@@ -450,38 +426,34 @@ return [ ...@@ -450,38 +426,34 @@ return [
``` ```
上記においては、サポートされる拡張構文が [[yii\web\AssetConverter::commands]] プロパティによって定義されています。 上記においては、サポートされる拡張構文が [[yii\web\AssetConverter::commands]] プロパティによって定義されています。
配列のキーはファイルの拡張子 (先頭のドットは省く) であり、配列の値は結果として作られるアセットファイルの拡張子と 配列のキーはファイルの拡張子 (先頭のドットは省く) であり、配列の値は結果として作られるアセットファイルの拡張子とアセット変換を実行するためのコマンドです。
アセット変換を実行するためのコマンドです。コマンドの中の `{from}``{to}` のトークンは、ソースのアセットファイルのパスと コマンドの中の `{from}``{to}` のトークンは、ソースのアセットファイルのパスとターゲットのアセットファイルのパスに置き換えられます。
ターゲットのアセットファイルのパスに置き換えられます。
> Info|情報: 上記で説明した方法の他にも、拡張構文のアセットを扱う方法はあります。例えば、[grunt](http://gruntjs.com/) > Info|情報: 上記で説明した方法の他にも、拡張構文のアセットを扱う方法はあります。
のようなビルドツールを使って、拡張構文のアセットをモニターし、自動的に変換することが出来ます。この場合は、元のファイルではなく、 例えば、[grunt](http://gruntjs.com/) のようなビルドツールを使って、拡張構文のアセットをモニターし、自動的に変換することが出来ます。
果として作られる CSS/JavaScript ファイルをアセットバンドルのリストに挙げなければなりません。 この場合は、元のファイルではなく、結果として作られる CSS/JavaScript ファイルをアセットバンドルのリストに挙げなければなりません。
## アセットを結合して圧縮する <a name="combining-compressing-assets"></a> ## アセットを結合して圧縮する <a name="combining-compressing-assets"></a>
ウェブページは数多くの CSS および/または JavaScript ファイルをインクルードすることがあり得ます。HTTP リクエストの数と ウェブページは数多くの CSS および/または JavaScript ファイルをインクルードすることがあり得ます。
これらのファイルの全体としてのダウンロードサイズを削減するためによく用いられる方法は、複数の CSS/JavaScript ファイルを HTTP リクエストの数とこれらのファイルの全体としてのダウンロードサイズを削減するためによく用いられる方法は、複数の CSS/JavaScript ファイルを結合して圧縮し、一つまたはごく少数のファイルにまとめることです。
結合して圧縮し、一つまたはごく少数のファイルにまとめることです。そして、ウェブページでは元のファイルをインクルードする そして、ウェブページでは元のファイルをインクルードする代りに、圧縮されたファイルをインクルードする訳です。
代りに、圧縮されたファイルをインクルードする訳です。
> Info|情報: アセットの結合と圧縮は、通常はアプリケーションが実運用モードにある場合に必要になります。開発モードにおいては、 > Info|情報: アセットの結合と圧縮は、通常はアプリケーションが実運用モードにある場合に必要になります。
たいていは元の CSS/JavaScript ファイルを使う方がデバッグのために好都合です。 開発モードにおいては、たいていは元の CSS/JavaScript ファイルを使う方がデバッグのために好都合です。
次に、既存のアプリケーションコードを修正する必要なしに、アセットファイルを結合して圧縮する方法を紹介します。 次に、既存のアプリケーションコードを修正する必要なしに、アセットファイルを結合して圧縮する方法を紹介します。
1. アプリケーションの中で、結合して圧縮する予定のアセットバンドルを全て探し出す。 1. アプリケーションの中で、結合して圧縮する予定のアセットバンドルを全て探し出す。
2. これらのバンドルを一個か数個のグループにまとめる。どのバンドルも一つのグループにしか属することが出来ないことに注意。 2. これらのバンドルを一個か数個のグループにまとめる。どのバンドルも一つのグループにしか属することが出来ないことに注意。
3. 各グループの CSS ファイルを一つのファイルに結合/圧縮する。JavaScript ファイルに対しても同様にこれを行う。 3. 各グループの CSS ファイルを一つのファイルに結合/圧縮する。JavaScript ファイルに対しても同様にこれを行う。
4. 各グループに対して新しいアセットバンドルを定義する: 4. 各グループに対して新しいアセットバンドルを定義する。
* [[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]] のプロパティを、それぞれ、結合された CSS ファイルと * [[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]] のプロパティに、それぞれ、結合された CSS ファイルと JavaScript ファイルをセットする。
JavaScript ファイルにセットする。 * 各グループに属する元のアセットバンドルをカスタマイズして、[[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]] のプロパティを空っぽにし、[[yii\web\AssetBundle::depends|depends]] プロパティにグループのために作られた新しいバンドルを指定する。
* 各グループに属する元のアセットバンドルをカスタマイズして、[[yii\web\AssetBundle::css|css]] と [[yii\web\AssetBundle::js|js]]
のプロパティを空っぽにし、[[yii\web\AssetBundle::depends|depends]] プロパティにグループのために作られた新しいバンドルを指定する。
この方法を使うと、ビューでアセットバンドルを登録したときに、元のバンドルが属するグループのための新しいアセットバンドルが自動的に この方法を使うと、ビューでアセットバンドルを登録したときに、元のバンドルが属するグループのための新しいアセットバンドルが自動的に登録されるようになります。
登録されるようになります。そして、結果として、結合/圧縮されたアセットファイルが、元のファイルの代りに、ページにインクルードされます。 そして、結果として、結合/圧縮されたアセットファイルが、元のファイルの代りに、ページにインクルードされます。
### 一例 <a name="example"></a> ### 一例 <a name="example"></a>
...@@ -492,28 +464,25 @@ return [ ...@@ -492,28 +464,25 @@ return [
ページ Y はアセットバンドル B、C、D を使用します。 ページ Y はアセットバンドル B、C、D を使用します。
これらのアセットバンドルを分割する方法は二つあります。一つは単一のグループを使用して全てのアセットバンドルを含める方法です。 これらのアセットバンドルを分割する方法は二つあります。一つは単一のグループを使用して全てのアセットバンドルを含める方法です。
もう一つは、A をグループ X に入れ、D をグループ Y に入れ、そして、B と C をグループ S に入れる方法です。どちらが良いでしょう? もう一つは、A をグループ X に入れ、D をグループ Y に入れ、そして、B と C をグループ S に入れる方法です。どちらが良いでしょう? 場合によります。
場合によります。最初の方法の利点は、二つのページが同一の結合された CSS と JavaScript のファイルを共有するため、HTTP キャッシュの 最初の方法の利点は、二つのページが同一の結合された CSS と JavaScript のファイルを共有するため、HTTP キャッシュの効果が高くなることです。
効果が高くなることです。その一方で、単一のグループが全てのバンドルを含むために、結合された CSS と JavaScript のファイルは その一方で、単一のグループが全てのバンドルを含むために、結合された CSS と JavaScript のファイルはより大きくなり、従って最初のファイル転送時間はより長くなります。
より大きくなり、従って最初のファイル転送時間はより長くなります。この例では話を簡単にするために、最初の方法、すなわち、 この例では話を簡単にするために、最初の方法、すなわち、全てのバンドルを含む単一のグループを使用することにします。
全てのバンドルを含む単一のグループを使用することにします。
> Info|情報: アセットバンドルをグループに分けることは些細な仕事ではありません。通常、そのためには、いろいろなページの > Info|情報: アセットバンドルをグループに分けることは些細な仕事ではありません。
さまざまなアセットの現実世界での転送量を分析することが必要になります。とりあえず、最初は、簡単にするために、 通常、そのためには、いろいろなページのさまざまなアセットの現実世界での転送量を分析することが必要になります。
単一のグループから始めて良いでしょう。 とりあえず、最初は、簡単にするために、単一のグループから始めて良いでしょう。
既存のツール (例えば [Closure Compiler](https://developers.google.com/closure/compiler/) 既存のツール (例えば [Closure Compiler](https://developers.google.com/closure/compiler/)[YUI Compressor](https://github.com/yui/yuicompressor/)) を使って、全てのバンドルにある CSS と JavaScript のファイルを結合して圧縮します。
[YUI Compressor](https://github.com/yui/yuicompressor/)) を使って、全てのバンドルにある CSS と JavaScript のファイルを ファイルは、バンドル間の依存関係を満たす順序に従って結合しなければならないことに注意してください。
結合して圧縮します。ファイルは、バンドル間の依存関係を満たす順序に従って結合しなければならないことに注意してください。 例えば、バンドル A が B に依存し、B が C と D の両方に依存している場合は、アセットファイルの結合順は、最初に C と D、次に B、そして最後に A としなければなりません。
例えば、バンドル A が B に依存し、B が C と D の両方に依存している場合は、アセットファイルの結合順は、最初に C と D、
次に B、そして最後に A としなければなりません。
結合と圧縮が完了すると、一つの CSS ファイルと一つの JavaScript ファイルが得られます。それらは、`all-xyz.css` および 結合と圧縮が完了すると、一つの CSS ファイルと一つの JavaScript ファイルが得られます。
`all-xyz.js` と命名されたとしましょう。ここで `xyz` は、ファイル名をユニークにして HTTP キャッシュの問題を避ける それらは、`all-xyz.css` および `all-xyz.js` と命名されたとしましょう。
ために使用されるタイムスタンプまたはハッシュを表します。 こで `xyz` は、ファイル名をユニークにして HTTP キャッシュの問題を避けるために使用されるタイムスタンプまたはハッシュを表します。
いよいよ最終ステップです。アプリケーションのコンフィギュレーションの中で、[[yii\web\AssetManager|アセットマネージャ]] いよいよ最終ステップです。
次のように構成します: プリケーションの構成情報の中で、[[yii\web\AssetManager|アセットマネージャ]] を次のように構成します。
```php ```php
return [ return [
...@@ -537,15 +506,15 @@ return [ ...@@ -537,15 +506,15 @@ return [
]; ];
``` ```
[アセットバンドルをカスタマイズする](#customizing-asset-bundles) の項で説明したように、上記のコンフィギュレーションによって [アセットバンドルをカスタマイズする](#customizing-asset-bundles) の項で説明したように、上記の構成によって元のバンドルは全てデフォルトの振る舞いを変更されます。
のバンドルは全てデフォルトの振る舞いを変更されます。具体的にいえば、バンドル A、B、C、D は、もはやアセットファイルを 体的にいえば、バンドル A、B、C、D は、もはやアセットファイルを一つも持っていません。
一つも持っていません。この4つは、それぞれ、結合された `all-xyz.css``all-xyz.js` ファイルを持つ `all` バンドルに依存するように この4つは、それぞれ、結合された `all-xyz.css``all-xyz.js` ファイルを持つ `all` バンドルに依存するようになりました。
なりました。結果として、ページ X では、バンドル A、B、C から元のソースファイルをインクルードする代りに、これら二つの結合された 結果として、ページ X では、バンドル A、B、C から元のソースファイルをインクルードする代りに、これら二つの結合されたファイルだけがインクルードされます。
ファイルがインクルードされます。同じことはページ Y でも起ります 同じことはページ Y でも起ります。
最後にもう一つ、上記の方法をさらにスムーズに運用するためのトリックがあります。アプリケーションのコンフィギュレーションファイルを 最後にもう一つ、上記の方法をさらにスムーズに運用するためのトリックがあります。
直接修正する代りに、バンドルのカスタマイズ用の配列を独立したファイルに置いて、条件によってそのファイルをアプリケーションの アプリケーションの構成情報ファイルを直接修正する代りに、バンドルのカスタマイズ用の配列を独立したファイルに置いて、条件によってそのファイルをアプリケーションの構成情報にインクルードすることが出来ます。
コンフィギュレーションにインクルードすることが出来ます。例えば、 えば、
```php ```php
return [ return [
...@@ -557,42 +526,40 @@ return [ ...@@ -557,42 +526,40 @@ return [
]; ];
``` ```
つまり、アセットバンドルのコンフィギュレーション配列は、実運用モードのためのものは `assets-prod.php` に保存し、 つまり、アセットバンドルの構成情報配列は、実運用モードのためのものは `assets-prod.php` に保存し、開発モードのためのものは `assets-dev.php` に保存するという訳です。
開発モードのためのものは `assets-dev.php` に保存するという訳です。
### `asset` コマンドを使う <a name="using-asset-command"></a> ### `asset` コマンドを使う <a name="using-asset-command"></a>
Yii は、たった今説明した方法を自動化するための `asset` という名前のコンソールコマンドを提供しています。 Yii は、たった今説明した方法を自動化するための `asset` という名前のコンソールコマンドを提供しています。
このコマンドを使うためには、最初にコンフィギュレーションファイルを作成して、どのアセットバンドルが結合されるか、そして、 このコマンドを使うためには、最初に構成情報ファイルを作成して、どのアセットバンドルが結合されるか、そして、それらがどのようにグループ化されるかを記述しなければなりません。
それらがどのようにグループ化されるかを記述しなければなりません。`asset/template` サブコマンドを使って最初にテンプレートを生成し、 `asset/template` サブコマンドを使って最初にテンプレートを生成し、それをあなたの要求に合うように修正することが出来ます。
それをあなたの要求に合うように修正することが出来ます。
``` ```
yii asset/template assets.php yii asset/template assets.php
``` ```
上記のコマンドは、カレントディレクトリに `assets.php` というファイルを生成します。このファイルの内容は以下のようなものです: 上記のコマンドは、カレントディレクトリに `assets.php` というファイルを生成します。このファイルの内容は以下のようなものです。
```php ```php
<?php <?php
/** /**
* "yii asset" コンソールコマンドのためのコンフィギュレーションファイル * "yii asset" コンソールコマンドのための構成情報ファイル
* コンソール環境では、'@webroot' や '@web' のように、パスエイリアスが存在しない場合があることに注意してください。 * コンソール環境では、'@webroot' や '@web' のように、パスエイリアスが存在しない場合があることに注意してください。
* これらの欠落したパスエイリアスは手作業で定義してください。 * これらの欠落したパスエイリアスは手作業で定義してください。
*/ */
return [ return [
// JavaScript ファイルの圧縮のためのコマンド/コールバックを調整: // JavaScript ファイルの圧縮のためのコマンド/コールバックを調整。
'jsCompressor' => 'java -jar compiler.jar --js {from} --js_output_file {to}', 'jsCompressor' => 'java -jar compiler.jar --js {from} --js_output_file {to}',
// CSS ファイルの圧縮のためのコマンド/コールバックを調整: // CSS ファイルの圧縮のためのコマンド/コールバックを調整。
'cssCompressor' => 'java -jar yuicompressor.jar --type css {from} -o {to}', 'cssCompressor' => 'java -jar yuicompressor.jar --type css {from} -o {to}',
// 圧縮するアセットバンドルのリスト: // 圧縮するアセットバンドルのリスト。
'bundles' => [ 'bundles' => [
// 'yii\web\YiiAsset', // 'yii\web\YiiAsset',
// 'yii\web\JqueryAsset', // 'yii\web\JqueryAsset',
], ],
// 圧縮出力用のアセットバンドル: // 圧縮出力用のアセットバンドル。
'targets' => [ 'targets' => [
'all' => [ 'all' => [
'class' => 'yii\web\AssetBundle', 'class' => 'yii\web\AssetBundle',
...@@ -602,36 +569,31 @@ return [ ...@@ -602,36 +569,31 @@ return [
'css' => 'css/all-{hash}.css', 'css' => 'css/all-{hash}.css',
], ],
], ],
// アセットマネージャのコンフィギュレーション: // アセットマネージャの構成情報
'assetManager' => [ 'assetManager' => [
], ],
]; ];
``` ```
このファイルを修正して、どのバンドルを結合するつもりであるかを `bundles` オプションで指定しなければなりません。 このファイルを修正して、どのバンドルを結合するつもりであるかを `bundles` オプションで指定しなければなりません。
`targets` オプションでは、バンドルがどのようにグループに分割されるかを指定しなければなりません。既に述べたように、 `targets` オプションでは、バンドルがどのようにグループに分割されるかを指定しなければなりません。
つまたは複数のグループを定義することが出来ます。 既に述べたように、一つまたは複数のグループを定義することが出来ます。
> Note|注意: パスエイリアス `@webroot` および `@web` はコンソールアプリケーションでは利用できませんので、これらは > Note|注意: パスエイリアス `@webroot` および `@web` はコンソールアプリケーションでは利用できませんので、これらは構成情報の中で明示的に定義しなければなりません。
コンフィギュレーションの中で明示的に定義しなければなりません。
JavaScript ファイルは結合され、圧縮されて `js/all-{hash}.js` に保存されます。ここで {hash} は、結果として作られたファイルの JavaScript ファイルは結合され、圧縮されて `js/all-{hash}.js` に保存されます。ここで {hash} は、結果として作られたファイルのハッシュで置き換えられるものです。
ハッシュで置き換えられるものです。
`jsCompressor``cssCompressor` のオプションは、JavaScript と CSS の結合/圧縮を実行するコンソールコマンドまたは PHP `jsCompressor``cssCompressor` のオプションは、JavaScript と CSS の結合/圧縮を実行するコンソールコマンドまたは PHP コールバックを指定するものです。
コールバックを指定するものです。既定では、Yii は JavaScript ファイルの結合に [Closure Compiler](https://developers.google.com/closure/compiler/) 既定では、Yii は JavaScript ファイルの結合に [Closure Compiler](https://developers.google.com/closure/compiler/) を使い、CSS ファイルの結合に [YUI Compressor](https://github.com/yui/yuicompressor/) を使用します。
を使い、CSS ファイルの結合に [YUI Compressor](https://github.com/yui/yuicompressor/) を使用します。
あなたの好みのツールを使うためには、手作業でツールをインストールしたり、オプションを調整したりしなければなりません。 あなたの好みのツールを使うためには、手作業でツールをインストールしたり、オプションを調整したりしなければなりません。
このコンフィギュレーションファイルを使い、`asset` コマンドを走らせて、アセットファイルを結合して圧縮し、同時に この構成情報ファイルを使い、`asset` コマンドを走らせて、アセットファイルを結合して圧縮し、同時に、新しいアセットバンドルの構成情報ファイル `assets-prod.php` を生成することが出来ます。
新しいアセットバンドルのコンフィギュレーションファイル `assets-prod.php` を生成することが出来ます:
``` ```
yii asset assets.php config/assets-prod.php yii asset assets.php config/assets-prod.php
``` ```
直前の項で説明したように、この生成されたコンフィギュレーションファイルをアプリケーションのコンフィギュレーションに 直前の項で説明したように、この生成された構成情報ファイルをアプリケーションの構成情報にインクルードすることが出来ます。
インクルードすることが出来ます。
> Info|情報: `asset` コマンドを使うことは、アセットの結合・圧縮のプロセスを自動化する唯一の選択肢ではありません。 > Info|情報: `asset` コマンドを使うことは、アセットの結合・圧縮のプロセスを自動化する唯一の選択肢ではありません。
......
...@@ -3,9 +3,8 @@ ...@@ -3,9 +3,8 @@
コントローラは [MVC](http://ja.wikipedia.org/wiki/Model_View_Controller) アーキテクチャの一部を成すものです。 コントローラは [MVC](http://ja.wikipedia.org/wiki/Model_View_Controller) アーキテクチャの一部を成すものです。
これは [[yii\base\Controller]] を拡張したクラスのオブジェクトであり、リクエストの処理とレスポンスの生成について責任を負うものです。 これは [[yii\base\Controller]] を拡張したクラスのオブジェクトであり、リクエストの処理とレスポンスの生成について責任を負うものです。
具体的には、[アプリケーション](structure-applications.md) から制御を引き継いだ後、コントローラは入ってきたリクエストのデータを分析し、 具体的には、[アプリケーション](structure-applications.md) から制御を引き継いだ後、コントローラは入ってきたリクエストのデータを分析し、それを [モデル](structure-models.md)
それを [モデル](structure-models.md) に引き渡して、モデルが生成した結果を [ビュー](structure-views.md) に投入し、 に引き渡して、モデルが生成した結果を [ビュー](structure-views.md) に投入し、最終的に外に出て行くレスポンスを生成します。
最終的に外に出て行くレスポンスを生成します。
## アクション<a name="actions"></a> ## アクション<a name="actions"></a>
...@@ -14,7 +13,7 @@ ...@@ -14,7 +13,7 @@
アクションは、エンドユーザがアドレスを指定して実行をリクエストできる最も基本的な構成単位です。 アクションは、エンドユーザがアドレスを指定して実行をリクエストできる最も基本的な構成単位です。
コントローラは一つまたは複数のアクションを持ち得ます。 コントローラは一つまたは複数のアクションを持ち得ます。
次の例は、`view``create` という二つのアクションを持つ `post` コントローラを示すものです: 次の例は、`view``create` という二つのアクションを持つ `post` コントローラを示すものです
```php ```php
namespace app\controllers; namespace app\controllers;
...@@ -53,8 +52,7 @@ class PostController extends Controller ...@@ -53,8 +52,7 @@ class PostController extends Controller
} }
``` ```
`view` アクション (`actionView()` メソッドで定義されます) において、 `view` アクション (`actionView()` メソッドで定義されます) において、コードは最初に、リクエストされたモデルの ID に従って [モデル](structure-models.md) を読み出します。
コードは最初に、リクエストされたモデルの ID に従って [モデル](structure-models.md) を読み出します。
モデルの読み出しが成功したときは、`view` という名前の [ビュー](structure-views.md) を使ってモデルを表示します。 モデルの読み出しが成功したときは、`view` という名前の [ビュー](structure-views.md) を使ってモデルを表示します。
失敗したときは例外を投げます。 失敗したときは例外を投げます。
...@@ -69,32 +67,32 @@ class PostController extends Controller ...@@ -69,32 +67,32 @@ class PostController extends Controller
エンドユーザは、いわゆる *ルート* によって、アクションのアドレスを指定します。 エンドユーザは、いわゆる *ルート* によって、アクションのアドレスを指定します。
ルートは、次の部分からなる文字列です。 ルートは、次の部分からなる文字列です。
* モジュール ID: この部分は、コントローラがアプリケーションではなく [モジュール](structure-modules.md) に属する場合にのみ存在します; * モジュール ID: この部分は、コントローラがアプリケーションではなく [モジュール](structure-modules.md) に属する場合にのみ存在します
* コントローラ ID: 同じアプリケーション (または、コントローラがモジュールに属する場合は、同じモジュール) * コントローラ ID: 同じアプリケーション (または、コントローラがモジュールに属する場合は、同じモジュール)
に属する全てのコントローラの中から、特定のコントローラを指定するユニークな文字列; に属する全てのコントローラの中から、特定のコントローラを指定するユニークな文字列
* アクション ID: 同じコントローラに属する全てのアクションの中から、特定のアクションを指定するユニークな文字列。 * アクション ID: 同じコントローラに属する全てのアクションの中から、特定のアクションを指定するユニークな文字列。
ルートは次の形式を取ります: ルートは次の形式を取ります
``` ```
ControllerID/ActionID ControllerID/ActionID
``` ```
または、コントローラがモジュールに属する場合は、次の形式を取ります: または、コントローラがモジュールに属する場合は、次の形式を取ります
```php ```php
ModuleID/ControllerID/ActionID ModuleID/ControllerID/ActionID
``` ```
ですから、ユーザが `http://hostname/index.php?r=site/index` という URL でリクエストをした場合は、`site` コントローラの中の `index` アクションが実行されます。 ですから、ユーザが `http://hostname/index.php?r=site/index` という URL でリクエストをした場合は、`site` コントローラの中の `index` アクションが実行されます。
どのようにしてルートがアクションとして解決されるかについて、更なる詳細は [ルーティングと URL 生成](runtime-routing.md) の節を参照してください。 ルートがどのようにしてアクションとして解決されるかについての詳細は、[ルーティングと URL 生成](runtime-routing.md) の節を参照してください。
## コントローラを作成する<a name="creating-controllers"></a> ## コントローラを作成する<a name="creating-controllers"></a>
[[yii\web\Application|ウェブアプリケーション]] では、コントローラは [[yii\web\Controller]] またはその子クラスから派生させるべきです。 [[yii\web\Application|ウェブアプリケーション]] では、コントローラは [[yii\web\Controller]] またはその子クラスから派生させるべきものです。
同様に、[[yii\console\Application|コンソールアプリケーション]] では、コントローラは [[yii\console\Controller]] またはその子クラスから派生させるべきです。 同様に、[[yii\console\Application|コンソールアプリケーション]] では、コントローラは [[yii\console\Controller]] またはその子クラスから派生させるべきものです。
次のコードは `site` コントローラを定義するものです: 次のコードは `site` コントローラを定義するものです
```php ```php
namespace app\controllers; namespace app\controllers;
...@@ -113,43 +111,41 @@ class SiteController extends Controller ...@@ -113,43 +111,41 @@ class SiteController extends Controller
この理由により、たいていはコントローラが処理するリソースの型を示す名詞をコントローラの ID として使います。 この理由により、たいていはコントローラが処理するリソースの型を示す名詞をコントローラの ID として使います。
例えば、記事データを処理するコントローラの ID としては、`article` を使うことが出来ます。 例えば、記事データを処理するコントローラの ID としては、`article` を使うことが出来ます。
既定では、コントローラの ID は、以下の文字のみを含むべきものです: すなわち、小文字の英字、数字、アンダースコア、ダッシュ、 既定では、コントローラの ID は、小文字の英字、数字、アンダースコア、ダッシュ、および、フォワードスラッシュのみを含むべきものです。
および、フォワードスラッシュ。
例えば、`article``post-comment` はともに有効なコントローラの ID ですが、`article?``PostComment``admin\post` は有効ではありません。 例えば、`article``post-comment` はともに有効なコントローラの ID ですが、`article?``PostComment``admin\post` は有効ではありません。
コントローラの ID は、サブディレクトリの接頭辞を含んでも構いません。例えば、`admin/article` は、 コントローラの ID は、サブディレクトリの接頭辞を含んでも構いません。例えば、`admin/article` は、[[yii\base\Application::controllerNamespace|コントローラ名前空間]]
[[yii\base\Application::controllerNamespace|コントローラ名前空間]] の下の `admin` サブディレクトリにある `article` コントローラを表します。 の下の `admin` サブディレクトリにある `article` コントローラを表します。
サブディレクトリの接頭辞として有効な文字は以下を含みます: 小文字または大文字の英字、数字、アンダースコア、そして、 サブディレクトリの接頭辞として有効な文字は、小文字または大文字の英字、数字、アンダースコア、そして、
フォワードスラッシュ。フォワードスラッシュは、複数レベルのサブディレクトリの区切り文字として使われます (例えば、`panels/admin`)。 フォワードスラッシュです。
フォワードスラッシュは、複数レベルのサブディレクトリの区切り文字として使われます (例えば、`panels/admin`)。
### コントローラクラスの命名規則<a name="controller-class-naming"></a> ### コントローラクラスの命名規則<a name="controller-class-naming"></a>
コントローラクラスの名前は下記の規則に従ってコントローラの ID から導出することが出来ます: コントローラクラスの名前は下記の規則に従ってコントローラの ID から導出することが出来ます
* ダッシュで区切られた各単語の最初の文字を大文字に変える。コントローラ ID がスラッシュを含む場合、 * ダッシュで区切られた各単語の最初の文字を大文字に変える。
この規則は ID の最後のスラッシュの後ろの部分にのみ適用されることに注意。 コントローラ ID がスラッシュを含む場合、この規則は ID の最後のスラッシュの後ろの部分にのみ適用されることに注意。
* ダッシュを削除し、フォワードスラッシュを全てバックワードスラッシュに置き換える。 * ダッシュを削除し、フォワードスラッシュを全てバックワードスラッシュに置き換える。
* 接尾辞 `Controller` を追加する。 * 接尾辞 `Controller` を追加する。
* そして、[[yii\base\Application::controllerNamespace|コントローラ名前空間]] を頭に付ける。 * そして、[[yii\base\Application::controllerNamespace|コントローラ名前空間]] を頭に付ける。
以下は、[[yii\base\Application::controllerNamespace|コントローラ名前空間]] がデフォルト値 `app\controllers` を取っていると 以下は、[[yii\base\Application::controllerNamespace|コントローラ名前空間]] がデフォルト値 `app\controllers` を取っていると仮定したときの、いくつかの例です。
仮定したときの、いくつかの例です:
* `article` から `app\controllers\ArticleController` が導出される; * `article` から `app\controllers\ArticleController` が導出される
* `post-comment` から `app\controllers\PostCommentController` が導出される; * `post-comment` から `app\controllers\PostCommentController` が導出される
* `admin/post-comment` から `app\controllers\admin\PostCommentController` が導出される; * `admin/post-comment` から `app\controllers\admin\PostCommentController` が導出される
* `adminPanels/post-comment` から `app\controllers\adminPanels\PostCommentController` が導出される。 * `adminPanels/post-comment` から `app\controllers\adminPanels\PostCommentController` が導出される。
コントローラクラスは [オートロード可能](concept-autoloading.md) でなければなりません。この理由により、 コントローラクラスは [オートロード可能](concept-autoloading.md) でなければなりません。
上記の例の `aritcle` コントローラクラスは [エイリアス](concept-aliases.md)`@app/controllers/ArticleController.php` である この理由により、上記の例の `aritcle` コントローラクラスは [エイリアス](concept-aliases.md)`@app/controllers/ArticleController.php`
ファイルに保存されるべきものとなります。一方、`admin/post2-comment` コントローラは `@app/controllers/admin/Post2CommentController.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) は使いたくない、 この方法は、コントローラをいくつかのカテゴリに分けて整理したい、けれども [モジュール](structure-modules.md) は使いたくない、という場合に役立ちます。
という場合に役立ちます。
### コントローラマップ<a name="controller-map"></a> ### コントローラマップ<a name="controller-map"></a>
...@@ -157,7 +153,7 @@ class SiteController extends Controller ...@@ -157,7 +153,7 @@ class SiteController extends Controller
[[yii\base\Application::controllerMap|コントローラマップ]] を構成すると、上で述べたコントローラの ID とクラス名の制約を乗り越えることが出来ます。 [[yii\base\Application::controllerMap|コントローラマップ]] を構成すると、上で述べたコントローラの ID とクラス名の制約を乗り越えることが出来ます。
これは、主として、クラス名に対する制御が及ばないサードパーティのコントローラを使おうとする場合に有用です。 これは、主として、クラス名に対する制御が及ばないサードパーティのコントローラを使おうとする場合に有用です。
[[yii\base\Application::controllerMap|コントローラマップ]] は [アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) の中で、次のように構成することが出来ます: [[yii\base\Application::controllerMap|コントローラマップ]] は [アプリケーションの構成情報](structure-applications.md#application-configurations) の中で、次のように構成することが出来ます。
```php ```php
[ [
...@@ -165,7 +161,7 @@ class SiteController extends Controller ...@@ -165,7 +161,7 @@ class SiteController extends Controller
// クラス名を使って "account" コントローラを宣言する // クラス名を使って "account" コントローラを宣言する
'account' => 'app\controllers\UserController', 'account' => 'app\controllers\UserController',
// コンフィギュレーション配列を使って "article" コントローラを宣言する // 構成情報配列を使って "article" コントローラを宣言する
'article' => [ 'article' => [
'class' => 'app\controllers\PostController', 'class' => 'app\controllers\PostController',
'enableCsrfValidation' => false, 'enableCsrfValidation' => false,
...@@ -182,7 +178,7 @@ class SiteController extends Controller ...@@ -182,7 +178,7 @@ class SiteController extends Controller
[[yii\web\Application|ウェブアプリケーション]] では、この値は `'site'` であり、一方、[[yii\console\Application|コンソールアプリケーション]] では、`help` です。 [[yii\web\Application|ウェブアプリケーション]] では、この値は `'site'` であり、一方、[[yii\console\Application|コンソールアプリケーション]] では、`help` です。
従って、URL が `http://hostname/index.php` である場合は、`site` コントローラがリクエストを処理することになります。 従って、URL が `http://hostname/index.php` である場合は、`site` コントローラがリクエストを処理することになります。
次のように [アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) を構成して、デフォルトコントローラを変更することが出来ます: 次のように [アプリケーションの構成情報](structure-applications.md#application-configurations) を構成して、デフォルトコントローラを変更することが出来ます。
```php ```php
[ [
...@@ -196,7 +192,7 @@ class SiteController extends Controller ...@@ -196,7 +192,7 @@ class SiteController extends Controller
アクションの作成は、コントローラクラスの中にいわゆる *アクションメソッド* を定義するだけの簡単なことです。 アクションの作成は、コントローラクラスの中にいわゆる *アクションメソッド* を定義するだけの簡単なことです。
アクションメソッドとは、`action` という語で始まる名前を持つ *public* メソッドのことです。 アクションメソッドとは、`action` という語で始まる名前を持つ *public* メソッドのことです。
アクションメソッドの返り値がエンドユーザに送信されるレスポンスデータを表します。 アクションメソッドの返り値がエンドユーザに送信されるレスポンスデータを表します。
次のコードは、`index``hello-world` という二つのアクションを定義するものです: 次のコードは、`index``hello-world` という二つのアクションを定義するものです
```php ```php
namespace app\controllers; namespace app\controllers;
...@@ -220,52 +216,51 @@ class SiteController extends Controller ...@@ -220,52 +216,51 @@ class SiteController extends Controller
### アクション ID<a name="action-ids"></a> ### アクション ID<a name="action-ids"></a>
アクションは、たいてい、あるリソースについて特定の操作を実行するように設計されます。この理由により、 アクションは、たいてい、あるリソースについて特定の操作を実行するように設計されます。
アクション ID は、通常、`view``update` などのような動詞になります。 この理由により、アクション ID は、通常、`view``update` などのような動詞になります。
既定では、アクション ID は次の文字のみを含むべきものです: すなわち、小文字の英字、数字、アンダースコア、そして、ダッシュ 既定では、アクション ID は、小文字の英字、数字、アンダースコア、そして、ダッシュのみを含むべきものです
アクション ID の中のダッシュは単語を分けるために使われます。例えば、 アクション ID の中のダッシュは単語を分けるために使われます。
`view``update2``comment-post` は全て有効なアクション ID ですが、`view?``Update` は有効ではありません。 例えば、`view``update2``comment-post` は全て有効なアクション ID ですが、`view?``Update` は有効ではありません。
アクションは二つの方法で作成することが出来ます: すなわち、インラインアクションとスタンドアロンアクションです。 アクションは二つの方法で作成することが出来ますすなわち、インラインアクションとスタンドアロンアクションです。
インラインアクションはコントローラクラスのメソッドとして定義されるものであり、一方、スタンドアロンアクションは インラインアクションはコントローラクラスのメソッドとして定義されるものであり、一方、スタンドアロンアクションは
[[yii\base\Action]] またはその子クラスから派生させたクラスです。 [[yii\base\Action]] またはその子クラスから派生させたクラスです。
インラインアクションは作成するのにより少ない労力を要し、アクションを再利用する意図がない場合によく推奨されます。 インラインアクションは作成するのにより少ない労力を要し、アクションを再利用する意図がない場合によく推奨されます。
もう一方で、スタンドアロンアクションは、主として、さまざまなコントローラの中で使われることや、 もう一方で、スタンドアロンアクションは、主として、さまざまなコントローラの中で使われることや、[エクステンション](structure-extensions.md)
[エクステンション](structure-extensions.md) として再配布されることを意図して作成されます。 として再配布されることを意図して作成されます。
### インラインアクション<a name="inline-actions"></a> ### インラインアクション<a name="inline-actions"></a>
インラインアクションは、たった今説明したように、アクションメソッドとして定義されるアクションを指します。 インラインアクションは、たった今説明したように、アクションメソッドとして定義されるアクションを指します。
アクションメソッドの名前は、次の基準に従って、アクション ID から導出されます: アクションメソッドの名前は、次の基準に従って、アクション ID から導出されます
* アクション ID に含まれる各単語の最初の文字を大文字に変換する; * アクション ID に含まれる各単語の最初の文字を大文字に変換する
* ダッシュを削除する; * ダッシュを削除する
* 前置`action` を前に付ける。 * 接頭`action` を前に付ける。
例えば、`index``actionIndex` となり、`hello-world``actionHelloWorld` となります。 例えば、`index``actionIndex` となり、`hello-world``actionHelloWorld` となります。
> Note|注意: アクションメソッドの名前は、*大文字と小文字を区別* します。`ActionIndex` という名前のメソッドがあっても、 > Note|注意: アクションメソッドの名前は、*大文字と小文字を区別* します。`ActionIndex`
それはアクションメソッドとは見なされず、結果として、`index` アクションに対するリクエストは例外に帰結します。 という名前のメソッドがあっても、 それはアクションメソッドとは見なされず、結果として、`index`
アクションメソッドが public でなければならない事にも注意してください。private や protected なメソッドが アクションに対するリクエストは例外に帰結します。
インラインアクションを定義することはありません。 アクションメソッドが public でなければならない事にも注意してください。
private や protected なメソッドがインラインアクションを定義することはありません。
アクションは、作成するのにほとんど労力を要さないため、たいていの場合、インラインアクションとして定義されます。 インラインアクションは作成するのにほとんど労力を要さないため、たいていのアクションはインラインアクションとして定義されます。
しかしながら、同じアクションを別の場所で再利用する計画があったり、また、アクションを再配布したいと思ったりする場合は、 しかし、同じアクションを別の場所で再利用する計画を持っていたり、また、アクションを再配布したいと思っていたりする場合は、アクションを *スタンドアロンアクション* として定義することを考慮すべきです。
*スタンドアロンアクション* として定義することを考慮すべきです。
### スタンドアロンアクション<a name="standalone-actions"></a> ### スタンドアロンアクション<a name="standalone-actions"></a>
スタンドアロンアクションは、[[yii\base\Action]] またはその子クラスを拡張したクラスとして定義されるものです。 スタンドアロンアクションは、[[yii\base\Action]] またはその子クラスを拡張したクラスとして定義されるものです。
例えば、Yii のリリースに [[yii\web\ViewAction]] と [[yii\web\ErrorAction]] が含まれていますが、これらは両方とも 例えば、Yii のリリースに [[yii\web\ViewAction]] と [[yii\web\ErrorAction]] が含まれていますが、これらは両方ともスタンドアロンアクションです。
スタンドアロンアクションです。
スタンドアロンアクションを使用するためには、下記のように、コントローラの [[yii\base\Controller::actions()]] メソッドを スタンドアロンアクションを使用するためには、下記のように、コントローラの [[yii\base\Controller::actions()]]
オーバーライドして、スタンドアロンアクションを *アクションマップ* の中で宣言します: メソッドをオーバーライドして、スタンドアロンアクションを *アクションマップ* の中で宣言します。
```php ```php
public function actions() public function actions()
...@@ -274,7 +269,7 @@ public function actions() ...@@ -274,7 +269,7 @@ public function actions()
// クラス名を使って "error" アクションを宣言する // クラス名を使って "error" アクションを宣言する
'error' => 'yii\web\ErrorAction', 'error' => 'yii\web\ErrorAction',
// コンフィギュレーション配列を使って "view" アクションを宣言する // 構成情報配列を使って "view" アクションを宣言する
'view' => [ 'view' => [
'class' => 'yii\web\ViewAction', 'class' => 'yii\web\ViewAction',
'viewPrefix' => '', 'viewPrefix' => '',
...@@ -283,10 +278,8 @@ public function actions() ...@@ -283,10 +278,8 @@ public function actions()
} }
``` ```
見ると分かるように、`actions()` メソッドは、キーがアクション ID であり、値が対応するアクションのクラス名または 見ると分かるように、`actions()` メソッドは、キーがアクション ID であり、値が対応するアクションのクラス名または [構成情報](concept-configurations.md) である配列を返すべきものです。
[コンフィギュレーション](concept-configurations.md) である配列を返すべきものです。 インラインアクションと違って、スタンドアロンアクションのアクション ID は、`actions()` メソッドにおいて宣言される限りにおいて、任意の文字を含むことが出来ます。
インラインアクションと違って、スタンドアロンアクションのアクション ID は、`actions()` メソッドにおいて宣言される
限りにおいて、任意の文字を含むことが出来ます。
スタンドアロンアクションクラスを作成するためには、[[yii\base\Action]] またはその子クラスを拡張して、 スタンドアロンアクションクラスを作成するためには、[[yii\base\Action]] またはその子クラスを拡張して、
...@@ -316,14 +309,12 @@ class HelloWorldAction extends Action ...@@ -316,14 +309,12 @@ class HelloWorldAction extends Action
返り値は、エンドユーザにレスポンスとして送信される [レスポンス](runtime-responses.md) オブジェクトとすることが出来ます。 返り値は、エンドユーザにレスポンスとして送信される [レスポンス](runtime-responses.md) オブジェクトとすることが出来ます。
* [[yii\web\Application|ウェブアプリケーション]] では、返り値を、[[yii\web\Response::data]] に割り当てられ、 * [[yii\web\Application|ウェブアプリケーション]] では、[[yii\web\Response::data]] に割り当てられて後にレスポンスの本文を表す文字列へと変換される、任意のデータとすることも出来ます。
さらにレスポンスの本文を表す文字列へと変換される任意のデータとすることも出来ます。 * [[yii\console\Application|コンソールアプリケーション]] では、返り値をコマンド実行の [[yii\console\Response::exitStatus|終了ステータス]] を示す整数とすることも出来ます。
* [[yii\console\Application|コンソールアプリケーション]] では、返り値をコマンド実行の [[yii\console\Response::exitStatus|終了ステータス]]
を示す整数とすることも出来ます。
これまでに示した例においては、アクションの結果はすべて文字列であり、エンドユーザに送信されるレスポンスの本文として扱われるものでした。 これまでに示した例においては、アクションの結果はすべて文字列であり、エンドユーザに送信されるレスポンスの本文として扱われるものでした。
次の例では、アクションがレスポンスオブジェクトを返すことによって、ユーザのブラウザを新しい URL にリダイレクトすることが出来る様子が示されています 次の例では、アクションがレスポンスオブジェクトを返すことによって、ユーザのブラウザを新しい URL にリダイレクトすることが出来る様子が示されています
([[yii\web\Controller::redirect()|redirect()]] メソッドの返り値はレスポンスオブジェクトです): ([[yii\web\Controller::redirect()|redirect()]] メソッドの返り値はレスポンスオブジェクトです)
```php ```php
public function actionForward() public function actionForward()
...@@ -336,13 +327,12 @@ public function actionForward() ...@@ -336,13 +327,12 @@ public function actionForward()
### アクションパラメータ<a name="action-parameters"></a> ### アクションパラメータ<a name="action-parameters"></a>
インラインアクションのアクションメソッドと、スタンドアロンアクションの `run()` メソッドは、 インラインアクションのアクションメソッドと、スタンドアロンアクションの `run()` メソッドは、*アクションパラメータ* と呼ばれる引数を取ることが出来ます。
*アクションパラメータ* と呼ばれる引数を取ることが出来ます。
パラメータの値はリクエストから取得されます。 パラメータの値はリクエストから取得されます。
[[yii\web\Application|ウェブアプリケーション]] では、各アクションパラメータの値は `$_GET` からパラメータ名をキーとして読み出されます。 [[yii\web\Application|ウェブアプリケーション]] では、各アクションパラメータの値は `$_GET` からパラメータ名をキーとして読み出されます。
[[yii\console\Application|コンソールアプリケーション]] では、アクションパラメータはコマンドライン引数に対応します。 [[yii\console\Application|コンソールアプリケーション]] では、アクションパラメータはコマンドライン引数に対応します。
次の例では、`view` アクション (インラインアクションです) は、二つのパラメータを宣言しています: すなわち、`$id``$version`す。 次の例では、`view` アクション (インラインアクションです) は、二つのパラメータ、すなわち、`$id``$version` を宣言しています。
```php ```php
namespace app\controllers; namespace app\controllers;
...@@ -358,18 +348,15 @@ class PostController extends Controller ...@@ -358,18 +348,15 @@ class PostController extends Controller
} }
``` ```
アクションパラメータは、次のように、さまざまなリクエストに応じて値を投入されます: アクションパラメータは、次のように、さまざまなリクエストに応じて値を投入されます
* `http://hostname/index.php?r=post/view&id=123`: `$id` パラメータには `'123'` という値が入れられますが、 * `http://hostname/index.php?r=post/view&id=123`: `$id` パラメータには `'123'` という値が入れられますが、`version`
`version` というクエリパラメータが無いので、`$version` は null のままになります。 というクエリパラメータは無いので、`$version` は null のままになります。
* `http://hostname/index.php?r=post/view&id=123&version=2`: `$id` および `$version` パラメータに、それぞれ、 * `http://hostname/index.php?r=post/view&id=123&version=2`: `$id` および `$version` パラメータに、それぞれ、`'123'``'2'` が入ります。
`'123'``'2'` が入ります。 * `http://hostname/index.php?r=post/view`: 必須の `$id` パラメータがリクエストで提供されていないため、 [[yii\web\BadRequestHttpException]] 例外が投げられます。
* `http://hostname/index.php?r=post/view`: 必須の `$id` パラメータがリクエストで提供されていないため、 * `http://hostname/index.php?r=post/view&id[]=123`: `$id` パラメータが予期しない配列値 `['123']` を受け取ろうとするため、[[yii\web\BadRequestHttpException]] 例外が投げられます。
[[yii\web\BadRequestHttpException]] 例外が投げられます。
* `http://hostname/index.php?r=post/view&id[]=123`: `$id` パラメータが予期しない配列値 `['123']` を受け取ろうとするため、
[[yii\web\BadRequestHttpException]] 例外が投げられます。
アクションパラメータに配列値を受け取らせたい場合は、以下のように、パラメータに `array` の型ヒントを付けなければなりません: アクションパラメータに配列値を受け取らせたい場合は、以下のように、パラメータに `array` の型ヒントを付けなければなりません
```php ```php
public function actionView(array $id, $version = null) public function actionView(array $id, $version = null)
...@@ -378,13 +365,11 @@ public function actionView(array $id, $version = null) ...@@ -378,13 +365,11 @@ public function actionView(array $id, $version = null)
} }
``` ```
このようにすると、リクエストが `http://hostname/index.php?r=post/view&id[]=123` である場合、`$id` パラメータは このようにすると、リクエストが `http://hostname/index.php?r=post/view&id[]=123` である場合、`$id` パラメータは `['123']` という値を受け取るようになります。
`['123']` という値を受け取るようになります。 リクエストが `http://hostname/index.php?r=post/view&id=123` である場合も、スカラ値 `'123'` が自動的に配列に変換されるため、`$id` パラメータは引き続き同じ配列値を受け取ります。
リクエストが `http://hostname/index.php?r=post/view&id=123` である場合も、スカラ値 `'123'` が自動的に配列に変換されるため、
`$id` パラメータは引き続き同じ配列値を受け取ります。
上記の例は主としてウェブアプリケーションでのアクションパラメータの動作を示すものです。 上記の例は主としてウェブアプリケーションでのアクションパラメータの動作を示すものです。
コンソールアプリケーションについては、[コンソールコマンド](tutorial-console.md) の節で更なる詳細を参照してください。 コンソールアプリケーションについては、[コンソールコマンド](tutorial-console.md) の節で詳細を参照してください。
### デフォルトアクション<a name="default-action"></a> ### デフォルトアクション<a name="default-action"></a>
...@@ -393,7 +378,7 @@ public function actionView(array $id, $version = null) ...@@ -393,7 +378,7 @@ public function actionView(array $id, $version = null)
[ルート](#ids-routes) がコントローラ ID のみを含む場合は、指定されたコントローラのデフォルトアクションがリクエストされたことを意味します。 [ルート](#ids-routes) がコントローラ ID のみを含む場合は、指定されたコントローラのデフォルトアクションがリクエストされたことを意味します。
既定では、デフォルトアクションは `index` と設定されます。 既定では、デフォルトアクションは `index` と設定されます。
このデフォルト値を変更したい場合は、以下のように、コントローラクラスでこのプロパティをオーバーライドするだけです: このデフォルト値を変更したい場合は、以下のように、コントローラクラスでこのプロパティをオーバーライドするだけです
```php ```php
namespace app\controllers; namespace app\controllers;
...@@ -414,40 +399,34 @@ class SiteController extends Controller ...@@ -414,40 +399,34 @@ class SiteController extends Controller
## コントローラのライフサイクル<a name="controller-lifecycle"></a> ## コントローラのライフサイクル<a name="controller-lifecycle"></a>
リクエストを処理するときに、[アプリケーション](structure-applications.md) はリクエストされた [ルート](#routes)に基いてコントローラを作成します。 リクエストを処理するときに、[アプリケーション](structure-applications.md) はリクエストされた [ルート](#routes) に基いてコントローラを作成します。
そして、次に、コントローラはリクエストに応じるために以下のライフサイクルを経過します: そして、次に、コントローラはリクエストに応じるために以下のライフサイクルを経過します
1. コントローラが作成され構成された後、[[yii\base\Controller::init()]] メソッドが呼ばれる。 1. コントローラが作成され構成された後、[[yii\base\Controller::init()]] メソッドが呼ばれる。
2. コントローラは、リクエストされたアクション ID に基いて、アクションオブジェクトを作成する: 2. コントローラは、リクエストされたアクション ID に基いて、アクションオブジェクトを作成する
* アクション ID が指定されていないときは、[[yii\base\Controller::defaultAction|デフォルトアクション ID]] が使われる。 * アクション ID が指定されていないときは、[[yii\base\Controller::defaultAction|デフォルトアクション ID]] が使われる。
* アクション ID が [[yii\base\Controller::actions()|アクションマップ]] の中に見つかった場合は、 * アクション ID が [[yii\base\Controller::actions()|アクションマップ]] の中に見つかった場合は、スタンドアロンアクションが作成される。
スタンドアロンアクションが作成される。
* アクション ID に合致するアクションメソッドが見つかった場合は、インラインアクションが作成される。 * アクション ID に合致するアクションメソッドが見つかった場合は、インラインアクションが作成される。
* アクションが見つからないと、[[yii\base\InvalidRouteException]] 例外が投げられる。 * アクションが見つからないと、[[yii\base\InvalidRouteException]] 例外が投げられる。
3. コントローラは、アプリケーション、(コントローラがモジュールに属する場合は) モジュール、そしてコントローラの 3. コントローラは、アプリケーション、(コントローラがモジュールに属する場合は) モジュール、そしてコントローラの `beforeAction()` メソッドをこの順で呼び出す。
`beforeAction()` メソッドをこの順で呼び出す: * どれか一つの呼び出しが false を返した場合は、残りのまだ呼ばれていない `beforeAction()` はスキップされ、アクションの実行はキャンセルされる。
* どれか一つの呼び出しが false を返した場合は、残りのまだ呼ばれていない `beforeAction()` はスキップされ、 * 既定では、それぞれの `beforeAction()` メソッドは、ハンドラをアタッチすることが可能な `beforeAction` イベントをトリガする。
アクションの実行はキャンセルされる。 4. コントローラがアクションを走らせる。
* 既定では、それぞれの `beforeAction()` メソッドは、ハンドラを取り付けることが出来る `beforeAction` イベントをトリガする。
4. コントローラがアクションを走らせる:
* リクエストデータが解析されて、アクションパラメータにデータが投入される。 * リクエストデータが解析されて、アクションパラメータにデータが投入される。
5. コントローラは、コントローラ、(コントローラがモジュールに属する場合は) モジュール、そしてアプリケーションの 5. コントローラは、コントローラ、(コントローラがモジュールに属する場合は) モジュール、そしてアプリケーションの `afterAction()` メソッドをこの順で呼び出す。
`afterAction()` メソッドをこの順で呼び出す。 * 既定では、それぞれの `afterAction()` メソッドは、ハンドラをアタッチすることが可能な `afterAction` イベントをトリガする。
* 既定では、それぞれの `afterAction()` メソッドは、ハンドラを取り付けることが出来る `afterAction` イベントをトリガする。
6. アプリケーションはアクションの結果を受け取り、それを [レスポンス](runtime-responses.md) に割り当てる。 6. アプリケーションはアクションの結果を受け取り、それを [レスポンス](runtime-responses.md) に割り当てる。
## 最善の慣行<a name="best-practices"></a> ## 最善の慣行<a name="best-practices"></a>
良く設計されたアプリケーションでは、コントローラはたいてい非常に軽いものになり、 良く設計されたアプリケーションでは、コントローラはたいてい非常に軽いものになり、それぞれのアクションは数行のコードしか含まないものになります。
それぞれのアクションは数行のコードしか含まないものになります。 あなたのコントローラが少々複雑になっている場合、そのことは、通常、コントローラをリファクタして、コードの一部を他のクラスに移動すべきことを示すものです。
あなたのコントローラが少々複雑になっている場合、そのことは、通常、コントローラをリファクタして、
コードの一部を他のクラスに移動すべきことを示すものです。
要約すると、コントローラは、 要約すると、コントローラは、
* [リクエスト](runtime-requests.md) データにアクセスすることが出来ます; * [リクエスト](runtime-requests.md) データにアクセスすることが出来ます
* リクエストデータを使って [モデル](structure-models.md) や他のサービスコンポーネントのメソッドを呼ぶことが出来ます; * リクエストデータを使って [モデル](structure-models.md) や他のサービスコンポーネントのメソッドを呼ぶことが出来ます
* [ビュー](structure-views.md) を使ってレスポンスを構成することが出来ます; * [ビュー](structure-views.md) を使ってレスポンスを構成することが出来ます
* リクエストされたデータの処理をするべきではありません - データは [モデル](structure-models.md) において処理されるべきです; * リクエストされたデータの処理をするべきではありません - データは [モデル](structure-models.md) において処理されるべきです
* HTML を埋め込むなどの表示に関わるコードは避けるべきです - 表示は [ビュー](structure-views.md) で行う方が良いです。 * HTML を埋め込むなどの表示に関わるコードは避けるべきです - 表示は [ビュー](structure-views.md) で行う方が良いです。
...@@ -3,30 +3,27 @@ ...@@ -3,30 +3,27 @@
エントリスクリプトは、アプリケーションのブートストラップ過程のチェーンにおける最初の環です。 エントリスクリプトは、アプリケーションのブートストラップ過程のチェーンにおける最初の環です。
アプリケーションは (ウェブアプリケーションであれ、コンソールアプリケーションであれ)単一のエントリスクリプトを持ちます。 アプリケーションは (ウェブアプリケーションであれ、コンソールアプリケーションであれ)単一のエントリスクリプトを持ちます。
エンドユーザはエントリスクリプトに対してリクエストを発行し、エントリスクリプトはアプリケーションのインスタンスを作成して、 エンドユーザはエントリスクリプトに対してリクエストを発行し、エントリスクリプトはアプリケーションのインスタンスを作成して、それにリクエストを送付します。
それにリクエストを送付します。
ウェブアプリケーションのエントリスクリプトは、エンドユーザからアクセス出来るように、 ウェブアプリケーションのエントリスクリプトは、エンドユーザからアクセス出来るように、ウェブからのアクセスが可能なディレクトリの下に保管されなければなりません。
ウェブからのアクセスが可能なディレクトリの下に保管されなければなりません。 たいていは `index.php` と名付けられますが、ウェブサーバが見つけることが出来る限り、どのような名前を使っても構いません。
大抵は `index.php` と名付けられますが、ウェブサーバが見つけることが出来る限り、どのような名前を使っても構いません。
コンソールアプリケーションのエントリスクリプトは、通常は、アプリケーションの [ベースパス](structure-applications.md) コンソールアプリケーションのエントリスクリプトは、通常は、アプリケーションの [ベースパス](structure-applications.md) の下に保管され、`yii` と名付けられます (`.php` の拡張子を伴います) 。
下に保管され、`yii` と名付けられます (`.php` の拡張子を伴います) 。
これは、ユーザが `./yii <route> [引数] [オプション]` というコマンドによってコンソールアプリケーションを走らせることが出来るようにするためのスクリプトであり、実行可能なパーミッションを与えられるべきものです。 これは、ユーザが `./yii <route> [引数] [オプション]` というコマンドによってコンソールアプリケーションを走らせることが出来るようにするためのスクリプトであり、実行可能なパーミッションを与えられるべきものです。
エントリスクリプトは主として次の仕事をします: エントリスクリプトは主として次の仕事をします
* グローバルな定数を定義する; * グローバルな定数を定義する;
* [Composer のオートローダ](http://getcomposer.org/doc/01-basic-usage.md#autoloading) を登録する; * [Composer のオートローダ](http://getcomposer.org/doc/01-basic-usage.md#autoloading) を登録する
* [[Yii]] クラスファイルをインクルードする; * [[Yii]] クラスファイルをインクルードする
* アプリケーションのコンフィギュレーションを読み出す; * アプリケーションの構成情報を読み出す。
* [アプリケーション](structure-applications.md) のインスタンスを生成して構成する; * [アプリケーション](structure-applications.md) のインスタンスを生成して構成する
* [[yii\base\Application::run()]] を呼んで、受け取ったリクエストを処理する。 * [[yii\base\Application::run()]] を呼んで、受け取ったリクエストを処理する。
## ウェブアプリケーション<a name="web-applications"></a> ## ウェブアプリケーション<a name="web-applications"></a>
次に示すのが、[ベーシックウェブアプリケーションテンプレート](start-installation.md) のエントリスクリプトです: 次に示すのが、[ベーシックウェブアプリケーションテンプレート](start-installation.md) のエントリスクリプトです
```php ```php
<?php <?php
...@@ -40,7 +37,7 @@ require(__DIR__ . '/../vendor/autoload.php'); ...@@ -40,7 +37,7 @@ require(__DIR__ . '/../vendor/autoload.php');
// Yii クラスファイルをインクルード // Yii クラスファイルをインクルード
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php'); require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
// アプリケーションのコンフィギュレーションを読み出す // アプリケーションの構成情報を読み出す
$config = require(__DIR__ . '/../config/web.php'); $config = require(__DIR__ . '/../config/web.php');
// アプリケーションを作成し、構成して、走らせる // アプリケーションを作成し、構成して、走らせる
...@@ -75,7 +72,7 @@ require(__DIR__ . '/vendor/autoload.php'); ...@@ -75,7 +72,7 @@ require(__DIR__ . '/vendor/autoload.php');
// Yii クラスファイルをインクルード // Yii クラスファイルをインクルード
require(__DIR__ . '/vendor/yiisoft/yii2/Yii.php'); require(__DIR__ . '/vendor/yiisoft/yii2/Yii.php');
// アプリケーションのコンフィギュレーションを読み出す // アプリケーションの構成情報を読み出す
$config = require(__DIR__ . '/config/console.php'); $config = require(__DIR__ . '/config/console.php');
$application = new yii\console\Application($config); $application = new yii\console\Application($config);
...@@ -90,23 +87,22 @@ exit($exitCode); ...@@ -90,23 +87,22 @@ exit($exitCode);
Yii は下記の三つの定数をサポートしています: Yii は下記の三つの定数をサポートしています:
* `YII_DEBUG`: アプリケーションがデバッグモードで走るかどうかを規定します。 * `YII_DEBUG`: アプリケーションがデバッグモードで走るかどうかを規定します。
デバッグモードにおいては、アプリケーションはより多くのログ情報を保持し、 デバッグモードにおいては、アプリケーションはより多くのログ情報を保持し、例外が投げられたときに、より詳細なエラーのコールスタックを表示します。
例外が投げられたときに、より詳細なエラーのコールスタックを表示します。
この理由により、デバッグモードは主として開発時に使用されるべきものとなります。 この理由により、デバッグモードは主として開発時に使用されるべきものとなります。
`YII_DEBUG` の既定値は false です。 `YII_DEBUG` の既定値は false です。
* `YII_ENV`: どういう環境でアプリケーションが走るかを規定します。 * `YII_ENV`: どういう環境でアプリケーションが走るかを規定します。
詳細については、[コンフィギュレーション](concept-configurations.md#environment-constants) の節で説明されます。 詳細については、[構成情報](concept-configurations.md#environment-constants) の節で説明されます。
`YII_ENV` の既定値は `'prod'` です。これはアプリケーションが実運用環境で走ることを意味します。 `YII_ENV` の既定値は `'prod'` です。これはアプリケーションが実運用環境で走ることを意味します。
* `YII_ENABLE_ERROR_HANDLER`: Yii によって提供されるエラーハンドラを有効にするかどうかを規定します。 * `YII_ENABLE_ERROR_HANDLER`: Yii によって提供されるエラーハンドラを有効にするかどうかを規定します。
この定数の既定値は true です。 この定数の既定値は true です。
定数を定義するときには、しばしば次のようなコードを用います: 定数を定義するときには、しばしば次のようなコードを用います
```php ```php
defined('YII_DEBUG') or define('YII_DEBUG', true); defined('YII_DEBUG') or define('YII_DEBUG', true);
``` ```
これは下記のコードと同じ意味のものです: これは下記のコードと同じ意味のものです
```php ```php
if (!defined('YII_DEBUG')) { if (!defined('YII_DEBUG')) {
......
エクステンション エクステンション
================ ================
エクステンションは、Yii のアプリケーションで使われることに限定して設計され、そのまますぐに使える機能を提供する エクステンションは、Yii のアプリケーションで使われることに限定して設計され、そのまますぐに使える機能を提供する再配布可能なソフトウェアパッケージです。
再配布可能なソフトウェアパッケージです。例えば、[yiisoft/yii2-debug](tool-debugger.md) エクステンションは、 例えば、[yiisoft/yii2-debug](tool-debugger.md) エクステンションは、あなたのアプリケーションにおいて、全てのページの末尾に便利なデバッグツールバーを追加して、ページが生成される過程をより容易に把握できるように手助けしてくれます。
あなたのアプリケーションにおいて、全てのページの末尾に便利なデバッグツールバーを追加して、ページが生成される過程を エクステンションを使うと、あなたの開発プロセスを加速することが出来ます。
より容易に把握できるように手助けしてくれます。エクステンションを使うと、あなたの開発プロセスを加速することが出来ます。
また、あなたのコードをエクステンションとしてパッケージ化すると、あなたの優れた仕事を他の人たちと共有することが出来ます。 また、あなたのコードをエクステンションとしてパッケージ化すると、あなたの優れた仕事を他の人たちと共有することが出来ます。
> Info|情報: 「エクステンション」という用語は Yii に限定されたソフトウェアパッケージを指すものとして使用します。 > Info|情報: 「エクステンション」という用語は Yii に限定されたソフトウェアパッケージを指すものとして使用します。
...@@ -12,25 +11,24 @@ ...@@ -12,25 +11,24 @@
## エクステンションを使う <a name="using-extensions"></a> ## エクステンションを使う <a name="using-extensions"></a>
エクステンションを使うためには、先ずはそれをインストールする必要があります。ほとんどのエクステンションは [Composer](https://getcomposer.org/) エクステンションを使うためには、先ずはそれをインストールする必要があります。
パッケージとして配布されていて、次の二つの簡単なステップをふめばインストールすることが出来ます: とんどのエクステンションは [Composer](https://getcomposer.org/) のパッケージとして配布されていて、次の二つの簡単なステップをふめばインストールすることが出来ます。
1. アプリケーションの `composer.json` ファイルを修正して、どのエクステンション (Composer パッケージ) をインストールしたいかを指定する。 1. アプリケーションの `composer.json` ファイルを修正して、どのエクステンション (Composer パッケージ) をインストールしたいかを指定する。
2. `composer install` コマンドを走らせて指定したエクステンションをインストールする。 2. `composer install` コマンドを走らせて指定したエクステンションをインストールする。
[Composer](https://getcomposer.org/) を持っていない場合は、それをインストールする必要があることに注意してください。 [Composer](https://getcomposer.org/) を持っていない場合は、それをインストールする必要があることに注意してください。
既定では、Composer は [Packagist](https://packagist.org/) に登録されたパッケージをインストールします。Packagist は 既定では、Composer は [Packagist](https://packagist.org/) に登録されたパッケージをインストールします。
オープンソース Composer パッケージの最大のレポジトリであり、そこでエクステンションを探すことが出来ます。 Packagist はオープンソース Composer パッケージの最大のレポジトリであり、そこでエクステンションを探すことが出来ます。
また、[自分自身のレポジトリを作成](https://getcomposer.org/doc/05-repositories.md#repository) して、それを使うように また、[自分自身のレポジトリを作成](https://getcomposer.org/doc/05-repositories.md#repository) して、それを使うように Composer を構成することも出来ます。
Composer を構成することも出来ます。これは、あなたがプライベートなエクステンションを開発していて、 これは、あなたがプライベートなエクステンションを開発していて、それを自分のプロジェクト間でのみ共有したい場合に役に立つ方法です。
それを自分のプロジェクト間でのみ共有したい場合に役に立つ方法です。
Composer によってインストールされるエクステンションは `BasePath/vendor` ディレクトリに保存されます。ここで `BasePath` Composer によってインストールされるエクステンションは `BasePath/vendor` ディレクトリに保存されます。
、アプリケーションの [ベースパス](structure-applications.md#basePath) を指します。Composer は依存関係を管理するものですから、 こで `BasePath` は、アプリケーションの [ベースパス](structure-applications.md#basePath) を指します。
パッケージをインストールするときには、それが依存している全てのパッケージをも同時にインストールします。 Composer は依存関係を管理するものですから、あるパッケージをインストールするときには、それが依存する全てのパッケージも同時にインストールします。
例えば、`yiisoft/yii2-imagine` エクステンションをインストールするためには、あなたの `composer.json` を次のように修正します: 例えば、`yiisoft/yii2-imagine` エクステンションをインストールするためには、あなたの `composer.json` を次のように修正します。
```json ```json
{ {
...@@ -44,8 +42,8 @@ Composer 縺ォ繧医▲縺ヲ繧、繝ウ繧ケ繝医繝ォ縺輔l繧九お繧ッ繧ケ繝Φ繧キ繝ァ繝ウ縺ッ `Bas ...@@ -44,8 +42,8 @@ Composer 縺ォ繧医▲縺ヲ繧、繝ウ繧ケ繝医繝ォ縺輔l繧九お繧ッ繧ケ繝Φ繧キ繝ァ繝ウ縺ッ `Bas
} }
``` ```
インストール完了後には、`BasePath/vendor` の下に `yiisoft/yii2-imagine` ディレクトリが作られている筈です。それと同時に、 インストール完了後には、`BasePath/vendor` の下に `yiisoft/yii2-imagine` ディレクトリが作られている筈です。
`imagine/imagine` という別のディレクトリも作られて、依存するパッケージがそこにインストールされている筈です。 それと同時に、`imagine/imagine` という別のディレクトリも作られて、依存するパッケージがそこにインストールされている筈です。
> Info|情報: `yiisoft/yii2-imagine` は Yii 開発チームによって開発され保守されるコアエクステンションの一つです。 > Info|情報: `yiisoft/yii2-imagine` は Yii 開発チームによって開発され保守されるコアエクステンションの一つです。
全てのコアエクステンションは [Packagist](https://packagist.org/) でホストされ、`yiisoft/yii2-xyz` のように名付けられます。 全てのコアエクステンションは [Packagist](https://packagist.org/) でホストされ、`yiisoft/yii2-xyz` のように名付けられます。
...@@ -53,7 +51,7 @@ Composer 縺ォ繧医▲縺ヲ繧、繝ウ繧ケ繝医繝ォ縺輔l繧九お繧ッ繧ケ繝Φ繧キ繝ァ繝ウ縺ッ `Bas ...@@ -53,7 +51,7 @@ Composer 縺ォ繧医▲縺ヲ繧、繝ウ繧ケ繝医繝ォ縺輔l繧九お繧ッ繧ケ繝Φ繧キ繝ァ繝ウ縺ッ `Bas
これであなたはインストールされたエクステンションをあなたのアプリケーションの一部であるかのように使うことが出来ます。 これであなたはインストールされたエクステンションをあなたのアプリケーションの一部であるかのように使うことが出来ます。
次の例は、`yiisoft/yii2-imagine` エクステンションによって提供される `yii\imagine\Image` クラスをどのようにして使うことが 次の例は、`yiisoft/yii2-imagine` エクステンションによって提供される `yii\imagine\Image` クラスをどのようにして使うことが
出来るかを示すものです: 出来るかを示すものです。
```php ```php
use Yii; use Yii;
...@@ -70,17 +68,18 @@ Image::thumbnail('@webroot/img/test-image.jpg', 120, 120) ...@@ -70,17 +68,18 @@ Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
### エクステンションを手作業でインストールする <a name="installing-extensions-manually"></a> ### エクステンションを手作業でインストールする <a name="installing-extensions-manually"></a>
あまり無いことですが、いくつかまたは全てのエクステンションを Composer に頼らずに手作業でインストールしたい場合があるかもしれません。 あまり無いことですが、いくつかまたは全てのエクステンションを Composer に頼らずに手作業でインストールしたい場合があるかもしれません。
そうするためには、次のようにしなければなりません: そうするためには、次のようにしなければなりません。
1. エクステンションのアーカイブファイルをダウンロードして、`vendor` ディレクトリに解凍する。 1. エクステンションのアーカイブファイルをダウンロードして、`vendor` ディレクトリに解凍する。
2. もし有れば、エクステンションによって提供されているクラスオートローダをインストールする。 2. もし有れば、エクステンションによって提供されているクラスオートローダをインストールする。
3. 指示に従って、依存するエクステンションを全てダウンロードしインストールする。 3. 指示に従って、依存するエクステンションを全てダウンロードしインストールする。
エクステンションがクラスオートローダを持っていなくても、[PSR-4 標準](http://www.php-fig.org/psr/psr-4/) に従っている場合は、 エクステンションがクラスオートローダを持っていなくても、[PSR-4 標準](http://www.php-fig.org/psr/psr-4/)
Yii によって提供されているクラスオートローダを使ってエクステンションのクラスをオートロードすることが出来ます。必要なことは、 に従っている場合は、Yii によって提供されているクラスオートローダを使ってエクステンションのクラスをオートロードすることが出来ます。
エクステンションのルートディレクトリのための [ルートエイリアス](concept-aliases.md#defining-aliases) を宣言することだけです。 必要なことは、エクステンションのルートディレクトリのための [ルートエイリアス](concept-aliases.md#defining-aliases) を宣言することだけです。
例えば、エクステンションを `vendor/mycompany/myext` というディレクトリにインストールしたと仮定します。そして、エクステンションの 例えば、エクステンションを `vendor/mycompany/myext` というディレクトリにインストールしたと仮定します。
クラスは `myext` 名前空間の下にあるとします。その場合、アプリケーションのコンフィギュレーションに下記のコードを含めれば良いのです: そして、エクステンションのクラスは `myext` 名前空間の下にあるとします。
その場合、アプリケーションのコンフィギュレーションに下記のコードを含めれば良いのです。
```php ```php
[ [
...@@ -94,26 +93,27 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ ...@@ -94,26 +93,27 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ
## エクステンションを作成する <a name="creating-extensions"></a> ## エクステンションを作成する <a name="creating-extensions"></a>
あなたの優れたコードを他の人々と共有する必要があると感じたときは、エクステンションを作成することを考慮するのが良いでしょう。 あなたの優れたコードを他の人々と共有する必要があると感じたときは、エクステンションを作成することを考慮するのが良いでしょう。
エクステンションは、ヘルパークラス、ウィジェット、モジュールなど、どのようなコードでも含むことが出来ます。 エクステンションは、ヘルパクラス、ウィジェッ、モジュールなど、どのようなコードでも含むことが出来ます。
エクステンションは、[Composer パッケージ](https://getcomposer.org/) の形式で作成することが推奨されます。そうすれば、 エクステンションは、[Composer パッケージ](https://getcomposer.org/) の形式で作成することが推奨されます。
直前の項で説明したように、いっそう容易に他のユーザによってインストールされ、使用されることが出来ます。 そうすれば、直前の項で説明したように、いっそう容易に他のユーザによってインストールされ、使用されることが出来ます。
以下は、エクステンションを Composer のパッケージとして作成するために踏む基本的なステップです。 以下は、エクステンションを Composer のパッケージとして作成するために踏む基本的なステップです。
1. エクステンションのためのプロジェクトを作成して、[github.com](https://github.com) などの VCS レポジトリ上でホストする。 1. エクステンションのためのプロジェクトを作成して、[github.com](https://github.com) などの VCS レポジトリ上でホストします。
エクステンションに関する開発と保守の作業はこのレポジトリ上でなされなければならない。 エクステンションに関する開発と保守の作業はこのレポジトリ上でなされなければならない。
2. プロジェクトのルートディレクトリに、Composer によって要求される `composer.json` という名前のファイルを作成する。 2. プロジェクトのルートディレクトリに、Composer によって要求される `composer.json` という名前のファイルを作成します。
更なる詳細については、次の項を参照。 詳細については、次の項を参照してください。
3. エクステンションを [Packagist](https://packagist.org/) などの Composer レポジトリに登録する。そうすると、他のユーザが 3. エクステンションを [Packagist](https://packagist.org/) などの Composer レポジトリに登録します。
エクステンションを見つけて Composer を使ってインストールすることが出来るようになる。 そうすると、他のユーザがエクステンションを見つけて Composer を使ってインストールすることが出来るようになります。
### `composer.json` <a name="composer-json"></a> ### `composer.json` <a name="composer-json"></a>
全ての Composer パッケージは、ルートディレクトリに `composer.json` というファイルを持たなければなりません。このファイルは 全ての Composer パッケージは、ルートディレクトリに `composer.json` というファイルを持たなければなりません。
パッケージに関するメタデータを含むものです。このファイルに関する完全な仕様は [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup) このファイルはパッケージに関するメタデータを含むものです。
に記載されています。次の例は、`yiisoft/yii2-imagine` エクステンションのための `composer.json` ファイルを示すものです: このファイルに関する完全な仕様は [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup) に記載されています。
次の例は、`yiisoft/yii2-imagine` エクステンションのための `composer.json` ファイルを示すものです。
```json ```json
{ {
...@@ -159,8 +159,8 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ ...@@ -159,8 +159,8 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ
#### パッケージ名 <a name="package-name"></a> #### パッケージ名 <a name="package-name"></a>
全ての Composer パッケージは、他の全てパッケージに対して唯一のものとして特定できるような名前を持たなければなりません。 全ての Composer パッケージは、他の全てパッケージに対して唯一のものとして特定できるような名前を持たなければなりません。
パッケージ名の形式は `vendorName/projectName` です。例えば、`yiisoft/yii2-imagine` というパッケージ名の中では、 パッケージ名の形式は `vendorName/projectName` です。
ベンダー名とプロジェクト名は、それぞれ、`yiisoft``yii2-imagine` です。 例えば、`yiisoft/yii2-imagine` というパッケージ名の中では、ベンダー名とプロジェクト名は、それぞれ、`yiisoft``yii2-imagine` です。
ベンダー名として `yiisoft` を使ってはいけません。これは Yii のコアコードに使うために予約されています。 ベンダー名として `yiisoft` を使ってはいけません。これは Yii のコアコードに使うために予約されています。
...@@ -170,27 +170,24 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ ...@@ -170,27 +170,24 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ
#### パッケージタイプ <a name="package-type"></a> #### パッケージタイプ <a name="package-type"></a>
パッケージがインストールされたときに Yii のエクステンションとして認識されるように、エクステンションのパッケージタイプを パッケージがインストールされたときに Yii のエクステンションとして認識されるように、エクステンションのパッケージタイプを `yii2-extension` と指定することは重要なことです。
`yii2-extension` と指定することは重要なことです。
ユーザが `composer install` を走らせてエクステンションをインストールすると、`vendor/yiisoft/extensions.php` というファイルが ユーザが `composer install` を走らせてエクステンションをインストールすると、`vendor/yiisoft/extensions.php` というファイルが自動的に更新されて、新しいエクステンションに関する情報を含むようになります。
自動的に更新されて、新しいエクステンションに関する情報を含むようになります。このファイルから、Yii のアプリケーションは このファイルから、Yii のアプリケーションはどんなエクステンションがインストールされているかを知ることが出来ます
どんなエクステンションがインストールされているかを知ることが出来ます (その情報には、[[yii\base\Application::extensions]] (その情報には、[[yii\base\Application::extensions]] を通じてアクセス出来ます)。
を通じてアクセス出来ます)。
#### 依存パッケージ <a name="dependencies"></a> #### 依存パッケージ <a name="dependencies"></a>
あなたのエクステンションは Yii に依存します (当然ですね)。ですから、`composer.json``require` エントリのリストに あなたのエクステンションは Yii に依存します (当然ですね)。
れ (`yiisoft/yii2`) を挙げなければなりません。あなたのエクステンションがその他のエクステンションやサードパーティの すから、`composer.json``require` エントリのリストにそれ (`yiisoft/yii2`) を挙げなければなりません。
ライブラリに依存する場合は、それらもリストに挙げなければなりません。それぞれの依存パッケージについて、適切なバージョン制約 あなたのエクステンションがその他のエクステンションやサードパーティのライブラリに依存する場合は、それらもリストに挙げなければなりません。
(例えば `1.*``@stable`) を指定することも忘れてはなりません。あなたのエクステンションを安定バージョンとしてリリースする場合は それぞれの依存パッケージについて、適切なバージョン制約 (例えば `1.*``@stable`) を指定することも忘れてはなりません。
定した依存パッケージを使ってください。 あなたのエクステンションを安定バージョンとしてリリースする場合は、安定した依存パッケージを使ってください。
たいていの JavaScript/CSS パッケージは、Composer ではなく、[Bower](http://bower.io/) および/または [NPM](https://www.npmjs.org/) たいていの JavaScript/CSS パッケージは、Composer ではなく、[Bower](http://bower.io/) および/または [NPM](https://www.npmjs.org/) を使って管理されています。
を使って管理されています。Yii は [Composer アセットプラグイン](https://github.com/francoispluchino/composer-asset-plugin) Yii は [Composer アセットプラグイン](https://github.com/francoispluchino/composer-asset-plugin) を使って、この種のパッケージを Composer によって管理することを可能にしています。
を使って、この種のパッケージを Composer によって管理することを可能にしています。あなたのエクステンションが Bower パッケージに あなたのエクステンションが Bower パッケージに依存している場合でも、次のように、`composer.json` に依存パッケージをリストアップすることが簡単に出来ます。
依存している場合でも、次のように、`composer.json` に依存パッケージをリストアップすることが簡単に出来ます:
```json ```json
{ {
...@@ -201,19 +198,18 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ ...@@ -201,19 +198,18 @@ Yii 縺ォ繧医▲縺ヲ謠蝉セ帙&繧後※縺k繧ッ繝ゥ繧ケ繧ェ繝シ繝医Ο繝シ繝繧剃スソ縺」縺ヲ繧ィ
} }
``` ```
上記のコードは、エクステンションが `jquery` Bower パッケージに依存することを述べています。一般に、`composer.json` の中 上記のコードは、エクステンションが `jquery` Bower パッケージに依存することを述べています。
Bower パッケージを指すためには `bower-asset/PackageName` を使うことが出来ます。そして、NPM パッケージを指すためには 一般に、`composer.json` の中でBower パッケージを指すためには `bower-asset/PackageName` を使うことが出来ます。
`npm-asset/PackageName` を使うことが出来ます。Composer が Bower または NPM のパッケージをインストールする場合は、既定では、 そして、NPM パッケージを指すためには `npm-asset/PackageName` を使うことが出来ます。
それぞれ、`@vendor/bower/PackageName` および `@vendor/npm/Packages` というディレクトリの下にパッケージの内容がインストールされます。 Composer が Bower または NPM のパッケージをインストールする場合は、既定では、それぞれ、`@vendor/bower/PackageName` および `@vendor/npm/Packages` というディレクトリの下にパッケージの内容がインストールされます。
この二つのディレクトリは、`@bower/PackageName` および `@npm/PackageName` という短いエイリアスを使って参照することも可能です。 この二つのディレクトリは、`@bower/PackageName` および `@npm/PackageName` という短いエイリアスを使って参照することも可能です。
アセット管理に関する更なる詳細については、[アセット](structure-assets.md#bower-npm-assets) の節を参照してください。 アセット管理に関する詳細についは、[アセット](structure-assets.md#bower-npm-assets) の節を参照してください。
#### クラスのオートロード <a name="class-autoloading"></a> #### クラスのオートロード <a name="class-autoloading"></a>
エクステンションのクラスが Yii のクラスオートローダまたは Composer のクラスオートローダによってオートロードされるように、 エクステンションのクラスが Yii のクラスオートローダまたは Composer のクラスオートローダによってオートロードされるように、下記に示すように、`composer.json` ファイルの `autoload` エントリを指定しなければなりません。
下記に示すように、`composer.json` ファイルの `autoload` エントリを指定しなければなりません:
```json ```json
{ {
...@@ -229,8 +225,7 @@ Bower 繝代ャ繧ア繝シ繧ク繧呈欠縺吶◆繧√↓縺ッ `bower-asset/PackageName` 繧剃スソ縺 ...@@ -229,8 +225,7 @@ Bower 繝代ャ繧ア繝シ繧ク繧呈欠縺吶◆繧√↓縺ッ `bower-asset/PackageName` 繧剃スソ縺
一つまたは複数のルート名前空間と、それに対応するファイルパスをリストに挙げることが出来ます。 一つまたは複数のルート名前空間と、それに対応するファイルパスをリストに挙げることが出来ます。
エクステンションがアプリケーションにインストールされると、Yii は列挙されたルート名前空間の一つ一つに対して、 エクステンションがアプリケーションにインストールされると、Yii は列挙されたルート名前空間の一つ一つに対して、名前空間に対応するディレクトリを指す [エイリアス](concept-aliases.md#extension-aliases) を作成します。
名前空間に対応するディレクトリを指す [エイリアス](concept-aliases.md#extension-aliases) を作成します。
例えば、上記の `autoload` の宣言は、`@yii/imagine` という名前のエイリアスに対応することになります。 例えば、上記の `autoload` の宣言は、`@yii/imagine` という名前のエイリアスに対応することになります。
...@@ -242,23 +237,21 @@ Bower 繝代ャ繧ア繝シ繧ク繧呈欠縺吶◆繧√↓縺ッ `bower-asset/PackageName` 繧剃スソ縺 ...@@ -242,23 +237,21 @@ Bower 繝代ャ繧ア繝シ繧ク繧呈欠縺吶◆繧√↓縺ッ `bower-asset/PackageName` 繧剃スソ縺
#### 名前空間 <a name="namespaces"></a> #### 名前空間 <a name="namespaces"></a>
名前の衝突を避けて、エクステンションの中のクラスをオートロード可能にするために、名前空間を使うべきであり、 名前の衝突を避けて、エクステンションの中のクラスをオートロード可能にするために、名前空間を使うべきであり、エクステンションの中のクラスに
エクステンションの中のクラスに [PSR-4 標準](http://www.php-fig.org/psr/psr-4/) または [PSR-4 標準](http://www.php-fig.org/psr/psr-4/) または [PSR-0 標準](http://www.php-fig.org/psr/psr-0/) に従った名前を付けるべきです。
[PSR-0 標準](http://www.php-fig.org/psr/psr-0/) に従った名前を付けるべきです。
あなたのクラスの名前空間は `vendorName\extensionName` で始まるべきです。ここで `extensionName` は、`yii2-` あなたのクラスの名前空間は `vendorName\extensionName` で始まるべきです。
いう前置辞を含むべきでないことを除けば、パッケージ名におけるプロジェクト名と同じものです。例えば、`yiisoft/yii2-imagine` こで `extensionName` は、`yii2-` という接頭辞を含むべきでないことを除けば、パッケージ名におけるプロジェクト名と同じものです。
エクステンションでは、`yii\imagine` をエクステンションのクラスの名前空間として使っています。 例えば、`yiisoft/yii2-imagine` エクステンションでは、`yii\imagine` をエクステンションのクラスの名前空間として使っています。
`yii``yii2` または `yiisoft` をベンダー名として使ってはいけません。これらの名前は、Yii のコアコードに使うために予約されています。 `yii``yii2` または `yiisoft` をベンダー名として使ってはいけません。これらの名前は、Yii のコアコードに使うために予約されています。
#### ブートストラップクラス <a name="bootstrapping-classes"></a> #### ブートストラップクラス <a name="bootstrapping-classes"></a>
場合によっては、アプリケーションが [ブートストラップ](runtime-bootstrapping.md) の段階にある間に、エクステンションに何らかの 場合によっては、アプリケーションが [ブートストラップ](runtime-bootstrapping.md) の段階にある間に、エクステンションに何らかのコードを実行させたい場合があるでしょう。
コードを実行させたい場合があるでしょう。例えば、エクステンションをアプリケーションの `beginRequest` イベントに反応させて、 例えば、エクステンションをアプリケーションの `beginRequest` イベントに反応させて、何らかの環境設定を調整したいことがあります。
何らかの環境設定を調整したいことがあります。エクステンションのユーザに対して、エクステンションの中にあるイベントハンドラを エクステンションのユーザに対して、エクステンションの中にあるイベントハンドラを `beginRequest` イベントに明示的にアタッチするように指示することも出来ますが、より良い方法は、それを自動的に行うことです。
`beginRequest` イベントに明示的にアタッチするように指示することも出来ますが、より良い方法は、それを自動的に行うことです。
この目的を達するためには、[[yii\base\BootstrapInterface]] を実装する、いわゆる *ブートストラップクラス* を作成します。 この目的を達するためには、[[yii\base\BootstrapInterface]] を実装する、いわゆる *ブートストラップクラス* を作成します。
例えば、 例えば、
...@@ -292,18 +285,17 @@ class MyBootstrapClass implements BootstrapInterface ...@@ -292,18 +285,17 @@ class MyBootstrapClass implements BootstrapInterface
} }
``` ```
このエクステンションがアプリケーションにインストールされると、すべてのリクエストのブートストラップの過程において、毎回、 このエクステンションがアプリケーションにインストールされると、すべてのリクエストのブートストラップの過程において、毎回、Yii
Yii が自動的にブートストラップクラスのインスタンスを作成し、その [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] が自動的にブートストラップクラスのインスタンスを作成し、その [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] メソッドを呼びます。
メソッドを呼びます。
#### データベースを扱う <a name="working-with-databases"></a> #### データベースを扱う <a name="working-with-databases"></a>
あなたのエクステンションはデータベースにアクセスする必要があるかも知れません。エクステンションを使うアプリケーションが あなたのエクステンションはデータベースにアクセスする必要があるかも知れません。
常に `Yii::$db` を DB 接続として使用すると仮定してはいけません。その代りに、DB アクセスを必要とするクラスのために `db` エクステンションを使うアプリケーションが常に `Yii::$db` を DB 接続として使用すると仮定してはいけません。
プロパティを宣言すべきです。このプロパティによって、エクステンションのユーザは、エクステンションにどの DB 接続を使わせるかを その代りに、DB アクセスを必要とするクラスのために `db` プロパティを宣言すべきです。
カスタマイズすることが出来るようになります。その一例として、[[yii\caching\DbCache]] クラスを参照して、それがどのように このプロパティによって、エクステンションのユーザは、エクステンションにどの DB 接続を使わせるかをカスタマイズすることが出来るようになります。
`db` プロパティを宣言して使っているかを見ることが出来ます。 その一例として、[[yii\caching\DbCache]] クラスを参照して、それがどのように `db` プロパティを宣言して使っているかを見ることが出来ます。
あなたのエクステンションが特定の DB テーブルを作成したり、DB スキーマを変更したりする必要がある場合は、次のようにするべきです。 あなたのエクステンションが特定の DB テーブルを作成したり、DB スキーマを変更したりする必要がある場合は、次のようにするべきです。
...@@ -314,78 +306,69 @@ Yii 縺瑚蜍慕噪縺ォ繝悶繝医せ繝医Λ繝繧ッ繝ゥ繧ケ縺ョ繧、繝ウ繧ケ繧ソ繝ウ繧ケ繧剃ス懈 ...@@ -314,78 +306,69 @@ Yii 縺瑚蜍慕噪縺ォ繝悶繝医せ繝医Λ繝繧ッ繝ゥ繧ケ縺ョ繧、繝ウ繧ケ繧ソ繝ウ繧ケ繧剃ス懈
#### アセットを使う <a name="using-assets"></a> #### アセットを使う <a name="using-assets"></a>
あなたのエクステンションがウィジェットかモジュールである場合は、動作するために何らかの [assets](structure-assets.md) あなたのエクステンションがウィジェットかモジュールである場合は、動作するために何らかの [アセット](structure-assets.md) が必要である可能性が高いでしょう。
が必要である可能性が高いでしょう。例えば、モジュールは、画像、JavaScript、そして CSS を含むページをいくつか表示するでしょう。 えば、モジュールは、画像、JavaScript、そして CSS を含むページをいくつか表示するでしょう。
エクステンションのファイルは、全て、アプリケーションにインストールされるときに、ウェブからアクセス出来ない同じディレクトリ エクステンションのファイルは、全て、アプリケーションにインストールされるときに、ウェブからアクセス出来ない同じディレクトリの下に配置されます。
下に配置されます。そのため、次のどちらかの方法を使って、アセットファイルをウェブから直接アクセス出来るようにしなければなりません。 ため、次のどちらかの方法を使って、アセットファイルをウェブから直接アクセス出来るようにしなければなりません。
- アセットファイルをウェブからアクセス出来る特定のフォルダに手作業でコピーするように、エクステンションのユーザにお願いする。 - アセットファイルをウェブからアクセス出来る特定のフォルダに手作業でコピーするように、エクステンションのユーザにお願いする。
- [アセットバンドル](structure-assets.md) を宣言し、アセット発行メカニズムに頼って、アセットバンドルにリスとされているファイルを - [アセットバンドル](structure-assets.md) を宣言し、アセット発行メカニズムに頼って、アセットバンドルにリストされているファイルをウェブからアクセス出来るフォルダに自動的にコピーする。
ウェブからアクセス出来るフォルダに自動的にコピーする。
あなたのエクステンションが他の人々にとってより一層使いやすいものになるように、第二の方法をとることを推奨します。 あなたのエクステンションが他の人々にとってより一層使いやすいものになるように、第二の方法をとることを推奨します。
アセットの取り扱い一般に関する更なる詳細は [セット](structure-assets.md) の節を参照してください。 アセットの取り扱い一般に関する詳細は [アセット](structure-assets.md) の節を参照してください。
#### 国際化と地域化 <a name="i18n-l10n"></a> #### 国際化と地域化 <a name="i18n-l10n"></a>
あなたのエクステンションは、さまざまな言語をサポートするアプリケーションによって使われるかもしれません。従って、 あなたのエクステンションは、さまざまな言語をサポートするアプリケーションによって使われるかもしれません。
あなたのエクステンションがエンドユーザにコンテンツを表示するものである場合は、それを [国際化](tutorial-i18n.md) 従って、あなたのエクステンションがエンドユーザにコンテンツを表示するものである場合は、それを [国際化](tutorial-i18n.md) するように努めるべきです。
するように努めるべきです。具体的には、 具体的には、
- エクステンションがエンドユーザに向けたメッセージを表示する場合は、翻訳することが出来るようにメッセージを `Yii::t()` - エクステンションがエンドユーザに向けたメッセージを表示する場合は、翻訳することが出来るようにメッセージを `Yii::t()` で包むべきです。
で包むべきです。開発者に向けられたメッセージ (内部的な例外のメッセージなど) は翻訳される必要はありません。 開発者に向けられたメッセージ (内部的な例外のメッセージなど) は翻訳される必要はありません。
- エクステンションが数値や日付などを表示する場合は、[[yii\i18n\Formatter]] を適切な書式化の規則とともに使って書式設定すべきです。 - エクステンションが数値や日付などを表示する場合は、[[yii\i18n\Formatter]] を適切な書式化の規則とともに使って書式設定すべきです。
更なる詳細については、[国際化](tutorial-i18n.md) の節を参照してください。 細については、[国際化](tutorial-i18n.md) の節を参照してください。
#### テスト <a name="testing"></a> #### テスト <a name="testing"></a>
あなたは、あなたのエクステンションが他の人々に問題をもたらすことなく完璧に動作することを望むでしょう。この目的を達するためには、 あなたは、あなたのエクステンションが他の人々に問題をもたらすことなく完璧に動作することを望むでしょう。
なたのエクステンションを公開する前にテストすべきです。 の目的を達するためには、あなたのエクステンションを公開する前にテストすべきです。
手作業のテストに頼るのではなく、あなたのエクステンションのコードをカバーするさまざまなテストケースを作成することが推奨されます。 手作業のテストに頼るのではなく、あなたのエクステンションのコードをカバーするさまざまなテストケースを作成することが推奨されます。
あなたのエクステンションの新しいバージョンを公開する前には、毎回、単にそれらのテストケースを走らせれば、全てが良い状態にあることを あなたのエクステンションの新しいバージョンを公開する前には、毎回、単にそれらのテストケースを走らせれば、全てが良い状態にあることを確認することが出来ます。
確認することが出来ます。Yii はテストのサポートを提供しており、それよって、ユニットテスト、機能テスト、承認テストを書くことが Yii はテストのサポートを提供しており、それよって、ユニットテスト、機能テスト、承認テストを書くことが一層簡単に出来るようになっています。
一層簡単に出来るようになっています。更なる詳細については、[テスト](test-overview.md) の節を参照してください。 細については、[テスト](test-overview.md) の節を参照してください。
#### バージョン管理 <a name="versioning"></a> #### バージョン管理 <a name="versioning"></a>
エクステンションのリリースごとにバージョン番号 (例えば `1.0.1`) を付けるべきです。 エクステンションのリリースごとにバージョン番号 (例えば `1.0.1`) を付けるべきです。
どのようなバージョン番号を付けるべきかを決定するときは、[セマンティックバージョニング](http://semver.org) どのようなバージョン番号を付けるべきかを決定するときは、[セマンティックバージョニング](http://semver.org) の慣行に従うことを推奨します。
の慣行に従うことを推奨します。
#### リリース(公開) <a name="releasing"></a> #### リリース(公開) <a name="releasing"></a>
他の人々にあなたのエクステンションを知ってもらうためには、それをリリース(公開)する必要があります。 他の人々にあなたのエクステンションを知ってもらうためには、それをリリース(公開)する必要があります。
エクステンションをリリースするのが初めての場合は、[Packagist](https://packagist.org/) などの Composer レポジトリに エクステンションをリリースするのが初めての場合は、[Packagist](https://packagist.org/) などの Composer レポジトリにエクステンションを登録するべきです。
エクステンションを登録するべきです。その後は、あなたがしなければならない仕事は、エクステンションの VCS レポジトリでリリースタグ その後は、あなたがしなければならない仕事は、エクステンションの VCS レポジトリでリリースタグ (例えば `v1.0.1`) を作成することと、Composer レポジトリに新しいリリースについて通知するだけのことになります。
(例えば `v1.0.1`) を作成して Composer レポジトリに新しいリリースについて通知するだけのことになります。そして、 そうすれば、人々が新しいリリースを見出すことが出来るようになり、Composer レポジトリを通じてエクステンションをインストールしたりアップデートしたりするようになります。
人々が新しいリリースを見出すことが出来るようになり、Composer レポジトリを通じてエクステンションをインストールしたり
アップデートしたりするようになります。
エクステンションのリリースには、人々があなたのエクステンションについて知ったり、エクステンションを使ったりするのを助けるために、 エクステンションのリリースには、コードファイル以外に、人々があなたのエクステンションについて知ったり、エクステンションを使ったりするのを助けるために、下記のものを含めることを考慮すべきです。
コードファイル以外に下記のものを含めることを考慮すべきです。
* パッケージのルートディレクトリに readme ファイル: あなたのエクステンションが何をするものか、そして、 * パッケージのルートディレクトリに readme ファイル: あなたのエクステンションが何をするものか、そして、どのようにインストールして使うものかを説明するものです。
どのようにインストールして使うものかを説明するものです。[Markdown](http://daringfireball.net/projects/markdown/) [Markdown](http://daringfireball.net/projects/markdown/) 形式で書いて、`readme.md` という名前にすることを推奨します。
形式で書いて、`readme.md` という名前にすることを推奨します。
* パッケージのルートディレクトリに changelog ファイル: それぞれのリリースで何が変ったかを一覧表示するものです。 * パッケージのルートディレクトリに changelog ファイル: それぞれのリリースで何が変ったかを一覧表示するものです。
このファイルは Markdown 形式で書いて `changelog.md` と名付けることが出来ます。 このファイルは Markdown 形式で書いて `changelog.md` と名付けることが出来ます。
* パッケージのルートディレクトリに upgrade ファイル: エクステンションの古いリリースからのアップグレード方法について説明するものです。 * パッケージのルートディレクトリに upgrade ファイル: エクステンションの古いリリースからのアップグレード方法について説明するものです。
このファイルは Markdown 形式で書いて `upgrade.md` と名付けることが出来ます。 このファイルは Markdown 形式で書いて `upgrade.md` と名付けることが出来ます。
* チュートリアル、デモ、スクリーンショットなど: あなたのエクステンションが readme ファイルでは十分にカバーできないほど * チュートリアル、デモ、スクリーンショットなど: あなたのエクステンションが readme ファイルでは十分にカバーできないほど多くの機能を提供するものである場合は、これらが必要になります。
多くの機能を提供するものである場合は、これらが必要になります。
* API ドキュメント: あなたのコードは、他の人々が読んで理解することがより一層容易に出来るように、十分な解説を含むべきです。 * API ドキュメント: あなたのコードは、他の人々が読んで理解することがより一層容易に出来るように、十分な解説を含むべきです。
[Object のクラスファイル](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php) を参照すると、 [Object のクラスファイル](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php) を参照すると、コードに解説を加える方法を学ぶことが出来ます。
コードに解説を加える方法を学ぶことが出来ます。
> Info|情報: コードのコメントを Markdown 形式で書くことが出来ます。`yiisoft/yii2-apidoc` エクステンションは、 > Info|情報: コードのコメントを Markdown 形式で書くことが出来ます。`yiisoft/yii2-apidoc` エクステンションは、コードのコメントに基づいて綺麗な API ドキュメントを生成するツールを提供しています。
コードのコメントに基づいて綺麗な API ドキュメントを生成するツールを提供しています。
> Info|情報: これは要求ではありませんが、あなたのエクステンションも一定のコーディングスタイルを守るのが良いと思います。 > Info|情報: これは要求ではありませんが、あなたのエクステンションも一定のコーディングスタイルを守るのが良いと思います。
[コアフレームワークコードスタイル](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style) を参照してください。 [コアフレームワークコードスタイル](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style) を参照してください。
...@@ -394,8 +377,7 @@ Yii 縺瑚蜍慕噪縺ォ繝悶繝医せ繝医Λ繝繧ッ繝ゥ繧ケ縺ョ繧、繝ウ繧ケ繧ソ繝ウ繧ケ繧剃ス懈 ...@@ -394,8 +377,7 @@ Yii 縺瑚蜍慕噪縺ォ繝悶繝医せ繝医Λ繝繧ッ繝ゥ繧ケ縺ョ繧、繝ウ繧ケ繧ソ繝ウ繧ケ繧剃ス懈
## コアエクステンション <a name="core-extensions"></a> ## コアエクステンション <a name="core-extensions"></a>
Yii は下記のコアエクステンションを提供しています。これらは Yii 開発チームによって開発され保守されているものです。 Yii は下記のコアエクステンションを提供しています。これらは Yii 開発チームによって開発され保守されているものです。
全て [Packagist](https://packagist.org/) に登録され、[エクステンションを使う](#using-extensions) の項で説明したように、 全て [Packagist](https://packagist.org/) に登録され、[エクステンションを使う](#using-extensions) の項で説明したように、簡単にインストールすることが出来ます。
簡単にインストールすることが出来ます。
- [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc): - [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc):
拡張可能で高性能な API ドキュメント生成機能を提供します。コアフレームワークの API ドキュメントを生成するためにも使われています。 拡張可能で高性能な API ドキュメント生成機能を提供します。コアフレームワークの API ドキュメントを生成するためにも使われています。
...@@ -406,30 +388,31 @@ Yii 縺ッ荳玖ィ倥繧ウ繧「繧ィ繧ッ繧ケ繝Φ繧キ繝ァ繝ウ繧呈署萓帙@縺ヲ縺∪縺吶ゅ%繧後 ...@@ -406,30 +388,31 @@ Yii 縺ッ荳玖ィ倥繧ウ繧「繧ィ繧ッ繧ケ繝Φ繧キ繝ァ繝ウ繧呈署萓帙@縺ヲ縺∪縺吶ゅ%繧後
- [yiisoft/yii2-codeception](https://github.com/yiisoft/yii2-codeception): - [yiisoft/yii2-codeception](https://github.com/yiisoft/yii2-codeception):
[Codeception](http://codeception.com/) に基づくテストのサポートを提供します。 [Codeception](http://codeception.com/) に基づくテストのサポートを提供します。
- [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug): - [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug):
Yii アプリケーションのデバッグのサポートを提供します。このエクステンションが使われると、全てのページの末尾にデバッガツールバーが Yii アプリケーションのデバッグのサポートを提供します。
表示されます。このエクステンションは、より詳細なデバッグ情報を表示する一連のスタンドアロンページも提供します。 このエクステンションが使われると、全てのページの末尾にデバッガツールバーが表示されます。
このエクステンションは、より詳細なデバッグ情報を表示する一連のスタンドアロンページも提供します。
- [yiisoft/yii2-elasticsearch](https://github.com/yiisoft/yii2-elasticsearch): - [yiisoft/yii2-elasticsearch](https://github.com/yiisoft/yii2-elasticsearch):
[Elasticsearch](http://www.elasticsearch.org/) の使用に対するサポートを提供します。基本的なクエリ/サーチのサポートを [Elasticsearch](http://www.elasticsearch.org/) の使用に対するサポートを提供します。
含むだけでなく、Elasticsearch にアクティブレコードを保存することを可能にする [アクティブレコード](db-active-record.md) 基本的なクエリ/サーチのサポートを含むだけでなく、Elasticsearch にアクティブレコードを保存することを可能にする [アクティブレコード](db-active-record.md) パターンをも実装しています。
パターンをも実装しています。
- [yiisoft/yii2-faker](https://github.com/yiisoft/yii2-faker): - [yiisoft/yii2-faker](https://github.com/yiisoft/yii2-faker):
ダミーデータを作る [Faker](https://github.com/fzaninotto/Faker) を使うためのサポートを提供します。 ダミーデータを作る [Faker](https://github.com/fzaninotto/Faker) を使うためのサポートを提供します。
- [yiisoft/yii2-gii](https://github.com/yiisoft/yii2-gii): - [yiisoft/yii2-gii](https://github.com/yiisoft/yii2-gii):
拡張性が非常に高いウェブベースのコードジェネレータを提供します。これを使って、モデル、フォーム、モジュール、CRUD 拡張性が非常に高いウェブベースのコードジェネレータを提供します。これを使って、モデル、フォーム、モジュール、CRUD などを迅速に生成することが出来ます。
などを迅速に生成することが出来ます。
- [yiisoft/yii2-imagine](https://github.com/yiisoft/yii2-imagine): - [yiisoft/yii2-imagine](https://github.com/yiisoft/yii2-imagine):
[Imagine](http://imagine.readthedocs.org/) に基づいて、使われることの多い画像操作機能を提供します。 [Imagine](http://imagine.readthedocs.org/) に基づいて、使われることの多い画像操作機能を提供します。
- [yiisoft/yii2-jui](https://github.com/yiisoft/yii2-jui): - [yiisoft/yii2-jui](https://github.com/yiisoft/yii2-jui):
[JQuery UI](http://jqueryui.com/) のインタラクションとウィジェットをカプセル化した一連のウィジェットを提供します。 [JQuery UI](http://jqueryui.com/) のインタラクションとウィジェットをカプセル化した一連のウィジェットを提供します。
- [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb): - [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb):
[MongoDB](http://www.mongodb.org/) の使用に対するサポートを提供します。基本的なクエリ、アクティブレコード、マイグレーション、 [MongoDB](http://www.mongodb.org/) の使用に対するサポートを提供します。
キャッシュ、コード生成などの機能を含みます。 基本的なクエリ、アクティブレコード、マイグレーション、キャッシュ、コード生成などの機能を含みます。
- [yiisoft/yii2-redis](https://github.com/yiisoft/yii2-redis): - [yiisoft/yii2-redis](https://github.com/yiisoft/yii2-redis):
[redis](http://redis.io/) の使用に対するサポートを提供します。基本的なクエリ、アクティブレコード、キャッシュなどの機能を含みます。 [redis](http://redis.io/) の使用に対するサポートを提供します。
基本的なクエリ、アクティブレコード、キャッシュなどの機能を含みます。
- [yiisoft/yii2-smarty](https://github.com/yiisoft/yii2-smarty): - [yiisoft/yii2-smarty](https://github.com/yiisoft/yii2-smarty):
[Smarty](http://www.smarty.net/) に基づいたテンプレートエンジンを提供します。 [Smarty](http://www.smarty.net/) に基づいたテンプレートエンジンを提供します。
- [yiisoft/yii2-sphinx](https://github.com/yiisoft/yii2-sphinx): - [yiisoft/yii2-sphinx](https://github.com/yiisoft/yii2-sphinx):
[Sphinx](http://sphinxsearch.com) の使用に対するサポートを提供します。基本的なクエリ、アクティブレコード、コード生成などの機能を含みます。 [Sphinx](http://sphinxsearch.com) の使用に対するサポートを提供します。
基本的なクエリ、アクティブレコード、コード生成などの機能を含みます。
- [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer): - [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer):
[swiftmailer](http://swiftmailer.org/) に基づいたメール送信機能を提供します。 [swiftmailer](http://swiftmailer.org/) に基づいたメール送信機能を提供します。
- [yiisoft/yii2-twig](https://github.com/yiisoft/yii2-twig): - [yiisoft/yii2-twig](https://github.com/yiisoft/yii2-twig):
......
...@@ -5,16 +5,14 @@ ...@@ -5,16 +5,14 @@
例えば、アクセスコントロールフィルタはアクションの前に走って、アクションが特定のエンドユーザだけにアクセスを許可するものであることを保証します。 例えば、アクセスコントロールフィルタはアクションの前に走って、アクションが特定のエンドユーザだけにアクセスを許可するものであることを保証します。
また、コンテンツ圧縮フィルタはアクションの後に走って、レスポンスのコンテンツをエンドユーザに送出する前に圧縮します。 また、コンテンツ圧縮フィルタはアクションの後に走って、レスポンスのコンテンツをエンドユーザに送出する前に圧縮します。
フィルタは、前フィルタ (アクションの *前* に適用されるフィルタのロジック) および/または 後フィルタ (アクションの *後* フィルタは、前フィルタ (アクションの *前* に適用されるフィルタのロジック) および/または 後フィルタ (アクションの *後* に適用されるフィルタ) から構成されます。
に適用されるフィルタ) から構成されます。
## フィルタを使用する <a name="using-filters"></a> ## フィルタを使用する <a name="using-filters"></a>
フィルタは、本質的には特別な種類の [ビヘイビア](concept-behaviors.md) です。したがって、フィルタを使うことは フィルタは、本質的には特別な種類の [ビヘイビア](concept-behaviors.md) です。
[ビヘイビアを使う](concept-behaviors.md#attaching-behaviors) ことと同じです。下記のように、 したがって、フィルタを使うことは [ビヘイビアを使う](concept-behaviors.md#attaching-behaviors) ことと同じです。
[[yii\base\Controller::behaviors()|behaviors()]] メソッドをオーバーライドすることによって、コントローラの中で 下記のように、[[yii\base\Controller::behaviors()|behaviors()]] メソッドをオーバーライドすることによって、コントローラの中でフィルタを宣言することが出来ます。
フィルタを宣言することが出来ます:
```php ```php
public function behaviors() public function behaviors()
...@@ -33,19 +31,17 @@ public function behaviors() ...@@ -33,19 +31,17 @@ public function behaviors()
``` ```
既定では、コントローラクラスの中で宣言されたフィルタは、そのコントローラの *全て* のアクションに適用されます。 既定では、コントローラクラスの中で宣言されたフィルタは、そのコントローラの *全て* のアクションに適用されます。
しかし、[[yii\base\ActionFilter::only|only]] プロパティを構成することによって、フィルタがどのアクションに適用されるべきかを しかし、[[yii\base\ActionFilter::only|only]] プロパティを構成することによって、フィルタがどのアクションに適用されるべきかを明示的に指定することも出来ます。
明示的に指定することも出来ます。上記の例では、 `HttpCache` フィルタは、`index``view` のアクションに対してのみ適用されています。 上記の例では、 `HttpCache` フィルタは、`index``view` のアクションに対してのみ適用されています。
また、[[yii\base\ActionFilter::except|except]] プロパティを構成して、いくつかのアクションをフィルタされないように除外することも可能です。 また、[[yii\base\ActionFilter::except|except]] プロパティを構成して、いくつかのアクションをフィルタされないように除外することも可能です。
コントローラのほかに、[モジュール](structure-modules.md) または [アプリケーション](structure-applications.md) コントローラのほかに、[モジュール](structure-modules.md) または [アプリケーション](structure-applications.md) でもフィルタを宣言することが出来ます。
でもフィルタを宣言することが出来ます。 そのようにした場合、[[yii\base\ActionFilter::only|only]] と [[yii\base\ActionFilter::except|except]] のプロパティを上で説明したように構成しない限り、
そのようにした場合、[[yii\base\ActionFilter::only|only]] と [[yii\base\ActionFilter::except|except]] のプロパティを そのフィルタは、モジュールまたはアプリケーションに属する *全て* のコントローラアクションに適用されます。
上で説明したように構成しない限り、そのフィルタは、モジュールまたはアプリケーションに属する *全て* のコントローラアクションに適用されます。
> Note|注意: モジュールやアプリケーションでフィルタを宣言する場合、[[yii\base\ActionFilter::only|only]] と > Note|注意: モジュールやアプリケーションでフィルタを宣言する場合、[[yii\base\ActionFilter::only|only]] と [[yii\base\ActionFilter::except|except]]
[[yii\base\ActionFilter::except|except]] のプロパティでは、アクション ID ではなく、[ルート](structure-controllers.md#routes) のプロパティでは、アクション ID ではなく、[ルート](structure-controllers.md#routes) を使うべきです。
を使うべきです。なぜなら、モジュールやアプリケーションのスコープでは、アクション ID だけでは完全にアクションを指定することが なぜなら、モジュールやアプリケーションのスコープでは、アクション ID だけでは完全にアクションを指定することが出来ないからです。
出来ないからです。
一つのアクションに複数のフィルタが構成されている場合、フィルタは下記で説明されている規則に従って適用されます。 一つのアクションに複数のフィルタが構成されている場合、フィルタは下記で説明されている規則に従って適用されます。
...@@ -63,13 +59,13 @@ public function behaviors() ...@@ -63,13 +59,13 @@ public function behaviors()
## フィルタを作成する <a name="creating-filters"></a> ## フィルタを作成する <a name="creating-filters"></a>
新しいアクションフィルタを作成するためには、[[yii\base\ActionFilter]] を拡張して、 新しいアクションフィルタを作成するためには、[[yii\base\ActionFilter]] を拡張して、[[yii\base\ActionFilter::beforeAction()|beforeAction()]]
[[yii\base\ActionFilter::beforeAction()|beforeAction()]] および/または [[yii\base\ActionFilter::afterAction()|afterAction()]] および/または [[yii\base\ActionFilter::afterAction()|afterAction()]] メソッドをオーバーライドします。
メソッドをオーバーライドします。前者はアクションが走る前に実行され、後者は走った後に実行されます。 前者はアクションが走る前に実行され、後者は走った後に実行されます。
[[yii\base\ActionFilter::beforeAction()|beforeAction()]] の返り値が、アクションが実行されるべきか否かを決定します。 [[yii\base\ActionFilter::beforeAction()|beforeAction()]] の返り値が、アクションが実行されるべきか否かを決定します。
返り値が false である場合、このフィルタの後に続くフィルタはスキップされ、アクションは実行を中止されます。 返り値が false である場合、このフィルタの後に続くフィルタはスキップされ、アクションは実行を中止されます。
次の例は、アクションの実行時間をログに記録するフィルタを示すものです: 次の例は、アクションの実行時間をログに記録するフィルタを示すものです
```php ```php
namespace app\components; namespace app\components;
...@@ -99,14 +95,15 @@ class ActionTimeFilter extends ActionFilter ...@@ -99,14 +95,15 @@ class ActionTimeFilter extends ActionFilter
## コアのフィルタ <a name="core-filters"></a> ## コアのフィルタ <a name="core-filters"></a>
Yii はよく使われる一連のフィルタを提供しており、それらは、主として `yii\filters` 名前空間の下にあります。以下では、 Yii はよく使われる一連のフィルタを提供しており、それらは、主として `yii\filters` 名前空間の下にあります。
それらのフィルタを簡単に紹介します。 以下では、それらのフィルタを簡単に紹介します。
### [[yii\filters\AccessControl|AccessControl]] <a name="access-control"></a> ### [[yii\filters\AccessControl|AccessControl]] <a name="access-control"></a>
AccessControl は、一組の [[yii\filters\AccessControl::rules|規則]] に基づいて、シンプルなアクセスコントロールを提供するものです。 AccessControl は、一組の [[yii\filters\AccessControl::rules|規則]] に基づいて、シンプルなアクセスコントロールを提供するものです。
具体的に言うと、アクションが実行される前に、AccessControl はリストされた規則を調べて、現在のコンテキスト変数 (例えば、ユーザの IP アドレスや、ユーザのログイン状態など) に最初に合致するものを見つけます。 具体的に言うと、アクションが実行される前に、AccessControl はリストされた規則を調べて、現在のコンテキスト変数
(例えば、ユーザの IP アドレスや、ユーザのログイン状態など) に最初に合致するものを見つけます。
そして、合致した規則によって、リクエストされたアクションの実行を許可するか拒否するかを決定します。 そして、合致した規則によって、リクエストされたアクションの実行を許可するか拒否するかを決定します。
合致する規則がなかった場合は、アクセスは拒否されます。 合致する規則がなかった場合は、アクセスは拒否されます。
...@@ -135,7 +132,7 @@ public function behaviors() ...@@ -135,7 +132,7 @@ public function behaviors()
} }
``` ```
アクセスコントロール一般について、更なる詳細は [権限](security-authorization.md) の節を参照してください。 アクセスコントロール一般について詳細は [権限](security-authorization.md) の節を参照してください。
### 認証メソッドフィルタ <a name="auth-method-filters"></a> ### 認証メソッドフィルタ <a name="auth-method-filters"></a>
...@@ -145,8 +142,8 @@ public function behaviors() ...@@ -145,8 +142,8 @@ public function behaviors()
これらのフィルタクラスはすべて `yii\filters\auth` 名前空間の下にあります。 これらのフィルタクラスはすべて `yii\filters\auth` 名前空間の下にあります。
次の例は、[[yii\filters\auth\HttpBasicAuth]] の使い方を示すもので、HTTP Basic 認証に基づくアクセストークンを使ってユーザを認証しています。 次の例は、[[yii\filters\auth\HttpBasicAuth]] の使い方を示すもので、HTTP Basic 認証に基づくアクセストークンを使ってユーザを認証しています。
これを動作させるためには、あなたの [[yii\web\User::identityClass|ユーザアイデンティティクラス]] これを動作させるためには、あなたの [[yii\web\User::identityClass|ユーザアイデンティティクラス]]
[[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]] [[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]]
メソッドを実装していなければならないことに注意してください。 メソッドを実装していなければならないことに注意してください。
```php ```php
...@@ -162,18 +159,16 @@ public function behaviors() ...@@ -162,18 +159,16 @@ public function behaviors()
} }
``` ```
認証メソッドフィルタは RESTful API を実装するときに使われるのが通例です。詳細については、 認証メソッドフィルタは RESTful API を実装するときに使われるのが通例です。
RESTful の [認証](rest-authentication.md) の節を参照してください。 詳細については、RESTful の [認証](rest-authentication.md) の節を参照してください。
### [[yii\filters\ContentNegotiator|ContentNegotiator]] <a name="content-negotiator"></a> ### [[yii\filters\ContentNegotiator|ContentNegotiator]] <a name="content-negotiator"></a>
ContentNegotiator は、レスポンス形式のネゴシエーションとアプリケーション言語のネゴシエーションをサポートします。 ContentNegotiator は、レスポンス形式のネゴシエーションとアプリケーション言語のネゴシエーションをサポートします。
このフィルタは `GET` パラメータと `Accept` HTTP ヘッダを調べることによって、レスポンス形式 および/または このフィルタは `GET` パラメータと `Accept` HTTP ヘッダを調べることによって、レスポンス形式 および/または 言語を決定しようとします。
言語を決定しようとします。
次の例では、ContentNegotiator はレスポンス形式として JSON と XML をサポートし、(合衆国の)英語とドイツ語を 次の例では、ContentNegotiator はレスポンス形式として JSON と XML をサポートし、(合衆国の)英語とドイツ語を言語としてサポートするように構成されています。
言語としてサポートするように構成されています。
```php ```php
use yii\filters\ContentNegotiator; use yii\filters\ContentNegotiator;
...@@ -198,9 +193,9 @@ public function behaviors() ...@@ -198,9 +193,9 @@ public function behaviors()
``` ```
レスポンス形式と言語は [アプリケーションのライフサイクル](structure-applications.md#application-lifecycle) レスポンス形式と言語は [アプリケーションのライフサイクル](structure-applications.md#application-lifecycle)
のもっと早い段階で決定される必要があることがよくあります。このため、ContentNegotiator はフィルタの他に、 のもっと早い段階で決定される必要があることがよくあります。
[ブートストラップコンポーネント](structure-applications.md#bootstrap) としても使うことができるように設計されています。 このため、ContentNegotiator はフィルタの他に、[ブートストラップコンポーネント](structure-applications.md#bootstrap) としても使うことができるように設計されています。
例えば、次のように、ContentNegotiator を [アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) の中で構成することが出来ます。 例えば、次のように、ContentNegotiator を [アプリケーションの構成情報](structure-applications.md#application-configurations) の中で構成することが出来ます。
```php ```php
use yii\filters\ContentNegotiator; use yii\filters\ContentNegotiator;
...@@ -250,15 +245,14 @@ public function behaviors() ...@@ -250,15 +245,14 @@ public function behaviors()
} }
``` ```
HttpCache に関する更なる詳細は [HTTP キャッシュ](caching-http.md) の節を参照してください。 HttpCache に関する詳細は [HTTP キャッシュ](caching-http.md) の節を参照してください。
### [[yii\filters\PageCache|PageCache]] <a name="page-cache"></a> ### [[yii\filters\PageCache|PageCache]] <a name="page-cache"></a>
PageCache はサーバサイドにおけるページ全体のキャッシュを実装するものです。次の例では、PageCache が PageCache はサーバサイドにおけるページ全体のキャッシュを実装するものです。
`index` アクションに適用されて、最大 60 秒間、または、`post` テーブルのエントリ数が変化するまでの間、 次の例では、PageCache が `index` アクションに適用されて、最大 60 秒間、または、`post` テーブルのエントリ数が変化するまでの間、ページ全体をキャッシュしています。
ページ全体をキャッシュしています。さらに、このページキャッシュは、選択されたアプリケーションの言語に従って、 さらに、このページキャッシュは、選択されたアプリケーションの言語に従って、違うバージョンのページを保存するようにしています。
違うバージョンのページを保存するようにしています。
```php ```php
use yii\filters\PageCache; use yii\filters\PageCache;
...@@ -283,7 +277,7 @@ public function behaviors() ...@@ -283,7 +277,7 @@ public function behaviors()
} }
``` ```
PageCache の使用に関する更なる詳細は [ページキャッシュ](caching-page.md) の節を参照してください。 PageCache の使用に関する詳細は [ページキャッシュ](caching-page.md) の節を参照してください。
### [[yii\filters\RateLimiter|RateLimiter]] <a name="rate-limiter"></a> ### [[yii\filters\RateLimiter|RateLimiter]] <a name="rate-limiter"></a>
...@@ -296,8 +290,8 @@ RateLimiter は [リーキーバケットアルゴリズム](http://ja.wikipedia ...@@ -296,8 +290,8 @@ RateLimiter は [リーキーバケットアルゴリズム](http://ja.wikipedia
### [[yii\filters\VerbFilter|VerbFilter]] <a name="verb-filter"></a> ### [[yii\filters\VerbFilter|VerbFilter]] <a name="verb-filter"></a>
VerbFilter は、HTTP リクエストメソッドがリクエストされたアクションによって許可されているかどうかをチェックするものです。 VerbFilter は、HTTP リクエストメソッドがリクエストされたアクションによって許可されているかどうかをチェックするものです。
許可されていない場合は、HTTP 405 例外を投げます。次の例では、VerbFilter が宣言されて、 許可されていない場合は、HTTP 405 例外を投げます。
CRUD アクションに対して許可されるメソッドの典型的なセットを規定しています。 次の例では、VerbFilter が宣言されて、CRUD アクションに対して許可されるメソッドの典型的なセットを規定しています。
```php ```php
use yii\filters\VerbFilter; use yii\filters\VerbFilter;
...@@ -321,12 +315,10 @@ public function behaviors() ...@@ -321,12 +315,10 @@ public function behaviors()
### [[yii\filters\Cors|Cors]] <a name="cors"></a> ### [[yii\filters\Cors|Cors]] <a name="cors"></a>
クロスオリジンリソース共有 [CORS](https://developer.mozilla.org/ja/docs/HTTP_access_control) とは、 クロスオリジンリソース共有 [CORS](https://developer.mozilla.org/ja/docs/HTTP_access_control) とは、ウェブページにおいて、さまざまなリソース
ウェブページにおいて、さまざまなリソース (例えば、フォントや JavaScript など) を、 (例えば、フォントや JavaScript など) を、それを生成するドメイン以外のドメインからリクエストすることを可能にするメカニズムです。
それを生成するドメイン以外のドメインからリクエストすることを可能にするメカニズムです。
特に言えば、JavaScript の AJAX 呼出しが使用することが出来る XMLHttpRequest メカニズムです。 特に言えば、JavaScript の AJAX 呼出しが使用することが出来る XMLHttpRequest メカニズムです。
このような「クロスドメイン」のリクエストは、このメカニズムに拠らなければ、 このような「クロスドメイン」のリクエストは、このメカニズムに拠らなければ、同一生成元のセキュリティポリシーによって、ウェブブラウザから禁止されるはずのものです。
同一生成元のセキュリティポリシーによって、ウェブブラウザから禁止されるはずのものです。
CORS は、ブラウザとサーバが交信して、クロスドメインのリクエストを許可するか否かを決定する方法を定義するものです。 CORS は、ブラウザとサーバが交信して、クロスドメインのリクエストを許可するか否かを決定する方法を定義するものです。
[[yii\filters\Cors|Cors フィルタ]] は、CORS ヘッダが常に送信されることを保証するために、Authentication / Authorization のフィルタよりも前に定義されなければなりません。 [[yii\filters\Cors|Cors フィルタ]] は、CORS ヘッダが常に送信されることを保証するために、Authentication / Authorization のフィルタよりも前に定義されなければなりません。
...@@ -347,14 +339,17 @@ public function behaviors() ...@@ -347,14 +339,17 @@ public function behaviors()
Cors のフィルタリングは `cors` プロパティを使ってチューニングすることが出来ます。 Cors のフィルタリングは `cors` プロパティを使ってチューニングすることが出来ます。
* `cors['Origin']`: 許可される生成元を定義するのに使われる配列。`['*']` (すべて) または `['http://www.myserver.net'、'http://www.myotherserver.com']` などが設定可能。デフォルトは `['*']` * `cors['Origin']`: 許可される生成元を定義するのに使われる配列。
* `cors['Access-Control-Request-Method']`: 許可されるメソッドの配列。たとえば、`['GET', 'OPTIONS', 'HEAD']`。デフォルトは `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']` `['*']` (すべて) または `['http://www.myserver.net'、'http://www.myotherserver.com']` などが設定可能。デフォルトは `['*']`
* `cors['Access-Control-Request-Headers']`: 許可されるヘッダの配列。全てのヘッダを意味する `['*']` または特定のヘッダを示す `['X-Request-With']` が設定可能。デフォルトは `['*']` * `cors['Access-Control-Request-Method']`: 許可されるメソッドの配列。
たとえば、`['GET', 'OPTIONS', 'HEAD']`。デフォルトは `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']`
* `cors['Access-Control-Request-Headers']`: 許可されるヘッダの配列。
全てのヘッダを意味する `['*']` または特定のヘッダを示す `['X-Request-With']` が設定可能。デフォルトは `['*']`
* `cors['Access-Control-Allow-Credentials']`: 現在のリクエストをクレデンシャルを使ってすることが出来るかどうかを定義。 * `cors['Access-Control-Allow-Credentials']`: 現在のリクエストをクレデンシャルを使ってすることが出来るかどうかを定義。
`true``false` または `null` (設定なし) が設定可能。デフォルトは `null` `true``false` または `null` (設定なし) が設定可能。デフォルトは `null`
* `cors['Access-Control-Max-Age']`: プリフライトリクエストの寿命を定義。デフォルトは `86400` * `cors['Access-Control-Max-Age']`: プリフライトリクエストの寿命を定義。デフォルトは `86400`
次の例は、生成元 `http://www.myserver.net` に対する `GET``HEAD` および `OPTIONS` のメソッドによる CORS を許可するものです: 次の例は、生成元 `http://www.myserver.net` に対する `GET``HEAD` および `OPTIONS` のメソッドによる CORS を許可するものです
```php ```php
use yii\filters\Cors; use yii\filters\Cors;
...@@ -375,7 +370,7 @@ public function behaviors() ...@@ -375,7 +370,7 @@ public function behaviors()
``` ```
デフォルトのパラメータをアクション単位でオーバーライドして CORS ヘッダをチューニングすることも可能です。 デフォルトのパラメータをアクション単位でオーバーライドして CORS ヘッダをチューニングすることも可能です。
例えば、`login` アクションに `Access-Control-Allow-Credentials` を追加することは、次のようにすれば出来ます: 例えば、`login` アクションに `Access-Control-Allow-Credentials` を追加することは、次のようにすれば出来ます
```php ```php
use yii\filters\Cors; use yii\filters\Cors;
......
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
モデルクラスは、[[yii\base\Model]] またはその子クラスを拡張することによって作成することが出来ます。 モデルクラスは、[[yii\base\Model]] またはその子クラスを拡張することによって作成することが出来ます。
基底クラス [[yii\base\Model]] は数多くの有用な機能をサポートしています。 基底クラス [[yii\base\Model]] は数多くの有用な機能をサポートしています。
* [属性](#attributes): 業務のデータを表現し、通常のオブジェクトプロパティや配列要素のようにアクセス出来る。 * [属性](#attributes): 業務のデータを表現する。通常のオブジェクトプロパティや配列要素のようにしてアクセス出来る。
* [属性のラベル](#attribute-labels): 属性の表示ラベルを規定する。 * [属性のラベル](#attribute-labels): 属性の表示ラベルを規定する。
* [一括代入](#massive-assignment): 一回のステップで複数の属性にデータを投入することをサポートしている。 * [一括代入](#massive-assignment): 一回のステップで複数の属性にデータを投入することをサポートしている。
* [検証規則](#validation-rules): 宣言された検証規則に基いて入力されたデータを確認する。 * [検証規則](#validation-rules): 宣言された検証規則に基いて入力されたデータを確認する。
...@@ -25,7 +25,7 @@ ...@@ -25,7 +25,7 @@
モデルは業務のデータを *属性* の形式で表現します。 モデルは業務のデータを *属性* の形式で表現します。
全ての属性はそれぞれパブリックにアクセス可能なモデルのプロパティと同様なものです。 全ての属性はそれぞれパブリックにアクセス可能なモデルのプロパティと同様なものです。
メソッド [[yii\base\Model::attributes()]] が、モデルがどのような属性を持つかを規定します。 [[yii\base\Model::attributes()]] メソッドが、モデルがどのような属性を持つかを規定します。
属性に対しては、通常のオブジェクトプロパティにアクセスするのと同じようにして、アクセスすることが出来ます。 属性に対しては、通常のオブジェクトプロパティにアクセスするのと同じようにして、アクセスすることが出来ます。
...@@ -57,7 +57,7 @@ foreach ($model as $name => $value) { ...@@ -57,7 +57,7 @@ foreach ($model as $name => $value) {
### 属性を定義する<a name="defining-attributes"></a> ### 属性を定義する<a name="defining-attributes"></a>
あなたのモデルが [[yii\base\Model]] を直接に拡張するものである場合、既定によって、全ての *static でない public な* メンバ変数は属性となります。 あなたのモデルが [[yii\base\Model]] を直接に拡張するものである場合、既定によって、全ての *static でない public な* メンバ変数は属性となります。
例えば、次に示す `ContactForm` モデルは4つの属性を持ちます: すなわち、`name``email``subject`、そして、`body`す。 例えば、次に示す `ContactForm` モデルは4つの属性、すなわち、`name``email``subject`、そして、`body` を持ちます。
この `ContactForm` モデルは、HTML フォームから受け取る入力データを表現するために使われます。 この `ContactForm` モデルは、HTML フォームから受け取る入力データを表現するために使われます。
```php ```php
...@@ -77,9 +77,9 @@ class ContactForm extends Model ...@@ -77,9 +77,9 @@ class ContactForm extends Model
[[yii\base\Model::attributes()]] をオーバーライドして、属性を異なる方法で定義することが出来ます。 [[yii\base\Model::attributes()]] をオーバーライドして、属性を異なる方法で定義することが出来ます。
このメソッドはモデルの中の属性の名前を返さなくてはなりません。 このメソッドはモデルの中の属性の名前を返さなくてはなりません。
例えば、[[yii\db\ActiveRecord]] はそのようにして、関連付けられたデータベーステーブルのコラム名を属性の名前として返しています。 例えば、[[yii\db\ActiveRecord]] は、関連付けられたデータベーステーブルのコラム名を属性の名前として返すことによって、属性を定義しています。
これと同時に `__get()``__set()` などのマジックメソッドをオーバーライドして これと同時に、定義された属性に対して通常のオブジェクトプロパティと同じようにアクセスすることが出来るように
属性が通常のオブジェクトプロパティと同じようにアクセス出来るようにする必要があるかもしれないことに注意してください。 `__get()``__set()` などのマジックメソッドをオーバーライドする必要があるかもしれないことに注意してください。
### 属性のラベル <a name="attribute-labels"></a> ### 属性のラベル <a name="attribute-labels"></a>
...@@ -101,8 +101,7 @@ echo $model->getAttributeLabel('name'); ...@@ -101,8 +101,7 @@ echo $model->getAttributeLabel('name');
このメソッドは、キャメルケースの変数名を複数の単語に分割し、各単語の最初の文字を大文字にします。 このメソッドは、キャメルケースの変数名を複数の単語に分割し、各単語の最初の文字を大文字にします。
例えば、`username``Username` となり、`firstName``First Name` となります。 例えば、`username``Username` となり、`firstName``First Name` となります。
自動的に生成されるラベルを使用したくない場合は、[[yii\base\Model::attributeLabels()]] をオーバーライドして、 自動的に生成されるラベルを使用したくない場合は、[[yii\base\Model::attributeLabels()]] をオーバーライドして、属性のラベルを明示的に宣言することが出来ます。例えば、
属性のラベルを明示的に宣言することが出来ます。例えば、
```php ```php
namespace app\models; namespace app\models;
...@@ -129,7 +128,7 @@ class ContactForm extends Model ...@@ -129,7 +128,7 @@ class ContactForm extends Model
``` ```
複数の言語をサポートするアプリケーションでは、属性のラベルを翻訳したいと思うでしょう。 複数の言語をサポートするアプリケーションでは、属性のラベルを翻訳したいと思うでしょう。
これも、以下のように、[[yii\base\Model::attributeLabels()|attributeLabels()]] の中で行うことが出来ます: これも、以下のように、[[yii\base\Model::attributeLabels()|attributeLabels()]] の中で行うことが出来ます
```php ```php
public function attributeLabels() public function attributeLabels()
...@@ -147,8 +146,7 @@ public function attributeLabels() ...@@ -147,8 +146,7 @@ public function attributeLabels()
[シナリオ](#scenarios) に基づいて、同じ属性に対して違うラベルを返すことことが出来ます。 [シナリオ](#scenarios) に基づいて、同じ属性に対して違うラベルを返すことことが出来ます。
> Info|情報: 厳密に言えば、属性のラベルは [ビュー](structure-views.md) の一部を成すものです。 > Info|情報: 厳密に言えば、属性のラベルは [ビュー](structure-views.md) の一部を成すものです。
しかし、たいていの場合、モデルの中でラベルを宣言する方が便利が良く、 しかし、たいていの場合、モデルの中でラベルを宣言する方が便利が良く、結果としてクリーンで再利用可能なコードになります。
結果としてクリーンで再利用可能なコードになります。
## シナリオ<a name="scenarios"></a> ## シナリオ<a name="scenarios"></a>
...@@ -160,19 +158,19 @@ public function attributeLabels() ...@@ -160,19 +158,19 @@ public function attributeLabels()
モデルは [[yii\base\Model::scenario]] プロパティを使って、自身が使われているシナリオを追跡します。 モデルは [[yii\base\Model::scenario]] プロパティを使って、自身が使われているシナリオを追跡します。
既定では、モデルは `default` という単一のシナリオのみをサポートします。 既定では、モデルは `default` という単一のシナリオのみをサポートします。
次のコードは、モデルのシナリオを設定する二つの方法を示すものです: 次のコードは、モデルのシナリオを設定する二つの方法を示すものです
```php ```php
// プロパティとしてシナリオをセットする // プロパティとしてシナリオをセットする
$model = new User; $model = new User;
$model->scenario = 'login'; $model->scenario = 'login';
// シナリオはコンフィギュレーションでセットされる // シナリオは設定情報でセットされる
$model = new User(['scenario' => 'login']); $model = new User(['scenario' => 'login']);
``` ```
既定では、モデルによってサポートされるシナリオは、モデルで宣言されている [検証規則](#validation-rules) によって決定されます。 既定では、モデルによってサポートされるシナリオは、モデルで宣言されている [検証規則](#validation-rules) によって決定されます。
しかし、次のように、[[yii\base\Model::scenarios()]] メソッドをオーバーライドして、この動作をカスタマイズすることが出来ます: しかし、次のように、[[yii\base\Model::scenarios()]] メソッドをオーバーライドして、この動作をカスタマイズすることが出来ます
```php ```php
namespace app\models; namespace app\models;
...@@ -201,7 +199,7 @@ class User extends ActiveRecord ...@@ -201,7 +199,7 @@ class User extends ActiveRecord
`scenarios()` の既定の実装は、検証規則の宣言メソッドである [[yii\base\Model::rules()]] に現れる全てのシナリオを返すものです。 `scenarios()` の既定の実装は、検証規則の宣言メソッドである [[yii\base\Model::rules()]] に現れる全てのシナリオを返すものです。
`scenarios()` をオーバーライドするときに、デフォルトのシナリオに加えて新しいシナリオを導入したい場合は、 `scenarios()` をオーバーライドするときに、デフォルトのシナリオに加えて新しいシナリオを導入したい場合は、
次のようなコードを書きます: 次のようなコードを書きます
```php ```php
namespace app\models; namespace app\models;
...@@ -250,9 +248,8 @@ if ($model->validate()) { ...@@ -250,9 +248,8 @@ if ($model->validate()) {
``` ```
モデルに関連付けられた検証規則を宣言するためには、[[yii\base\Model::rules()]] メソッドをオーバーライドして、 モデルに関連付けられた検証規則を宣言するためには、[[yii\base\Model::rules()]] メソッドをオーバーライドして、モデルの属性が満たすべき規則を返すようにします。
モデルの属性が満たすべき規則を返すようにします。 次の例は、`ContactForm` モデルのために宣言された検証規則を示します。
次の例は、`ContactForm` モデルのために宣言された検証規則を示します:
```php ```php
public function rules() public function rules()
...@@ -269,10 +266,10 @@ public function rules() ...@@ -269,10 +266,10 @@ public function rules()
一個の規則は、一個または複数の属性を検証するために使うことが出来ます。 一個の規則は、一個または複数の属性を検証するために使うことが出来ます。
また、一個の属性は、一個または複数の規則によって検証することが出来ます。 また、一個の属性は、一個または複数の規則によって検証することが出来ます。
検証規則をどのように宣言するかについて、更なる詳細は [入力を検証する](input-validation.md) の節を参照してください。 検証規則をどのように宣言するかについて詳細は [入力を検証する](input-validation.md) の節を参照してください。
時として、特定の [シナリオ](#scenarios) にのみ適用される規則が必要になるでしょう。そのためには、下記のように、 時として、特定の [シナリオ](#scenarios) にのみ適用される規則が必要になるでしょう。
規則に `on` プロパティを指定することが出来ます: そのためには、下記のように、規則に `on` プロパティを指定することが出来ます。
```php ```php
public function rules() public function rules()
...@@ -290,8 +287,8 @@ public function rules() ...@@ -290,8 +287,8 @@ public function rules()
`on` プロパティを指定しない場合は、その規則は全てのシナリオに適用されることになります。 `on` プロパティを指定しない場合は、その規則は全てのシナリオに適用されることになります。
現在の [[yii\base\Model::scenario|シナリオ]] に適用可能な規則は *アクティブな規則* と呼ばれます。 現在の [[yii\base\Model::scenario|シナリオ]] に適用可能な規則は *アクティブな規則* と呼ばれます。
属性が検証されるのは、それが `scenarios()` の中でアクティブな属性であると宣言されており、 属性が検証されるのは、それが `scenarios()` の中でアクティブな属性であると宣言されており、かつ、その属性が `rules()`
かつ、`rules()` の中で宣言されている一つまたは複数のアクティブな規則と関連付けられている場合であり、また、そのような場合だけです。 の中で宣言されている一つまたは複数のアクティブな規則と結び付けられている場合であり、また、そのような場合だけです。
## 一括代入<a name="massive-assignment"></a> ## 一括代入<a name="massive-assignment"></a>
...@@ -299,7 +296,7 @@ public function rules() ...@@ -299,7 +296,7 @@ public function rules()
一括代入は、一行のコードを書くだけで、ユーザの入力したデータをモデルに投入できる便利な方法です。 一括代入は、一行のコードを書くだけで、ユーザの入力したデータをモデルに投入できる便利な方法です。
一括代入は、入力されたデータを [[yii\base\Model::$attributes]] に直接に代入することによって、モデルの属性にデータを投入します。 一括代入は、入力されたデータを [[yii\base\Model::$attributes]] に直接に代入することによって、モデルの属性にデータを投入します。
次の二つのコード断片は等価であり、どちらもエンドユーザから送信されたフォームのデータを `ContactForm` モデルの属性に割り当てようとするものです。 次の二つのコード断片は等価であり、どちらもエンドユーザから送信されたフォームのデータを `ContactForm` モデルの属性に割り当てようとするものです。
明らかに、一括代入を使う前者の方が、後者よりも明瞭で間違いも起こりにくいでしょう: 明らかに、一括代入を使う前者の方が、後者よりも明瞭で間違いも起こりにくいでしょう
```php ```php
$model = new \app\models\ContactForm; $model = new \app\models\ContactForm;
...@@ -318,8 +315,8 @@ $model->body = isset($data['body']) ? $data['body'] : null; ...@@ -318,8 +315,8 @@ $model->body = isset($data['body']) ? $data['body'] : null;
### 安全な属性<a name="safe-attributes"></a> ### 安全な属性<a name="safe-attributes"></a>
一括代入は、いわゆる *安全な属性*、すなわち、モデルの現在の [[yii\base\Model::scenario|シナリオ]] 一括代入は、いわゆる *安全な属性*、すなわち、[[yii\base\Model::scenarios()]] においてモデルの現在の [[yii\base\Model::scenario|シナリオ]]
用に [[yii\base\Model::scenarios()]] にリストされている属性に対してのみ適用されます。 のためにリストされている属性に対してのみ適用されます。
例えば、`User` モデルが次のようなシナリオ宣言を持っている場合において、現在のシナリオが `login` であるときは、`username``password` のみが一括代入が可能です。その他の属性はいっさい触れられません。 例えば、`User` モデルが次のようなシナリオ宣言を持っている場合において、現在のシナリオが `login` であるときは、`username``password` のみが一括代入が可能です。その他の属性はいっさい触れられません。
```php ```php
...@@ -332,9 +329,8 @@ public function scenarios() ...@@ -332,9 +329,8 @@ public function scenarios()
} }
``` ```
> Info|情報: 一括代入が安全な属性に対してのみ適用されるのは、どの属性がエンドユーザのデータによって > Info|情報: 一括代入が安全な属性に対してのみ適用されるのは、どの属性がエンドユーザの入力データによって修正されうるかを制御する必要があるからです。
修正されうるかを制御する必要があるからです。 例えば、`User` モデルに、ユーザに割り当てられた権限を決定する `permission` という属性がある場合、
例えば、`User` モデルに、ユーザに割り当てられる権限を決定する `permission` という属性がある場合、
この属性が修正できるのは、管理者がバックエンドのインターフェイスを通じてする時だけに制限したいでしょう。 この属性が修正できるのは、管理者がバックエンドのインターフェイスを通じてする時だけに制限したいでしょう。
[[yii\base\Model::scenarios()]] の既定の実装は [[yii\base\Model::rules()]] に現われる全てのシナリオと属性を返すものです。 [[yii\base\Model::scenarios()]] の既定の実装は [[yii\base\Model::rules()]] に現われる全てのシナリオと属性を返すものです。
...@@ -354,11 +350,11 @@ public function rules() ...@@ -354,11 +350,11 @@ public function rules()
### 安全でない属性<a name="unsafe-attributes"></a> ### 安全でない属性<a name="unsafe-attributes"></a>
上記で説明したように、[[yii\base\Model::scenarios()]] メソッドは二つの目的を持っています: 上記で説明したように、[[yii\base\Model::scenarios()]] メソッドは二つの目的を持っています
すなわち、どの属性が検証されるべきかを決めることと、どの属性が安全であるかを決めることです。 すなわち、どの属性が検証されるべきかを決めることと、どの属性が安全であるかを決めることです。
めったにない場合として、属性を検証する必要はあるが、安全であるという印は付けたくない、ということがあります。 めったにない場合として、属性を検証する必要はあるが、安全であるという印は付けたくない、ということがあります。
そういう時は、下の例の `secret` 属性のように、`scenarios()` の中で宣言するときに属性の名前の前に感嘆符 そういう時は、下の例の `secret` 属性のように、`scenarios()` の中で宣言するときに属性の名前の前に感嘆符
`!` を前置することが出来ます: `!` を前置することが出来ます
```php ```php
public function scenarios() public function scenarios()
...@@ -370,8 +366,7 @@ public function scenarios() ...@@ -370,8 +366,7 @@ public function scenarios()
``` ```
このモデルが `login` シナリオにある場合、三つの属性は全て検証されます。しかし、`username` このモデルが `login` シナリオにある場合、三つの属性は全て検証されます。しかし、`username`
`password` の属性だけが一括代入が可能です。`secret` 属性に入力値を割り当てるためには、 `password` の属性だけが一括代入が可能です。`secret` 属性に入力値を割り当てるためには、下記のように明示的に代入を実行する必要があります。
下記のように明示的に実行する必要があります。
```php ```php
$model->secret = $secret; $model->secret = $secret;
...@@ -384,8 +379,8 @@ $model->secret = $secret; ...@@ -384,8 +379,8 @@ $model->secret = $secret;
Excel 形式に変換したい場合があるでしょう。 Excel 形式に変換したい場合があるでしょう。
エクスポートのプロセスは二つの独立したステップに分割することが出来ます。 エクスポートのプロセスは二つの独立したステップに分割することが出来ます。
最初のステップで、モデルは配列に変換されます。そして第二のステップで、配列が目的の形式に変換されます。 最初のステップで、モデルは配列に変換されます。そして第二のステップで、配列が目的の形式に変換されます。
あなたは最初のステップだけに注力しても構いません。と言うのは、第二のステップは汎用的なデータフォーマッタ、 あなたは最初のステップだけに注力しても構いません。と言うのは、第二のステップは汎用的なデータフォーマッタ、例えば [[yii\web\JsonResponseFormatter]]
例えば [[yii\web\JsonResponseFormatter]] によって達成できるからです。 によって達成できるからです。
モデルを配列に変換する最も簡単な方法は、[[yii\base\Model::$attributes]] プロパティを使うことです。 モデルを配列に変換する最も簡単な方法は、[[yii\base\Model::$attributes]] プロパティを使うことです。
例えば、 例えば、
...@@ -399,23 +394,21 @@ $array = $post->attributes; ...@@ -399,23 +394,21 @@ $array = $post->attributes;
モデルを配列に変換するためのもっと柔軟で強力な方法は、[[yii\base\Model::toArray()]] メソッドを使うことです。 モデルを配列に変換するためのもっと柔軟で強力な方法は、[[yii\base\Model::toArray()]] メソッドを使うことです。
このメソッドの既定の動作は [[yii\base\Model::$attributes]] のそれと同じものです。 このメソッドの既定の動作は [[yii\base\Model::$attributes]] のそれと同じものです。
しかしながら、このメソッドを使うと、どのデータ項目 (*フィールド* と呼ばれます) を結果の配列に入れるか、 しかしながら、このメソッドを使うと、どのデータ項目 (*フィールド* と呼ばれます)
そして、その項目にどのような書式を適用するかを選ぶことが出来ます。 を結果の配列に入れるか、そして、その項目にどのような書式を適用するかを選ぶことが出来ます。
実際、[レスポンスの書式設定](rest-response-formatting.md) で説明されているように、 実際、[レスポンスの書式設定](rest-response-formatting.md) で説明されているように、RESTful
RESTful ウェブサービスの開発においては、これがモデルをエクスポートする既定の方法となっています。 ウェブサービスの開発においては、これがモデルをエクスポートする既定の方法となっています。
### フィールド<a name="fields"></a> ### フィールド<a name="fields"></a>
フィールドとは、単に、モデルの [[yii\base\Model::toArray()]] メソッドを呼ぶことによって取得される配列の中の、 フィールドとは、単に、モデルの [[yii\base\Model::toArray()]] メソッドを呼ぶことによって取得される配列に含まれる名前付きの要素のことです。
名前付きの要素のことです。
既定では、フィールドの名前は属性の名前と等しいものになります。しかし、この既定の動作は、 既定では、フィールドの名前は属性の名前と等しいものになります。しかし、この既定の動作は、[[yii\base\Model::fields()|fields()]]
[[yii\base\Model::fields()|fields()]] および/または [[yii\base\Model::extraFields()|extraFields()]] メソッドをオーバーライドして、変更することが出来ます。 および/または [[yii\base\Model::extraFields()|extraFields()]] メソッドをオーバーライドして、変更することが出来ます。
どちらも、フィールド定義のリストを返すべきメソッドです。 どちらのメソッドも、フィールド定義のリストを返します。
`fields()` によって定義されたフィールドは、デフォルトフィールドです。 `fields()` によって定義されるフィールドは、デフォルトフィールドです。すなわち、`toArray()` はデフォルトでこれらのフィールドを返す、ということを意味します。
すなわち、`toArray()` が、既定ではこれらのフィールドを返すということを意味します。 `extraFields()` メソッドは、`$expand` パラメータによって指定する限りにおいて `toArray()` によって返される追加のフィールドを定義するものです。
`extraFields()` メソッドは、`$expand` パラメータによって指定する限りにおいて `toArray()` によって返され得る、追加のフィールドを定義します。
例として、次のコードは、`fields()` で定義された全てのフィールドと、 例として、次のコードは、`fields()` で定義された全てのフィールドと、
(`extraFields()` で定義されていれば) `prettyName``fullAddress` フィールドを返すものです。 (`extraFields()` で定義されていれば) `prettyName``fullAddress` フィールドを返すものです。
...@@ -424,8 +417,8 @@ $array = $model->toArray([], ['prettyName', 'fullAddress']); ...@@ -424,8 +417,8 @@ $array = $model->toArray([], ['prettyName', 'fullAddress']);
``` ```
`fields()` をオーバーライドして、フィールドを追加、削除、リネーム、再定義することが出来ます。 `fields()` をオーバーライドして、フィールドを追加、削除、リネーム、再定義することが出来ます。
`fields()` の返り値は配列でなければなりません。配列のキーはフィールド名であり、 `fields()` の返り値は配列でなければなりません。配列のキーはフィールド名であり、配列の値は対応するフィールド定義です。
配列の値は対応するフィールド定義です。フィールド定義には、プロパティ/属性の名前か、または、対応するフィールドの値を返す無名関数を使うことが出来ます。 フィールドの定義には、プロパティ/属性 の名前か、または、対応するフィールドの値を返す無名関数を使うことが出来ます。
フィールド名がそれを定義する属性名と同一であるという特殊な場合においては、配列のキーを省略することが出来ます。 フィールド名がそれを定義する属性名と同一であるという特殊な場合においては、配列のキーを省略することが出来ます。
例えば、 例えば、
...@@ -475,30 +468,28 @@ public function fields() ...@@ -475,30 +468,28 @@ public function fields()
要約すると、モデルは、 要約すると、モデルは、
* ビジネスデータを表現する属性を含むことが出来ます; * ビジネスデータを表現する属性を含むことが出来ます
* データの有効性と整合性を保証する検証規則を含むことが出来ます; * データの有効性と整合性を保証する検証規則を含むことが出来ます
* ビジネスロジックを実装するメソッドを含むことが出来ます; * ビジネスロジックを実装するメソッドを含むことが出来ます
* リクエスト、セッション、または他の環境データに直接アクセスするべきではありません。 * リクエスト、セッション、または他の環境データに直接アクセスするべきではありません。
これらのデータは、[コントローラ](structure-controllers.md) によってモデルに注入されるべきです; これらのデータは、[コントローラ](structure-controllers.md) によってモデルに注入されるべきです
* HTML を埋め込むなどの表示用のコードは避けるべきです - 表示は [ビュー](structure-views.md) で行う方が良いです; * HTML を埋め込むなどの表示用のコードは避けるべきです - 表示は [ビュー](structure-views.md) で行う方が良いです
* あまりに多くの [シナリオ](#scenarios) を単一のモデルで持つことは避けましょう。 * あまりに多くの [シナリオ](#scenarios) を単一のモデルで持つことは避けましょう。
大規模で複雑なシステムを開発するときには、たいてい、上記の最後にあげた推奨事項を考慮するのが良いでしょう。 大規模で複雑なシステムを開発するときには、たいてい、上記の最後にあげた推奨事項を考慮するのが良いでしょう。
そういうシステムでは、モデルは数多くの場所で使用され、それに従って、数多くの規則セットやビジネスロジックを含むため、非常に大きくて重いものになり得ます。 そういうシステムでは、モデルは数多くの場所で使用され、それに従って、数多くの規則セットやビジネスロジックを含むため、非常に大きくて重いものになり得ます。
コードの一ヶ所に触れるだけで数ヶ所の違った場所に影響が及ぶため、ついには、モデルのコードの保守が悪夢になってしまうこともよくあります。 コードの一ヶ所に触れるだけで数ヶ所の違った場所に影響が及ぶため、ついには、モデルのコードの保守が悪夢になってしまうこともよくあります。
モデルのコードの保守性を高めるために、以下の戦略をとることが出来ます: モデルのコードの保守性を高めるために、以下の戦略をとることが出来ます
* 異なる [アプリケーション](structure-applications.md)[モジュール](structure-modules.md) * 異なる [アプリケーション](structure-applications.md)[モジュール](structure-modules.md)
によって共有される一連の基底モデルクラスを定義します。 によって共有される一連の基底モデルクラスを定義します。
これらのモデルクラスは、すべてで共通に使用される最小限の規則セットとロジックのみを含むべきです。 これらのモデルクラスは、すべてで共通に使用される最小限の規則セットとロジックのみを含むべきです。
* モデルを使用するそれぞれの [アプリケーション](structure-applications.md) または [モジュール](structure-modules.md) において、 * モデルを使用するそれぞれの [アプリケーション](structure-applications.md) または [モジュール](structure-modules.md)
対応する基底モデルクラスから拡張した具体的なモデルクラスを定義します。 において、対応する基底モデルクラスから拡張した具体的なモデルクラスを定義します。
この具体的なモデルクラスが、そのアプリケーションやモジュールに固有の規則やロジックを含むべきです。 この具体的なモデルクラスが、そのアプリケーションやモジュールに固有の規則やロジックを含むべきです。
例えば、[アドバンストアプリケーションテンプレート](tutorial-advanced-app.md) の中で、 例えば、[アドバンストアプリケーションテンプレート](tutorial-advanced-app.md) の中で、基底モデルクラス `common\models\Post`
基底モデルクラス `common\models\Post` を定義することが出来ます。 を定義することが出来ます。次に、フロントエンドアプリケーションにおいては、`common\models\Post` から拡張した具体的なモデルクラス
次に、フロントエンドアプリケーションにおいては、`common\models\Post` から拡張した具体的なモデルクラス `frontend\models\Post` を定義して使います。また、バックエンドアプリケーションにおいても、同様に、`backend\models\Post` を定義します。
`frontend\models\Post` を定義して使います。
また、バックエンドアプリケーションにおいても、同様に、`backend\models\Post` を定義します。
この戦略を取ると、`frontend\models\Post` の中のコードはフロントエンドアプリケーション固有のものであると保証することが出来ます。 この戦略を取ると、`frontend\models\Post` の中のコードはフロントエンドアプリケーション固有のものであると保証することが出来ます。
そして、フロントエンドのコードにどのような変更を加えても、バックエンドアプリケーションを壊すかもしれないと心配する必要がなくなります。 そして、フロントエンドのコードにどのような変更を加えても、バックエンドアプリケーションを壊すかもしれないと心配する必要がなくなります。
モジュール モジュール
========== ==========
モジュールは、[モデル](structure-models.md)[ビュー](structure-views.md)[コントローラ](structure-controllers.md) モジュールは、[モデル](structure-models.md)[ビュー](structure-views.md)[コントローラ](structure-controllers.md)、およびその他の支援コンポーネントから構成される自己充足的なソフトウェアのユニットです。
およびその他の支援コンポーネントから構成される自己充足的なソフトウェアのユニットです。 モジュールが [アプリケーション](structure-applications.md) にインストールされている場合、エンドユーザはモジュールのコントローラにアクセスする事が出来ます。
モジュールが [アプリケーション](structure-applications.md) にインストールされている場合、 これらのことを理由として、モジュールは小さなアプリケーションと見なされることがよくあります。
エンドユーザはモジュールのコントローラにアクセスする事が出来ます。これらのことを理由として、 しかし、モジュールは単独では配置できず、アプリケーションの中に存在しなければならないという点で [アプリケーション](structure-applications.md) とは異なります。
モジュールは小さなアプリケーションと見なされることがよくあります。しかし、モジュールは単独では配置できず、
アプリケーションの中に存在しなければならないという点で [アプリケーション](structure-applications.md) とは異なります。
## モジュールを作成する <a name="creating-modules"></a> ## モジュールを作成する <a name="creating-modules"></a>
...@@ -14,7 +12,7 @@ ...@@ -14,7 +12,7 @@
モジュールは、モジュールの [[yii\base\Module::basePath|ベースパス]] と呼ばれるディレクトリとして組織されます。 モジュールは、モジュールの [[yii\base\Module::basePath|ベースパス]] と呼ばれるディレクトリとして組織されます。
このディレクトリの中に、ちょうどアプリケーションの場合と同じように、`controllers``models``views` このディレクトリの中に、ちょうどアプリケーションの場合と同じように、`controllers``models``views`
のようなサブディレクトリが存在して、コントローラ、モデル、ビュー、その他のコードを収納しています。 のようなサブディレクトリが存在して、コントローラ、モデル、ビュー、その他のコードを収納しています。
次の例は、モジュール内の中身を示すものです: 次の例は、モジュール内の中身を示すものです
``` ```
forum/ forum/
...@@ -32,13 +30,11 @@ forum/ ...@@ -32,13 +30,11 @@ forum/
### モジュールクラス <a name="module-classes"></a> ### モジュールクラス <a name="module-classes"></a>
全てのモジュールは [[yii\base\Module]] から拡張したユニークなモジュールクラスを持たなければなりません。 全てのモジュールは [[yii\base\Module]] から拡張したユニークなモジュールクラスを持たなければなりません。
モジュールクラスは、モジュールの [[yii\base\Module::basePath|ベースパス]] 直下に配置されて モジュールクラスは、モジュールの [[yii\base\Module::basePath|ベースパス]] 直下に配置されて [オートロード可能](concept-autoloading.md) になっていなければなりません。
[オートロード可能](concept-autoloading.md) になっていなければなりません。
モジュールがアクセスされたとき、対応するモジュールクラスの単一のインスタンスが作成されます。 モジュールがアクセスされたとき、対応するモジュールクラスの単一のインスタンスが作成されます。
[アプリケーションのインスタンス](structure-applications.md) と同じように、モジュールのインスタンスは [アプリケーションのインスタンス](structure-applications.md) と同じように、モジュールのインスタンスは、モジュール内のコードがデータとコンポーネントを共有するために使用されます。
モジュール内のコードがデータとコンポーネントを共有するために使用されます。
次のコードは、モジュールクラスがどのように見えるかを示す例です: 次のコードは、モジュールクラスがどのように見えるかを示す例です
```php ```php
namespace app\modules\forum; namespace app\modules\forum;
...@@ -55,28 +51,25 @@ class Module extends \yii\base\Module ...@@ -55,28 +51,25 @@ class Module extends \yii\base\Module
} }
``` ```
`init` メソッドがモジュールのプロパティを初期化するためのコードをたくさん含む場合は、それを `init` メソッドがモジュールのプロパティを初期化するためのコードをたくさん含む場合は、
[コンフィギュレーション](concept-configurations.md) の形で保存し、`init()` の中で次のコードを使って それを [構成情報](concept-configurations.md) の形で保存し、`init()` の中で次のコードを使って読み出すことも可能です。
読み出すことも可能です:
```php ```php
public function init() public function init()
{ {
parent::init(); parent::init();
// config.php からロードしたコンフィギュレーションでモジュールを初期化する // config.php からロードした構成情報でモジュールを初期化する
\Yii::configure($this, require(__DIR__ . '/config.php')); \Yii::configure($this, require(__DIR__ . '/config.php'));
} }
``` ```
ここで、コンフィギュレーションファイル `config.php` は、 ここで、構成情報ファイル `config.php` は、[アプリケーションの構成情報](structure-applications.md#application-configurations) の場合と同じように、次のような内容を含むことが出来ます。
[アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) の場合と同じように、
次のような内容を含むことが出来ます。
```php ```php
<?php <?php
return [ return [
'components' => [ 'components' => [
// コンポーネントのコンフィギュレーションのリスト // コンポーネントの構成情報のリスト
], ],
'params' => [ 'params' => [
// パラメータのリスト // パラメータのリスト
...@@ -87,11 +80,9 @@ return [ ...@@ -87,11 +80,9 @@ return [
### モジュール内のコントローラ <a name="controllers-in-modules"></a> ### モジュール内のコントローラ <a name="controllers-in-modules"></a>
モジュールの中でコントローラを作成するときは、コントローラクラスをモジュールクラスの名前空間の `controllers` モジュールの中でコントローラを作成するときは、コントローラクラスをモジュールクラスの名前空間の `controllers` サブ名前空間に置くことが規約です。
サブ名前空間に置くことが規約です。このことは、同時に、コントローラのクラスファイルをモジュールの このことは、同時に、コントローラのクラスファイルをモジュールの [[yii\base\Module::basePath|ベースパス]] 内の `controllers` ディレクトリに置くべきことをも意味します。
[[yii\base\Module::basePath|ベースパス]] 内の `controllers` ディレクトリに置くべきことをも意味します。 例えば、前の項で示された `forum` モジュールの中で `post` コントローラを作成するためには、次のようにしてコントローラを宣言しなければなりません。
例えば、前の項で示された `forum` モジュールの中で `post` コントローラを作成するためには、次のようにして
コントローラを宣言しなければなりません:
```php ```php
namespace app\modules\forum\controllers; namespace app\modules\forum\controllers;
...@@ -105,78 +96,72 @@ class PostController extends Controller ...@@ -105,78 +96,72 @@ class PostController extends Controller
``` ```
コントローラクラスの名前空間は、[[yii\base\Module::controllerNamespace]] プロパティを構成してカスタマイズすることが出来ます。 コントローラクラスの名前空間は、[[yii\base\Module::controllerNamespace]] プロパティを構成してカスタマイズすることが出来ます。
いくつかのコントローラがこの名前空間の外にある場合でも、[[yii\base\Module::controllerMap]] プロパティを構成することによって、 いくつかのコントローラがこの名前空間の外にある場合でも、[[yii\base\Module::controllerMap]] プロパティを構成することによって、それらをアクセス可能にすることが出来ます。
それらをアクセス可能にすることが出来ます。これは、[アプリケーションでのコントローラマップ](structure-applications.md#controller-map) これは、[アプリケーションでのコントローラマップ](structure-applications.md#controller-map) の場合と同様です。
の場合と同様です。
### モジュール内のビュー <a name="views-in-modules"></a> ### モジュール内のビュー <a name="views-in-modules"></a>
モジュール内のビューは、モジュールの [[yii\base\Module::basePath|ベースパス]] 内の `views` ディレクトリに置かれなくてはなりません。 モジュール内のビューは、モジュールの [[yii\base\Module::basePath|ベースパス]] 内の `views` ディレクトリに置かれなくてはなりません。
モジュール内のコントローラによってレンダリングされるビューは、ディレクトリ `views/ControllerID` の下に置きます。ここで、 モジュール内のコントローラによってレンダリングされるビューは、ディレクトリ `views/ControllerID` の下に置きます。
`ControllerID`[コントローラ ID](structure-controllers.md#routes) を指します。例えば、コントローラクラスが `PostController` ここで、`ControllerID`[コントローラ ID](structure-controllers.md#routes) を指します。
である場合、ディレクトリはモジュールの [[yii\base\Module::basePath|ベースパス]] の中の `views/post` となります。 例えば、コントローラクラスが `PostController` である場合、ディレクトリはモジュールの [[yii\base\Module::basePath|ベースパス]] の中の `views/post` となります。
モジュールは、そのモジュールのコントローラによってレンダリングされるビューに適用される [レイアウト](structure-views.md#layouts) モジュールは、そのモジュールのコントローラによってレンダリングされるビューに適用される [レイアウト](structure-views.md#layouts) を指定することが出来ます。
を指定することが出来ます。レイアウトは、既定では `views/layouts` ディレクトリに置かれなければならず、また、 レイアウトは、既定では `views/layouts` ディレクトリに置かれなければならず、また、[[yii\base\Module::layout]] プロパティがレイアウトの名前を指すように構成しなければなりません。
[[yii\base\Module::layout]] プロパティがレイアウトの名前を指すように構成しなければなりません。
`layout` プロパティを構成しない場合は、アプリケーションのレイアウトが代りに使用されます。 `layout` プロパティを構成しない場合は、アプリケーションのレイアウトが代りに使用されます。
## モジュールを使う <a name="using-modules"></a> ## モジュールを使う <a name="using-modules"></a>
アプリケーションの中でモジュールを使うためには、アプリケーションの [[yii\base\Application::modules|modules]] プロパティのリストに アプリケーションの中でモジュールを使うためには、アプリケーションの [[yii\base\Application::modules|modules]] プロパティのリストにそのモジュールを載せてアプリケーションを構成するだけで大丈夫です。
そのモジュールを載せてアプリケーションを構成するだけで大丈夫です。次のコードは、 次のコードは、[アプリケーションの構成情報](structure-applications.md#application-configurations) の中で `forum` モジュールを使うようにするものです。
[アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) の中で
`forum` モジュールを使うようにするものです:
```php ```php
[ [
'modules' => [ 'modules' => [
'forum' => [ 'forum' => [
'class' => 'app\modules\forum\Module', 'class' => 'app\modules\forum\Module',
// ... モジュールのその他のコンフィギュレーション ... // ... モジュールのその他の構成情報 ...
], ],
], ],
] ]
``` ```
[[yii\base\Application::modules|modules]] プロパティは、モジュールのコンフィギュレーションの配列を取ります。各配列のキーは、 [[yii\base\Application::modules|modules]] プロパティは、モジュールの構成情報の配列を取ります。
アプリケーションの全てのモジュールの中でそのモジュールを特定するためのユニークな *モジュール ID* を表します。そして、 各配列のキーは、アプリケーションの全てのモジュールの中でそのモジュールを特定するためのユニークな *モジュール ID* を表します。
対応する配列の値は、そのモジュールを作成するための [コンフィギュレーション](concept-configurations.md) です。 そして、対応する配列の値は、そのモジュールを作成するための [構成情報](concept-configurations.md) です。
### ルート <a name="routes"></a> ### ルート <a name="routes"></a>
アプリケーションの中のコントローラをアクセスするのと同じように、[ルート](structure-controllers.md#routes) アプリケーションの中のコントローラをアクセスするのと同じように、[ルート](structure-controllers.md#routes) がモジュールの中のコントローラを指し示すために使われます。
がモジュールの中のコントローラを指し示すために使われます。モジュール内のコントローラのルートは、モジュール ID で始まり、 モジュール内のコントローラのルートは、モジュール ID で始まり、コントローラ ID、アクション ID と続くものでなければなりません。
コントローラ ID、アクション ID と続くものでなければなりません。例えば、アプリケーションが `forum` という名前のモジュールを 例えば、アプリケーションが `forum` という名前のモジュールを使用している場合、`forum/post/index` というルートは、`forum` モジュール内の `post` コントローラの `index` アクションを表します。
使用している場合、`forum/post/index` というルートは、`forum` モジュール内の `post` コントローラの `index` アクションを表します。 ルートがモジュール ID だけを含む場合は、[[yii\base\Module::defaultRoute]] プロパティ (既定値は `default` です) が、どのコントローラ/アクションが使用されるべきかを決定します。
ルートがモジュール ID だけを含む場合は、[[yii\base\Module::defaultRoute]] プロパティ (その既定値は `default` です) が、 これは、`forum` というルートは `forum` モジュール内の `default` コントローラを表すという意味です。
どのコントローラ/アクションが使用されるべきかを決定します。これは、`forum` というルートは `forum` モジュール内の
`default` コントローラを表すという意味です。
### モジュールにアクセスする <a name="accessing-modules"></a> ### モジュールにアクセスする <a name="accessing-modules"></a>
モジュール内において、モジュール ID や、モジュールのパラメータ、モジュールのコンポーネントなどにアクセスするために、 モジュール内において、モジュール ID や、モジュールのパラメータ、モジュールのコンポーネントなどにアクセスするために、[モジュールクラス](#module-classes) のインスタンスを取得する必要があることがよくあります。
[モジュールクラス](#module-classes) のインスタンスを取得する必要があることがよくあります。次の文を使ってそうすることが出来ます: 次の文を使ってそうすることが出来ます。
```php ```php
$module = MyModuleClass::getInstance(); $module = MyModuleClass::getInstance();
``` ```
ここで `MyModuleClass` は、関心を持っているモジュールクラスの名前を指します。`getInstance()` メソッドは、 ここで `MyModuleClass` は、関心を持っているモジュールクラスの名前を指します。
現在リクエストされているモジュールクラスのインスタンスを返します。モジュールがリクエストされていない場合は、 `getInstance()` メソッドは、現在リクエストされているモジュールクラスのインスタンスを返します。
このメソッドは null を返します。モジュールクラスの新しいインスタンスを手動で作成しようとしてはいけないことに注意してください。 モジュールがリクエストされていない場合は、このメソッドは null を返します。
モジュールクラスの新しいインスタンスを手動で作成しようとしてはいけないことに注意してください。
そのインスタンスは、リクエストに対するレスポンスとして Yii によって作成されたインスタンスとは別のものになります。 そのインスタンスは、リクエストに対するレスポンスとして Yii によって作成されたインスタンスとは別のものになります。
> Info|情報: モジュールを開発するとき、モジュールが固定の ID を使うと仮定してはいけません。なぜなら、モジュールは、 > Info|情報: モジュールを開発するとき、モジュールが固定の ID を使うと仮定してはいけません。
アプリケーションや他のモジュールの中で使うときに、任意の ID と結び付けることが出来るからです。 なぜなら、モジュールは、アプリケーションや他のモジュールの中で使うときに、任意の ID と結び付けることが出来るからです。
モジュール ID を取得するためには、上記の方法を使って最初にモジュールのインスタンスを取得し、そして `$module->id` モジュール ID を取得するためには、上記の方法を使って最初にモジュールのインスタンスを取得し、そして `$module->id` によって ID を取得しなければなりません。
によって ID を取得しなければなりません。
モジュールのインスタンスにアクセスするためには、次の二つの方法を使うことも出来ます: モジュールのインスタンスにアクセスするためには、次の二つの方法を使うことも出来ます
```php ```php
// ID が "forum" である子モジュールを取得する // ID が "forum" である子モジュールを取得する
...@@ -186,8 +171,7 @@ $module = \Yii::$app->getModule('forum'); ...@@ -186,8 +171,7 @@ $module = \Yii::$app->getModule('forum');
$module = \Yii::$app->controller->module; $module = \Yii::$app->controller->module;
``` ```
最初の方法は、モジュール ID を知っている時しか役に立ちません。一方、第二の方法は、 最初の方法は、モジュール ID を知っている時しか役に立ちません。一方、第二の方法は、リクエストされているコントローラについて知っている場合に使うのに最適な方法です。
リクエストされているコントローラについて知っている場合に使うのに最適な方法です。
いったんモジュールのインスタンスをとらえれば、モジュールに登録されたパラメータやコンポーネントにアクセスすることが可能になります。 いったんモジュールのインスタンスをとらえれば、モジュールに登録されたパラメータやコンポーネントにアクセスすることが可能になります。
例えば、 例えば、
...@@ -202,7 +186,7 @@ $maxPostCount = $module->params['maxPostCount']; ...@@ -202,7 +186,7 @@ $maxPostCount = $module->params['maxPostCount'];
いくつかのモジュールは、全てのリクエストで毎回走らせる必要があります。[[yii\debug\Module|デバッグ]] モジュールがその一例です。 いくつかのモジュールは、全てのリクエストで毎回走らせる必要があります。[[yii\debug\Module|デバッグ]] モジュールがその一例です。
そうするためには、そのようなモジュールをアプリケーションの [[yii\base\Application::bootstrap|bootstrap]] プロパティのリストに挙げます。 そうするためには、そのようなモジュールをアプリケーションの [[yii\base\Application::bootstrap|bootstrap]] プロパティのリストに挙げます。
例えば、次のアプリケーションのコンフィギュレーションは、`debug` モジュールが常にロードされることを保証するものです: 例えば、次のアプリケーションの構成情報は、`debug` モジュールが常にロードされることを保証するものです。
```php ```php
[ [
...@@ -219,9 +203,10 @@ $maxPostCount = $module->params['maxPostCount']; ...@@ -219,9 +203,10 @@ $maxPostCount = $module->params['maxPostCount'];
## 入れ子のモジュール <a name="nested-modules"></a> ## 入れ子のモジュール <a name="nested-modules"></a>
モジュールはレベルの制限無く入れ子にすることが出来ます。つまり、モジュールは別のモジュールを含むことが出来、 モジュールはレベルの制限無く入れ子にすることが出来ます。
その含まれたモジュールもさらに別のモジュールを含むことが出来ます。含む側を *親モジュール*、含まれる側を *子モジュール* つまり、モジュールは別のモジュールを含むことが出来、その含まれたモジュールもさらに別のモジュールを含むことが出来ます。
と呼びます。子モジュールは、親モジュールの [[yii\base\Module::modules|modules]] プロパティの中で宣言されなければなりません。 含む側を *親モジュール*、含まれる側を *子モジュール* と呼びます。
子モジュールは、親モジュールの [[yii\base\Module::modules|modules]] プロパティの中で宣言されなければなりません。
例えば、 例えば、
```php ```php
...@@ -244,8 +229,7 @@ class Module extends \yii\base\Module ...@@ -244,8 +229,7 @@ class Module extends \yii\base\Module
``` ```
入れ子にされたモジュールの中にあるコントローラのルートは、全ての祖先のモジュールの ID を含まなければなりません。 入れ子にされたモジュールの中にあるコントローラのルートは、全ての祖先のモジュールの ID を含まなければなりません。
例えば、`forum/admin/dashboard/index` というルートは、`forum` モジュールの子モジュールである `admin` モジュールの 例えば、`forum/admin/dashboard/index` というルートは、`forum` モジュールの子モジュールである `admin` モジュールの `dashboard` コントローラの `index` アクションを表します。
`dashboard` コントローラの `index` アクションを表します。
> Info|情報: [[yii\base\Module::getModule()|getModule()]] メソッドは、親モジュールに直接属する子モジュールだけを返します。 > Info|情報: [[yii\base\Module::getModule()|getModule()]] メソッドは、親モジュールに直接属する子モジュールだけを返します。
[[yii\base\Application::loadedModules]] プロパティがロードされた全てのモジュールのリストを保持しています。 [[yii\base\Application::loadedModules]] プロパティがロードされた全てのモジュールのリストを保持しています。
...@@ -254,9 +238,8 @@ class Module extends \yii\base\Module ...@@ -254,9 +238,8 @@ class Module extends \yii\base\Module
## 最善の慣行 <a name="best-practices"></a> ## 最善の慣行 <a name="best-practices"></a>
モジュールは、それぞれ密接に関係する一連の機能を含む数個のグループに分割できるような、規模の大きなアプリケーションに モジュールは、それぞれ密接に関係する一連の機能を含む数個のグループに分割できるような、規模の大きなアプリケーションに最も適しています。
最も適しています。そのような機能グループをそれぞれモジュールとして、特定の個人やチームによって開発することが出来ます。 そのような機能グループをそれぞれモジュールとして、特定の個人やチームによって開発することが出来ます。
モジュールは、また、機能グループレベルでコードを再利用するための良い方法でもあります。ある種のよく使われる機能、 モジュールは、また、機能グループレベルでコードを再利用するための良い方法でもあります。
例えばユーザ管理やコメント管理などは、全て、将来のプロジェクトで容易に再利用できるように、モジュールの形式で ある種のよく使われる機能、例えばユーザ管理やコメント管理などは、全て、将来のプロジェクトで容易に再利用できるように、モジュールの形式で開発することが出来ます。
開発することが出来ます。
...@@ -2,11 +2,11 @@ ...@@ -2,11 +2,11 @@
==== ====
Yii のアプリケーションは [モデル・ビュー・コントローラ (MVC)](http://ja.wikipedia.org/wiki/Model_View_Controller) デザインパターンに従って組織されます。 Yii のアプリケーションは [モデル・ビュー・コントローラ (MVC)](http://ja.wikipedia.org/wiki/Model_View_Controller) デザインパターンに従って組織されます。
[モデル](structure-models.md) は、データ、ビジネスロジック、規則を表現します; [モデル](structure-models.md) は、データ、ビジネスロジック、規則を表現します
[ビュー](structure-views.md) は、モデルの出力表現です; [ビュー](structure-views.md) は、モデルの出力表現です
そして [コントローラ](structure-controllers.md) は入力を受け取って、それを [モデル](structure-models.md)[ビュー](structure-views.md) のためのコマンドに変換します。 そして [コントローラ](structure-controllers.md) は入力を受け取って、それを [モデル](structure-models.md)[ビュー](structure-views.md) のためのコマンドに変換します。
MVC 以外にも、Yii のアプリケーションは下記の要素を持っています: MVC 以外にも、Yii のアプリケーションは下記の要素を持っています
* [エントリスクリプト](structure-entry-scripts.md): エンドユーザから直接アクセスできる PHP スクリプトです。 * [エントリスクリプト](structure-entry-scripts.md): エンドユーザから直接アクセスできる PHP スクリプトです。
これはリクエスト処理サイクルを開始する役目を持っています。 これはリクエスト処理サイクルを開始する役目を持っています。
...@@ -15,9 +15,9 @@ MVC 以外にも、Yii のアプリケーションは下記の要素を持って ...@@ -15,9 +15,9 @@ MVC 以外にも、Yii のアプリケーションは下記の要素を持って
* [アプリケーションコンポーネント](structure-application-components.md): アプリケーションと共に登録されたオブジェクトであり、リクエストに応えるための様々なサービスを提供します。 * [アプリケーションコンポーネント](structure-application-components.md): アプリケーションと共に登録されたオブジェクトであり、リクエストに応えるための様々なサービスを提供します。
* [モジュール](structure-modules.md): それ自身に完全な MVC を含む自己完結的なパッケージです。 * [モジュール](structure-modules.md): それ自身に完全な MVC を含む自己完結的なパッケージです。
アプリケーションは複数のモジュールとして組織することが出来ます。 アプリケーションは複数のモジュールとして組織することが出来ます。
* [フィルタ](structure-filters.md): 各リクエストが実際に処理される前と後に、コントローラから呼び出される必要があるコードを表現します。 * [フィルタ](structure-filters.md): 各リクエストが実際に処理される前と後に、コントローラから呼び出される必要があるコードを表現します。
* [ウィジェット](structure-widgets.md): [ビュー](structure-views.md) に埋め込むことが出来るオブジェクトです。コントローラのロジックを含むことが可能で、異なるビューで再利用することが出来ます。 * [ウィジェット](structure-widgets.md): [ビュー](structure-views.md) に埋め込むことが出来るオブジェクトです。コントローラのロジックを含むことが可能で、異なるビューで再利用することが出来ます。
下の図がアプリケーションの静的な構造を示すものです: 下の図がアプリケーションの静的な構造を示すものです
![アプリケーションの静的な構造](images/application-structure.png) ![アプリケーションの静的な構造](images/application-structure.png)
...@@ -3,9 +3,8 @@ ...@@ -3,9 +3,8 @@
ビューは [MVC](http://ja.wikipedia.org/wiki/Model_View_Controller) アーキテクチャの一部を成すものです。 ビューは [MVC](http://ja.wikipedia.org/wiki/Model_View_Controller) アーキテクチャの一部を成すものです。
ビューはエンドユーザにデータを表示することに責任を持つコードです。 ビューはエンドユーザにデータを表示することに責任を持つコードです。
ウェブアプリケーションにおいては、ビューは、通常、主として HTML コードと表示目的の PHP コードを含む PHP スクリプトファイルである、 ウェブアプリケーションにおいては、ビューは、通常、主として HTML コードと表示目的の PHP コードを含む PHP スクリプトファイルである、*ビューテンプレート* の形式で作成されます。
*ビューテンプレート* の形式で作成されます。 そして、ビューテンプレートを管理する [[yii\web\View|ビュー]] [アプリケーションコンポーネント](structure-application-components.md) が、
そして、ビューテンプレートを管理する [[yii\web\View|ビュー]] [アプリケーションコンポーネント](structure-application-components.md) は、
ビューの構築とレンダリングを助けるためによく使われるメソッドを提供します。 ビューの構築とレンダリングを助けるためによく使われるメソッドを提供します。
なお、簡潔さを重視して、ビューテンプレートまたはビューテンプレートファイルを単にビューと呼ぶことがよくあります。 なお、簡潔さを重視して、ビューテンプレートまたはビューテンプレートファイルを単にビューと呼ぶことがよくあります。
...@@ -38,25 +37,22 @@ $this->title = '繝ュ繧ー繧、繝ウ'; ...@@ -38,25 +37,22 @@ $this->title = '繝ュ繧ー繧、繝ウ';
<?php ActiveForm::end(); ?> <?php ActiveForm::end(); ?>
``` ```
ビューの中でアクセスできる `$this` は、このビューテンプレートを管理しレンダリングしている ビューの中でアクセスできる `$this` は、このビューテンプレートを管理しレンダリングしている [[yii\web\View|ビューコンポーネント]] を参照します。
[[yii\web\View|ビューコンポーネント]] を参照します。
`$this` 以外に、上記の例の `$model` のように、前もって定義された変数がビューの中にあることがあります。 `$this` 以外に、上記の例の `$model` のように、前もって定義された変数がビューの中にあることがあります。
このような変数は、[コントローラ](structure-controllers.md) または [ビューのレンダリング](#rendering-views) をトリガするオブジェクトによってビューに *プッシュ* されたデータを表します。 このような変数は、[コントローラ](structure-controllers.md) または [ビューのレンダリング](#rendering-views) をトリガするオブジェクトによってビューに *プッシュ* されたデータを表します。
> Tip|ヒント: 上の例では、事前に定義された変数は、IDE に認識されるように、 > Tip|ヒント: 上の例では、事前に定義された変数は、IDE に認識されるように、ビューの先頭のコメントブロックの中にリストされています。
ビューの先頭のコメントブロックの中にリストされています。これは、ビューに これは、ビューにドキュメントを付けるのにも良い方法です。
ドキュメントを付けるのにも良い方法です。
### セキュリティ <a name="security"></a> ### セキュリティ <a name="security"></a>
HTML ページを生成するビューを作成するときは、エンドユーザから受け取るデータを HTML ページを生成するビューを作成するときは、エンドユーザから受け取るデータを表示する前にエンコード および/または フィルタすることが重要です。
表示する前に エンコード および/または フィルター することが重要です。
そうしなければ、あなたのアプリケーションは [クロスサイトスクリプティング](http://ja.wikipedia.org/wiki/%E3%82%AF%E3%83%AD%E3%82%B9%E3%82%B5%E3%82%A4%E3%83%88%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0) 攻撃をこうむるおそれがあります。 そうしなければ、あなたのアプリケーションは [クロスサイトスクリプティング](http://ja.wikipedia.org/wiki/%E3%82%AF%E3%83%AD%E3%82%B9%E3%82%B5%E3%82%A4%E3%83%88%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0) 攻撃をこうむるおそれがあります。
平文テキストを表示するためには、まず [[yii\helpers\Html::encode()]] を呼んでエンコードします。 平文テキストを表示するためには、まず [[yii\helpers\Html::encode()]] を呼んでエンコードします。
例えば、次のコードはユーザの名前を表示する前にエンコードしています: 例えば、次のコードはユーザの名前を表示する前にエンコードしています。
```php ```php
<?php <?php
...@@ -68,8 +64,8 @@ use yii\helpers\Html; ...@@ -68,8 +64,8 @@ use yii\helpers\Html;
</div> </div>
``` ```
HTML コンテンツを表示するためには、[[yii\helpers\HtmlPurifier]] を使って、最初にコンテンツをフィルターします。 HTML コンテンツを表示するためには、[[yii\helpers\HtmlPurifier]] を使って、最初にコンテンツをフィルタします。
例えば、次のコードは、投稿のコンテンツを表示する前にフィルターしています: 例えば、次のコードは、投稿のコンテンツを表示する前にフィルタしています。
```php ```php
<?php <?php
...@@ -81,28 +77,22 @@ use yii\helpers\HtmlPurifier; ...@@ -81,28 +77,22 @@ use yii\helpers\HtmlPurifier;
</div> </div>
``` ```
> Tip|ヒント: HTMLPurifier は、出力を安全なものにすることにおいては素晴らしい仕事をしますが、 > Tip|ヒント: HTMLPurifier は、出力を安全なものにすることにおいては素晴らしい仕事をしますが、速くはありません。
速くはありません。アプリケーションが高いパフォーマンスを要求する場合は、 アプリケーションが高いパフォーマンスを要求する場合は、フィルター結果を [キャッシュ](caching-overview.md) することを考慮すべきです。
フィルター結果を [キャッシュ](caching-overview.md) することを考慮すべきです。
### ビューを整理する <a name="organizing-views"></a> ### ビューを整理する <a name="organizing-views"></a>
[コントローラ](structure-controllers.md)[モデル](structure-models.md) と同じように、 [コントローラ](structure-controllers.md)[モデル](structure-models.md) と同じように、ビューを整理するための規約があります。.
ビューを整理するための規約があります。.
* コントローラによって表示されるビューは、既定では、ディレクトリ * コントローラによって表示されるビューは、既定では、ディレクトリ `@app/views/ControllerID` の下に置かれるべきものです。
`@app/views/ControllerID` の下に置かれるべきものです。
ここで、`ControllerID`[コントローラ ID](structure-controllers.md#routes) を指します。 ここで、`ControllerID`[コントローラ ID](structure-controllers.md#routes) を指します。
例えば、コントローラクラスが `PostController` である場合、ディレクトリは `@app/views/post` 例えば、コントローラクラスが `PostController` である場合、ディレクトリは `@app/views/post` となります。
となります。`PostCommentController` の場合は、ディレクトリは `@app/views/post-comment` です。 `PostCommentController` の場合は、ディレクトリは `@app/views/post-comment` です。
また、コントローラがモジュールに属する場合は、ディレクトリは [[yii\base\Module::basePath|モジュールディレクトリ]] また、コントローラがモジュールに属する場合は、ディレクトリは [[yii\base\Module::basePath|モジュールディレクトリ]] の下の `views/ControllerID` です。
の下の `views/ControllerID` です。 * [ウィジェット](structure-widgets.md) で表示されるビューは、既定では、`WidgetPath/views` ディレクトリの下に置かれるべきものです。
* [ウィジェット](structure-widgets.md) で表示されるビューは、既定では、`WidgetPath/views` ここで、`WidgetPath` は、ウィジェットのクラスファイルを含んでいるディレクトリを指します。
ディレクトリの下に置かれるべきものです。ここで、`WidgetPath` は、ウィジェットのクラスファイル * 他のオブジェクトによって表示されるビューについても、ウィジェットの場合と同じ規約に従うことが推奨されます。
を含んでいるディレクトリを指します。
* 他のオブジェクトによって表示されるビューについても、ウィジェットの場合と同じ規約に従うことが
推奨されます。
これらの既定のビューディレクトリは、コントローラやウィジェットの [[yii\base\ViewContextInterface::getViewPath()]] これらの既定のビューディレクトリは、コントローラやウィジェットの [[yii\base\ViewContextInterface::getViewPath()]]
メソッドをオーバーライドすることでカスタマイズすることが可能です。 メソッドをオーバーライドすることでカスタマイズすることが可能です。
...@@ -110,14 +100,13 @@ use yii\helpers\HtmlPurifier; ...@@ -110,14 +100,13 @@ use yii\helpers\HtmlPurifier;
## ビューをレンダリングする <a name="rendering-views"></a> ## ビューをレンダリングする <a name="rendering-views"></a>
[コントローラ](structure-controllers.md) の中でも、[ウィジェット](structure-widgets.md) の中でも、 [コントローラ](structure-controllers.md) の中でも、[ウィジェット](structure-widgets.md) の中でも、または、その他のどんな場所でも、
または、その他のどんな場所でも、ビューをレンダリングするメソッドを呼ぶことによって ビューをレンダリングするメソッドを呼ぶことによってビューをレンダリングすることが出来ます。
ビューをレンダリングすることが出来ます。
これらのメソッドは、下記に示されるような類似のシグニチャを共有します。 これらのメソッドは、下記に示されるような類似のシグニチャを共有します。
``` ```
/** /**
* @param string $view ビュー名またはファイルパス、実際のレンダリングメソッドに依存する * @param string $view ビュー名またはファイルパス (実際のレンダリングメソッドに依存する)
* @param array $params ビューに引き渡されるデータ * @param array $params ビューに引き渡されるデータ
* @return string レンダリングの結果 * @return string レンダリングの結果
*/ */
...@@ -127,20 +116,14 @@ methodName($view, $params = []) ...@@ -127,20 +116,14 @@ methodName($view, $params = [])
### コントローラでのレンダリング <a name="rendering-in-controllers"></a> ### コントローラでのレンダリング <a name="rendering-in-controllers"></a>
[コントローラ](structure-controllers.md) の中では、ビューをレンダリングするために [コントローラ](structure-controllers.md) の中では、ビューをレンダリングするために次のコントローラメソッドを呼ぶことが出来ます。
次のコントローラメソッドを呼ぶことが出来ます:
* [[yii\base\Controller::render()|render()]]: [名前付きビュー](#named-views) をレンダリングし、 * [[yii\base\Controller::render()|render()]]: [名前付きビュー](#named-views) をレンダリングし、その結果に [レイアウト](#layouts) を適用する。
その結果に [レイアウト](#layouts) を適用する。 * [[yii\base\Controller::renderPartial()|renderPartial()]]: [名前付きビュー](#named-views) をレイアウトなしでレンダリングする。
* [[yii\base\Controller::renderPartial()|renderPartial()]]: [名前付きビュー](#named-views) * [[yii\web\Controller::renderAjax()|renderAjax()]]: [名前付きビュー](#named-views) をレイアウトなしでレンダリングし、登録されている全ての JS/CSS スクリプトおよびファイルを注入する。
レイアウトなしでレンダリングする。
* [[yii\web\Controller::renderAjax()|renderAjax()]]: [名前付きビュー](#named-views)
レイアウトなしでレンダリングし、登録されている全ての JS/CSS スクリプトおよびファイルを注入する。
通常、AJAX ウェブリクエストに対するレスポンスにおいて使用される。 通常、AJAX ウェブリクエストに対するレスポンスにおいて使用される。
* [[yii\base\Controller::renderFile()|renderFile()]]: ビューファイルのパスまたは [エイリアス](concept-aliases.md) * [[yii\base\Controller::renderFile()|renderFile()]]: ビューファイルのパスまたは [エイリアス](concept-aliases.md) の形式で指定されたビューをレンダリングする。
の形式で指定されたビューをレンダリングする。 * [[yii\base\Controller::renderContent()|renderContent()]]: 静的な文字列をレンダリングして、現在適用可能な [レイアウト](#layouts) に埋め込む。このメソッドは バージョン 2.0.1 以降で使用可能。
* [[yii\base\Controller::renderContent()|renderContent()]]: 現在適用可能な [レイアウト](#layouts) に埋め込むことによって、
静的な文字列をレンダリングする。このメソッドは バージョン 2.0.1 以降で使用可能。
例えば、 例えば、
...@@ -172,12 +155,10 @@ class PostController extends Controller ...@@ -172,12 +155,10 @@ class PostController extends Controller
### ウィジェットでのレンダリング <a name="rendering-in-widgets"></a> ### ウィジェットでのレンダリング <a name="rendering-in-widgets"></a>
[ウィジェット](structure-widgets.md) の中では、ビューをレンダリングするために、 [ウィジェット](structure-widgets.md) の中では、ビューをレンダリングするために、次のウィジェットメソッドを使用することが出来ます。
次のウィジェットメソッドを使用することが出来ます。
* [[yii\base\Widget::render()|render()]]: [名前付きのビュー](#named-views) をレンダリングする。 * [[yii\base\Widget::render()|render()]]: [名前付きのビュー](#named-views) をレンダリングする。
* [[yii\base\Widget::renderFile()|renderFile()]]: ビューファイルのパスまたは [エイリアス](concept-aliases.md) * [[yii\base\Widget::renderFile()|renderFile()]]: ビューファイルのパスまたは [エイリアス](concept-aliases.md) の形式で指定されたビューをレンダリングする。
の形式で指定されたビューをレンダリングする。
例えば、 例えば、
...@@ -204,19 +185,15 @@ class ListWidget extends Widget ...@@ -204,19 +185,15 @@ class ListWidget extends Widget
### ビューでのレンダリング <a name="rendering-in-views"></a> ### ビューでのレンダリング <a name="rendering-in-views"></a>
[[yii\base\View|ビューコンポーネント]] によって提供される下記のメソッドのどれかを使うと、 [[yii\base\View|ビューコンポーネント]] によって提供される下記のメソッドのどれかを使うと、ビューの中で、別のビューをレンダリングすることが出来ます。
ビューの中で、別のビューをレンダリングすることが出来ます:
* [[yii\base\View::render()|render()]]: [名前付きのビュー](#named-views) をレンダリングする。 * [[yii\base\View::render()|render()]]: [名前付きのビュー](#named-views) をレンダリングする。
* [[yii\web\View::renderAjax()|renderAjax()]]: [名前付きビュー](#named-views) をレンダリングし、 * [[yii\web\View::renderAjax()|renderAjax()]]: [名前付きビュー](#named-views) をレンダリングし、登録されている全ての JS/CSS スクリプトおよびファイルを注入する。
登録されている全ての JS/CSS スクリプトおよびファイルを注入する。
通常、AJAX ウェブリクエストに対するレスポンスにおいて使用される。 通常、AJAX ウェブリクエストに対するレスポンスにおいて使用される。
* [[yii\base\View::renderFile()|renderFile()]]: ビューファイルのパスまたは [エイリアス](concept-aliases.md) * [[yii\base\View::renderFile()|renderFile()]]: ビューファイルのパスまたは [エイリアス](concept-aliases.md) の形式で指定されたビューをレンダリングする。
の形式で指定されたビューをレンダリングする。
例えば、ビューの中の次のコードは、現在レンダリングされているビューと同じディレクトリにある 例えば、ビューの中の次のコードは、現在レンダリングされているビューと同じディレクトリにある `_overview.php` というビューファイルをレンダリングします。
`_overview.php` というビューファイルをレンダリングします。 ビューでは `$this`[[yii\base\View|ビュー]] コンポーネントを参照することを思い出してください。
ビューでは `$this`[[yii\base\View|ビュー]] コンポーネントを参照することを思い出してください:
```php ```php
<?= $this->render('_overview') ?> <?= $this->render('_overview') ?>
...@@ -237,8 +214,7 @@ echo \Yii::$app->view->renderFile('@app/views/site/license.php'); ...@@ -237,8 +214,7 @@ echo \Yii::$app->view->renderFile('@app/views/site/license.php');
### 名前付きビュー <a name="named-views"></a> ### 名前付きビュー <a name="named-views"></a>
ビューをレンダリングするとき、ビューを指定するのには、ビューの名前か、 ビューをレンダリングするとき、ビューを指定するのには、ビューの名前か、ビューファイルのパス/エイリアスか、どちらかを使うことが出来ます。
ビューファイルのパス/エイリアスか、どちらかを使うことが出来ます。
たいていの場合は、より簡潔で柔軟な前者を使います。 たいていの場合は、より簡潔で柔軟な前者を使います。
名前を使って指定されるビューを *名前付きビュー* と呼びます。 名前を使って指定されるビューを *名前付きビュー* と呼びます。
...@@ -246,42 +222,32 @@ echo \Yii::$app->view->renderFile('@app/views/site/license.php'); ...@@ -246,42 +222,32 @@ echo \Yii::$app->view->renderFile('@app/views/site/license.php');
* ビュー名はファイル拡張子を省略することが出来ます。その場合、`.php` が拡張子として使われます。 * ビュー名はファイル拡張子を省略することが出来ます。その場合、`.php` が拡張子として使われます。
例えば、`about` というビュー名は `about.php` というファイル名に対応します。 例えば、`about` というビュー名は `about.php` というファイル名に対応します。
* ビュー名が二つのスラッシュ (`//`) で始まる場合は、対応するビューファイルのパスは `@app/views/ViewName` * ビュー名が二つのスラッシュ (`//`) で始まる場合は、対応するビューファイルのパスは `@app/views/ViewName` となります。
となります。つまり、ビューファイルは [[yii\base\Application::viewPath|アプリケーションのビューパス]] つまり、ビューファイルは [[yii\base\Application::viewPath|アプリケーションのビューパス]] の下で探されます。
の下で探されます。例えば、`//site/about``@app/views/site/about.php` へと解決されます。 例えば、`//site/about``@app/views/site/about.php` へと解決されます。
* ビュー名が一つのスラッシュ (`/`) で始まる場合は、ビューファイルのパスは、ビュー名の前に、現在 * ビュー名が一つのスラッシュ (`/`) で始まる場合は、ビューファイルのパスは、ビュー名の前に、現在アクティブな [モジュール](structure-modules.md)[[yii\base\Module::viewPath|ビューパス]] を置くことによって形成されます。
アクティブな [モジュール](structure-modules.md)[[yii\base\Module::viewPath|ビューパス]] アクティブなモジュールが無い場合は、`@app/views/ViewName` が使用されます。
を置くことによって形成されます。アクティブなモジュールが無い場合は、`@app/views/ViewName` 例えば、`/user/create` は、現在アクティブなモジュールが `user` である場合は、`@app/modules/user/views/user/create.php` へと解決されます。
が使用されます。例えば、`/user/create` は、現在アクティブなモジュールが `user` である場合は、 アクティブなモジュールが無い場合は、ビューファイルのパスは `@app/views/user/create.php` となります。
`@app/modules/user/views/user/create.php` へと解決されます。アクティブなモジュールが無い場合は、 * ビューが [[yii\base\View::context|コンテキスト]] を伴ってレンダリングされ、そのコンテキストが [[yii\base\ViewContextInterface]] を実装している場合は、
ビューファイルのパスは `@app/views/user/create.php` となります。 ビューファイルのパスは、コンテキストの [[yii\base\ViewContextInterface::getViewPath()|ビューパス]] をビュー名の前に置くことによって形成されます。
* ビューが [[yii\base\View::context|コンテキスト]] を伴ってレンダリングされ、そのコンテキストが これは、主として、コントローラとウィジェットの中でレンダリングされるビューに当てはまります。
[[yii\base\ViewContextInterface]] を実装している場合は、ビューファイルのパスは、コンテキストの 例えば、コンテキストが `SiteController` コントローラである場合、`site/about``@app/views/site/about.php` へと解決されます。
[[yii\base\ViewContextInterface::getViewPath()|ビューパス]] をビュー名の前に置くことによって * あるビューが別のビューの中でレンダリングされる場合は、後者のビューファイルを含んでいるディレクトリが前者のビュー名の前に置かれて、実際のビューファイルのパスが形成されます。
形成されます。これは、主として、コントローラとウィジェットの中でレンダリングされるビューに当てはまります。 例えば、`item` は、`@app/views/post/index.php` というビューの中でレンダリングされる場合、`@app/views/post/item` へと解決されます。
例えば、コンテキストが `SiteController` コントローラである場合、`site/about``@app/views/site/about.php`
へと解決されます。 上記の規則によると、コントローラ `app\controllers\PostController` の中で `$this->render('view')` を呼ぶと、実際には、ビューファイル `@app/views/post/view.php` がレンダリングされ、
* あるビューが別のビューの中でレンダリングされる場合は、後者のビューファイルを含んでいるディレクトリが 一方、そのビューの中で `$this->render('_overview')` を呼ぶと、ビューファイル `@app/views/post/_overview.php` がレンダリングされることになります。
前者のビュー名の前に置かれて、実際のビューファイルのパスが形成されます。例えば、`item` は、
`@app/views/post/index.php` というビューの中でレンダリングされる場合、`@app/views/post/item`
へと解決されます。
上記の規則によると、コントローラ `app\controllers\PostController` の中で `$this->render('view')` を呼ぶと、
実際には、ビューファイル `@app/views/post/view.php` がレンダリングされ、一方、そのビューの中で
`$this->render('_overview')` を呼ぶと、ビューファイル `@app/views/post/_overview.php`
がレンダリングされることになります。
### ビューの中でデータにアクセスする <a name="accessing-data-in-views"></a> ### ビューの中でデータにアクセスする <a name="accessing-data-in-views"></a>
ビューの中でデータにアクセスするためのアプローチが二つあります: 「プッシュ」と「プル」です。 ビューの中でデータにアクセスするためのアプローチが二つあります。「プッシュ」と「プル」です。
ビューをレンダリングするメソッドに二番目のパラメータとしてデータを渡すのが「プッシュ」のアプローチです。 ビューをレンダリングするメソッドに二番目のパラメータとしてデータを渡すのが「プッシュ」のアプローチです。
データは、「名前-値」のペアの配列として表されなければなりません。 データは、「名前-値」のペアの配列として表されなければなりません。
ビューがレンダリングされるときに、PHP の `extract()` 関数がこの配列に対して呼び出され、 ビューがレンダリングされるときに、PHP の `extract()` 関数がこの配列に対して呼び出され、ビューの中でこの配列から変数が抽出されます。
ビューの中でこの配列から変数が抽出されます。 例えば、次のコードはコントローラの中でビューをレンダリングしていますが、`report` ビューに二つの変数、すなわち、`$foo = 1``$bar = 2` をプッシュしています。
例えば、次のコードはコントローラの中でビューをレンダリングしていますが、`report` ビューに
二つの変数、すなわち、`$foo = 1``$bar = 2` をプッシュしています。
```php ```php
echo $this->render('report', [ echo $this->render('report', [
...@@ -290,11 +256,10 @@ echo $this->render('report', [ ...@@ -290,11 +256,10 @@ echo $this->render('report', [
]); ]);
``` ```
「プル」のアプローチは、[[yii\base\View|ビューコンポーネント]] またはビューからアクセス出来るその他のオブジェクト (例えば `Yii::$app`) から 「プル」のアプローチは、[[yii\base\View|ビューコンポーネント]] またはビューからアクセス出来るその他のオブジェクト (例えば `Yii::$app`) から積極的にデータを読み出すものです。
積極的にデータを読み出すものです。 下記のコード例のように、ビューの中では `$this->context` という式でコントローラオブジェクトを取得することが出来ます。
下記のコードを例として使って、ビューの中で `$this->context` という式でコントローラオブジェクト その結果、`report` ビューの中で、コントローラの全てのプロパティやメソッドにアクセスすることが出来ます。
を取得することが出来ます。その結果、`report` ビューの中でコントローラの全てのプロパティや 次の例ではコントローラ ID にアクセスしています。
メソッドにアクセスすることが出来ます。次の例ではコントローラ ID にアクセスしています:
```php ```php
The controller ID is: <?= $this->context->id ?> The controller ID is: <?= $this->context->id ?>
...@@ -304,24 +269,20 @@ The controller ID is: <?= $this->context->id ?> ...@@ -304,24 +269,20 @@ The controller ID is: <?= $this->context->id ?>
通常は「プッシュ」アプローチが、ビューでデータにアクセスする方法として推奨されます。 通常は「プッシュ」アプローチが、ビューでデータにアクセスする方法として推奨されます。
なぜなら、ビューのコンテキストオブジェクトに対する依存がより少ないからです。 なぜなら、ビューのコンテキストオブジェクトに対する依存がより少ないからです。
その短所は、常にデータ配列を手作業で作成する必要がある、ということです。 その短所は、常にデータ配列を手作業で作成する必要がある、ということです。
ビューが共有されてさまざまな場所でレンダリングされる場合、その作業が面倒くさくなり、また、 ビューが共有されてさまざまな場所でレンダリングされる場合、その作業が面倒くさくなり、また、間違いも生じやすくなります。
間違いも生じやすくなります。
### ビューの間でデータを共有する <a name="sharing-data-among-views"></a> ### ビューの間でデータを共有する <a name="sharing-data-among-views"></a>
[[yii\base\View|ビューコンポーネント]] が提供する [[yii\base\View::params|params]] プロパティを使うと [[yii\base\View|ビューコンポーネント]] が提供する [[yii\base\View::params|params]] プロパティを使うと、ビューの間でデータを共有することが出来ます。
ビューの間でデータを共有することが出来ます。
例えば、`about` というビューで、次のようなコードを使って、 例えば、`about` というビューで、次のようなコードを使って、パン屑リストの現在の区分を指定することが出来ます。
パン屑リストの現在の区分を指定することが出来ます。
```php ```php
$this->params['breadcrumbs'][] = 'About Us'; $this->params['breadcrumbs'][] = 'About Us';
``` ```
そして、[レイアウト](#layouts) ファイル (これも一つのビューです) の中で、[[yii\base\View::params|params]] そして、[レイアウト](#layouts) ファイル (これも一つのビューです) の中で、[[yii\base\View::params|params]] によって渡されたデータを使って、パン屑リストを表示することが出来ます。
によって渡されたデータを使って、パン屑リストを表示することが出来ます:
```php ```php
<?= yii\widgets\Breadcrumbs::widget([ <?= yii\widgets\Breadcrumbs::widget([
...@@ -334,23 +295,19 @@ $this->params['breadcrumbs'][] = 'About Us'; ...@@ -334,23 +295,19 @@ $this->params['breadcrumbs'][] = 'About Us';
レイアウトは、複数のビューの共通部分をあらわす特殊なタイプのビューです。 レイアウトは、複数のビューの共通部分をあらわす特殊なタイプのビューです。
例えば、たいていのウェブアプリケーションでは、ページは共通のヘッダとフッタを持っています。 例えば、たいていのウェブアプリケーションでは、ページは共通のヘッダとフッタを持っています。
すべてのビューで同じヘッダとフッタを繰り返すことも出来ますが、もっと良い方法は、 すべてのビューで同じヘッダとフッタを繰り返すことも出来ますが、もっと良い方法は、そういうことはレイアウトの中で一度だけして、コンテンツビューのレンダリング結果をレイアウトの中の適切な場所に埋め込むことです。
そういうことはレイアウトの中で一度だけして、コンテンツビューのレンダリング結果を
レイアウトの中の適切な場所に埋め込むことです。
### レイアウトを作成する <a name="creating-layouts"></a> ### レイアウトを作成する <a name="creating-layouts"></a>
レイアウトもまたビューですので、通常のビューと同様な方法で作成することが出来ます。既定では、 レイアウトもまたビューですので、通常のビューと同様な方法で作成することが出来ます。
レイアウトは `@app/views/layouts` ディレクトリに保存されます。[モジュール](structure-modules.md) 既定では、レイアウトは `@app/views/layouts` ディレクトリに保存されます。
の中で使用されるレイアウトについては、[[yii\base\Module::basePath|モジュールディレクトリ]] の下の [モジュール](structure-modules.md) の中で使用されるレイアウトについては、[[yii\base\Module::basePath|モジュールディレクトリ]]
`views/layouts` ディレクトリに保存されるべきものとなります。既定のレイアウトディレクトリは、 の下の `views/layouts` ディレクトリに保存されるべきものとなります。
アプリケーションまたはモジュールの [[yii\base\Module::layoutPath]] プロパティを構成することで 既定のレイアウトディレクトリは、アプリケーションまたはモジュールの [[yii\base\Module::layoutPath]] プロパティを構成することでカスタマイズすることが出来ます。
カスタマイズすることが出来ます。
次の例は、レイアウトがどのようなものであるかを示すものです。説明のために、レイアウトの中のコードを 次の例は、レイアウトがどのようなものであるかを示すものです。説明のために、レイアウトの中のコードを大幅に単純化していることに注意してください。
大幅に単純化していることに注意してください。実際には、ヘッドのタグやメインメニューなど、もっと 実際には、ヘッドのタグやメインメニューなど、もっと多くのコンテンツを追加する必要があるでしょう。
多くのコンテンツを追加する必要があるでしょう。
```php ```php
<?php <?php
...@@ -379,13 +336,11 @@ use yii\helpers\Html; ...@@ -379,13 +336,11 @@ use yii\helpers\Html;
<?php $this->endPage() ?> <?php $this->endPage() ?>
``` ```
見ると分かるように、レイアウトはすべてのページに共通な HTML タグを生成しています。`<body>` 見ると分かるように、レイアウトはすべてのページに共通な HTML タグを生成しています。`<body>` セクションの中でレイアウトが `$content` という変数をエコーしていますが、
セクションの中でレイアウトが `$content` という変数をエコーしていますが、これは、 これは、コンテンツビューのレンダリング結果を表すものであり、[[yii\base\Controller::render()]] が呼ばれるときに、レイアウトにプッシュされるものです。
コンテンツビューのレンダリング結果を表すものであり、[[yii\base\Controller::render()]] が呼ばれるときに、レイアウトにプッシュされるものです。
上記のコードに示されているように、たいていのレイアウトは次に挙げるメソッドを呼び出すべきです。 上記のコードに示されているように、たいていのレイアウトは次に挙げるメソッドを呼び出すべきです。
これらのメソッドは主としてレンダリングの過程に関するイベントをトリガして、他の場所で登録された これらのメソッドは主としてレンダリングの過程に関するイベントをトリガして、他の場所で登録されたスクリプトやタグが、メソッドが呼ばれた場所に正しく注入されるようにするためのものです。
スクリプトやタグが、メソッドが呼ばれた場所に正しく注入されるようにするためのものです。
- [[yii\base\View::beginPage()|beginPage()]]: このメソッドがレイアウトの一番初めに呼ばれるべきです。 - [[yii\base\View::beginPage()|beginPage()]]: このメソッドがレイアウトの一番初めに呼ばれるべきです。
これは、ページの開始を示す [[yii\base\View::EVENT_BEGIN_PAGE|EVENT_BEGIN_PAGE]] イベントをトリガします。 これは、ページの開始を示す [[yii\base\View::EVENT_BEGIN_PAGE|EVENT_BEGIN_PAGE]] イベントをトリガします。
...@@ -395,37 +350,33 @@ use yii\helpers\Html; ...@@ -395,37 +350,33 @@ use yii\helpers\Html;
このメソッドは、ページのレンダリングが完了したときに、登録された head の HTML コード (リンクタグ、メタタグなど) に置き換えられるプレースホルダを生成します。 このメソッドは、ページのレンダリングが完了したときに、登録された head の HTML コード (リンクタグ、メタタグなど) に置き換えられるプレースホルダを生成します。
- [[yii\web\View::beginBody()|beginBody()]]: このメソッドが `<body>` セクションの最初で呼ばれるべきです。 - [[yii\web\View::beginBody()|beginBody()]]: このメソッドが `<body>` セクションの最初で呼ばれるべきです。
このメソッドは [[yii\web\View::EVENT_BEGIN_BODY|EVENT_BEGIN_BODY]] イベントをトリガし、 このメソッドは [[yii\web\View::EVENT_BEGIN_BODY|EVENT_BEGIN_BODY]] イベントをトリガし、
body の開始位置を目的とする登録された HTML コード (JavaScript など) によって置き換えられる body の開始位置を目的とする登録された HTML コード (JavaScript など) によって置き換えられるプレースホルダを生成します。
プレースホルダを生成します。
- [[yii\web\View::endBody()|endBody()]]: このメソッドが `<body`> セクションの最後で呼ばれるべきです。 - [[yii\web\View::endBody()|endBody()]]: このメソッドが `<body`> セクションの最後で呼ばれるべきです。
このメソッドは [[yii\web\View::EVENT_END_BODY|EVENT_END_BODY]] イベントをトリガし、 このメソッドは [[yii\web\View::EVENT_END_BODY|EVENT_END_BODY]] イベントをトリガし、
body の終了位置を目的とする登録された HTML コード (JavaScript など) によって置き換えられる body の終了位置を目的とする登録された HTML コード (JavaScript など) によって置き換えられるプレースホルダを生成します。
プレースホルダを生成します。
### レイアウトでデータにアクセスする <a name="accessing-data-in-layouts"></a> ### レイアウトでデータにアクセスする <a name="accessing-data-in-layouts"></a>
レイアウトの中では、事前定義された二つの変数にアクセス出来ます: `$this``$content` です。前者は、 レイアウトの中では、事前定義された二つの変数、すなわち、`$this``$content` にアクセス出来ます。
通常のビューにおいてと同じく、[[yii\base\View|ビュー]] コンポーネントを参照します。一方、後者は、 前者は、通常のビューにおいてと同じく、[[yii\base\View|ビュー]] コンポーネントを参照します。
コントローラの中で [[yii\base\Controller::render()|render()]] メソッドを呼ぶことによってレンダリングされる、 一方、後者は、コントローラの中で [[yii\base\Controller::render()|render()]] メソッドを呼ぶことによってレンダリングされる、
コンテンツビューのレンダリング結果を含むものです。 コンテンツビューのレンダリング結果を含むものです。
レイアウトの中で他のデータにアクセスする必要があるときは、[ビューの中でデータにアクセスする](#accessing-data-in-views) レイアウトの中で他のデータにアクセスする必要があるときは、[ビューの中でデータにアクセスする](#accessing-data-in-views) の項で説明されている「プル」の方法を使う必要があります。
の項で説明されている「プル」の方法を使う必要があります。コンテンツビューからレイアウトにデータを渡す必要があるときは、 コンテンツビューからレイアウトにデータを渡す必要があるときは、[ビューの間でデータを共有する](#sharing-data-among-views) の項で説明されている方法を使うことが出来ます。
[ビューの間でデータを共有する](#sharing-data-among-views) の項で説明されている方法を使うことが出来ます。
### レイアウトを使う <a name="using-layouts"></a> ### レイアウトを使う <a name="using-layouts"></a>
[コントローラでのレンダリング](#rendering-in-controllers) の項で説明されているように、コントローラの中で [コントローラでのレンダリング](#rendering-in-controllers) の項で説明されているように、コントローラの中で
[[yii\base\Controller::render()|render()]] メソッドを呼んでビューをレンダリングすると、レンダリング結果に [[yii\base\Controller::render()|render()]] メソッドを呼んでビューをレンダリングすると、レンダリング結果にレイアウトが適用されます。
レイアウトが適用されます。既定では、`@app/views/layouts/main.php` というレイアウトが使用されます。 既定では、`@app/views/layouts/main.php` というレイアウトが使用されます。
[[yii\base\Application::layout]] または [[yii\base\Controller::layout]] のどちらかを構成することによって、異なるレイアウトを [[yii\base\Application::layout]] または [[yii\base\Controller::layout]] のどちらかを構成することによって、異なるレイアウトを使うことが出来ます。
使うことが出来ます。前者は全てのコントローラによって使用されるレイアウトを決定するものですが、後者は個々のコントローラについて 前者は全てのコントローラによって使用されるレイアウトを決定するものですが、後者は個々のコントローラについて前者をオーバーライドするものです。
前者をオーバーライドするものです。例えば、次のコードは、`post` コントローラがビューをレンダリングするときに 例えば、次のコードは、`post` コントローラがビューをレンダリングするときに `@app/views/layouts/post.php` をレイアウトとして使うようにするものです。
`@app/views/layouts/post.php` をレイアウトとして使うようにするものです。その他のコントローラは、`layout` プロパティに その他のコントローラは、`layout` プロパティに触れられていないと仮定すると、引き続き既定の `@app/views/layouts/main.php` をレイアウトとして使います。
触れられていないと仮定すると、引き続き既定の `@app/views/layouts/main.php` をレイアウトとして使います。
```php ```php
namespace app\controllers; namespace app\controllers;
...@@ -440,13 +391,11 @@ class PostController extends Controller ...@@ -440,13 +391,11 @@ class PostController extends Controller
} }
``` ```
モジュールに属するコントローラについては、モジュールの [[yii\base\Module::layout|layout]] プロパティを構成して、モジュール内の モジュールに属するコントローラについては、モジュールの [[yii\base\Module::layout|layout]] プロパティを構成して、モジュール内のコントローラに特定のレイアウトを使用することも出来ます。
コントローラに特定のレイアウトを使用することも出来ます。
`layout` プロパティは異なるレベル (コントローラ、モジュール、アプリケーション) で構成されうるものですので、 `layout` プロパティは異なるレベル (コントローラ、モジュール、アプリケーション) で構成されうるものですので、Yii は舞台裏で二つのステップを踏んで、特定のコントローラで実際に使われるレイアウトファイルが何であるかを決定します。
Yii は舞台裏で二つのステップを践んで、特定のコントローラで実際に使われるレイアウトファイルが何であるかを決定します。
最初のステップで、Yii はレイアウトの値とコンテキストモジュールを決定します: 最初のステップで、Yii はレイアウトの値とコンテキストモジュールを決定します。
- コントローラの [[yii\base\Controller::layout]] プロパティが null でないときは、それをレイアウトの値として使い、 - コントローラの [[yii\base\Controller::layout]] プロパティが null でないときは、それをレイアウトの値として使い、
コントローラの [[yii\base\Controller::module|モジュール]] をコンテキストモジュールとして使う。 コントローラの [[yii\base\Controller::module|モジュール]] をコンテキストモジュールとして使う。
...@@ -456,7 +405,7 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -456,7 +405,7 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
そのようなモジュールが見つからなかったときは、レイアウトは適用されないということを意味する。 そのようなモジュールが見つからなかったときは、レイアウトは適用されないということを意味する。
第二のステップでは、最初のステップで決定されたレイアウトの値とコンテキストモジュールに従って、実際のレイアウトファイルを決定します。 第二のステップでは、最初のステップで決定されたレイアウトの値とコンテキストモジュールに従って、実際のレイアウトファイルを決定します。
レイアウトの値は下記のいずれかであり得ます: レイアウトの値は下記のいずれかであり得ます。
- パスエイリアス (例えば、`@app/views/layouts/main`)。 - パスエイリアス (例えば、`@app/views/layouts/main`)。
- 絶対パス (例えば、`/main`): すなわち、スラッシュで始まるレイアウトの値の場合。 - 絶対パス (例えば、`/main`): すなわち、スラッシュで始まるレイアウトの値の場合。
...@@ -471,12 +420,12 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -471,12 +420,12 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
### 入れ子のレイアウト <a name="nested-layouts"></a> ### 入れ子のレイアウト <a name="nested-layouts"></a>
ときとして、あるレイアウトの中に別のレイアウトを入れたい場合があるでしょう。例えば、 ときとして、あるレイアウトの中に別のレイアウトを入れたい場合があるでしょう。
ウェブサイトの別々のセクションにおいて、違うレイアウトを使いたいけれども、 例えば、ウェブサイトの別々のセクションにおいて、違うレイアウトを使いたいけれども、
それらのレイアウトは全て、全体としての HTML5 ページ構造を生成する同一の基本レイアウトを それらのレイアウトは全て、全体としての HTML5 ページ構造を生成する同一の基本レイアウトを共有している、という場合です。
共有している、という場合です。この目的を達することは、次のように、子レイアウトの中で この目的を達することは、次のように、子レイアウトの中で
[[yii\base\View::beginContent()|beginContent()]] と [[yii\base\View::endContent()|endContent()]] [[yii\base\View::beginContent()|beginContent()]] と [[yii\base\View::endContent()|endContent()]]
を呼ぶことで可能になります: を呼ぶことで可能になります。
```php ```php
<?php $this->beginContent('@app/views/layouts/base.php'); ?> <?php $this->beginContent('@app/views/layouts/base.php'); ?>
...@@ -488,8 +437,8 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -488,8 +437,8 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
上のコードが示すように、子レイアウトのコンテンツは [[yii\base\View::beginContent()|beginContent()]] と 上のコードが示すように、子レイアウトのコンテンツは [[yii\base\View::beginContent()|beginContent()]] と
[[yii\base\View::endContent()|endContent()]] によって囲まれなければなりません。 [[yii\base\View::endContent()|endContent()]] によって囲まれなければなりません。
[[yii\base\View::beginContent()|beginContent()]] に渡されるパラメータは、 [[yii\base\View::beginContent()|beginContent()]] に渡されるパラメータは、親レイアウトで何であるかを指定するものです。
親レイアウトで何であるかを指定するものです。レイアウトのファイルまたはエイリアスのどちらかを使うことが出来ます。 レイアウトのファイルまたはエイリアスのどちらかを使うことが出来ます。
上記のアプローチを使って、2レベル以上のレイアウトを入れ子にすることも出来ます。 上記のアプローチを使って、2レベル以上のレイアウトを入れ子にすることも出来ます。
...@@ -497,16 +446,14 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -497,16 +446,14 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
### ブロックを使う <a name="using-blocks"></a> ### ブロックを使う <a name="using-blocks"></a>
ブロックを使うと、ある場所でビューコンテンツを規定して、別の場所でそれを表示することが可能になります。 ブロックを使うと、ある場所でビューコンテンツを規定して、別の場所でそれを表示することが可能になります。
ブロックはたいていはレイアウトと一緒に使われます。例えば、ブロックをコンテンツビューで定義して、 ブロックはたいていはレイアウトと一緒に使われます。
それをレイアウトで表示する、ということが出来ます。 例えば、ブロックをコンテンツビューで定義して、それをレイアウトで表示する、ということが出来ます。
[[yii\base\View::beginBlock()|beginBlock()]] と [[yii\base\View::endBlock()|endBlock()]] [[yii\base\View::beginBlock()|beginBlock()]] と [[yii\base\View::endBlock()|endBlock()]] を呼んでブロックを定義します。
を呼んでブロックを定義します。
すると、そのブロックを `$view->blocks[$blockID]` によってアクセス出来るようになります。 すると、そのブロックを `$view->blocks[$blockID]` によってアクセス出来るようになります。
ここで `$blockID` は、定義したときにブロックに割り当てたユニークな ID を指します。 ここで `$blockID` は、定義したときにブロックに割り当てたユニークな ID を指します。
次の例は、どのようにブロックを使えば、レイアウトの特定の部分をコンテンツビューで 次の例は、どのようにブロックを使えば、レイアウトの特定の部分をコンテンツビューでカスタマイズすることが出来るかを示すものです。
カスタマイズすることが出来るかを示すものです。
最初に、コンテンツビューで、一つまたは複数のブロックを定義します。 最初に、コンテンツビューで、一つまたは複数のブロックを定義します。
...@@ -528,8 +475,7 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -528,8 +475,7 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
<?php $this->endBlock(); ?> <?php $this->endBlock(); ?>
``` ```
次に、レイアウトビューで、得ることが出来ればブロックをレンダリングし、ブロックが定義されていないときは 次に、レイアウトビューで、得ることが出来ればブロックをレンダリングし、ブロックが定義されていないときは何らかの既定のコンテンツを表示します。
何らかの既定のコンテンツを表示します。
```php ```php
... ...
...@@ -561,9 +507,8 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -561,9 +507,8 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
## ビューコンポーネントを使う <a name="using-view-components"></a> ## ビューコンポーネントを使う <a name="using-view-components"></a>
[[yii\base\View|ビューコンポーネント]] はビューに関連する多くの機能を提供します。 [[yii\base\View|ビューコンポーネント]] はビューに関連する多くの機能を提供します。
ビューコンポーネントは、[[yii\base\View]] またはその子クラスの個別のインスタンスを作成することによっても取得できますが、 ビューコンポーネントは、[[yii\base\View]] またはその子クラスの個別のインスタンスを作成することによっても取得できますが、たいていの場合は、`view` アプリケーションコンポーネントを主として使うことになるでしょう。
たいていの場合は、`view` アプリケーションコンポーネントを主として使うことになるでしょう。 このコンポーネントは [アプリケーションの構成情報](structure-applications.md#application-configurations) の中で、次のようにして構成することが出来ます。
このコンポーネントは [アプリケーションのコンフィギュレーション](structure-applications.md#application-configurations) の中で、次のようにして構成することが出来ます:
```php ```php
[ [
...@@ -577,8 +522,7 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -577,8 +522,7 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
] ]
``` ```
ビューコンポーネントは、次に挙げるビュー関連の有用な機能を提供します。それぞれについては、 ビューコンポーネントは、次に挙げるビュー関連の有用な機能を提供します。それぞれについては、独立の節で更に詳細に説明されます。
独立の節で更に詳細に説明されます。
* [テーマ](output-theming.md): ウェブサイトのテーマを開発し変更することを可能にします。 * [テーマ](output-theming.md): ウェブサイトのテーマを開発し変更することを可能にします。
* [フラグメントキャッシュ](caching-fragment.md): ウェブページの中の断片をキャッシュすることを可能にします。 * [フラグメントキャッシュ](caching-fragment.md): ウェブページの中の断片をキャッシュすることを可能にします。
...@@ -586,17 +530,16 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ ...@@ -586,17 +530,16 @@ Yii 縺ッ闊槫床陬上〒莠後▽縺ョ繧ケ繝ャ繝励r霍オ繧薙〒縲∫音螳壹繧ウ繝ウ繝医Ο繝シ
* [アセットバンドルの取り扱い](structure-assets.md): [アセットバンドル](structure-assets.md) の登録とレンダリングをサポートします。 * [アセットバンドルの取り扱い](structure-assets.md): [アセットバンドル](structure-assets.md) の登録とレンダリングをサポートします。
* [代替のテンプレートエンジン](tutorial-template-engines.md): [Twig](http://twig.sensiolabs.org/)[Smarty](http://www.smarty.net/) など、他のテンプレートエンジンを使用することを可能にします。 * [代替のテンプレートエンジン](tutorial-template-engines.md): [Twig](http://twig.sensiolabs.org/)[Smarty](http://www.smarty.net/) など、他のテンプレートエンジンを使用することを可能にします。
次に挙げるマイナーではあっても有用な諸機能は、ウェブページを開発するときに頻繁に使用するでしょう: 次に挙げるマイナーではあっても有用な諸機能は、ウェブページを開発するときに頻繁に使用するでしょう。
### ページタイトルを設定する <a name="setting-page-titles"></a> ### ページタイトルを設定する <a name="setting-page-titles"></a>
どんなウェブページにもタイトルが無ければなりません。通常、タイトルタグは [layout](#layouts) の中で表示されます。しかし、 どんなウェブページにもタイトルが無ければなりません。通常、タイトルタグは [layout](#layouts) の中で表示されます。
実際においては、多くの場合、タイトルはレイアウトではなくコンテンツビューで決められます。この問題を解決するために、 しかし、実際においては、多くの場合、タイトルはレイアウトではなくコンテンツビューで決められます。
[[yii\web\View]] は、タイトル情報をコンテンツビューからレイアウトに渡すための [[yii\web\View::title|title]] プロパティを この問題を解決するために、[[yii\web\View]] は、タイトル情報をコンテンツビューからレイアウトに渡すための [[yii\web\View::title|title]] プロパティを提供しています。
提供しています。
この機能を利用するためには、全てのコンテンツビューにおいて、次のようにタイトルを設定します: この機能を利用するためには、全てのコンテンツビューにおいて、次のようにタイトルを設定します。
```php ```php
<?php <?php
...@@ -604,7 +547,7 @@ $this->title = 'My page title'; ...@@ -604,7 +547,7 @@ $this->title = 'My page title';
?> ?>
``` ```
そして、レイアウトビューで、`<head>` セクションに次のコードを忘れずに書くようにします: そして、レイアウトビューで、`<head>` セクションに次のコードを忘れずに書くようにします。
```php ```php
<title><?= Html::encode($this->title) ?></title> <title><?= Html::encode($this->title) ?></title>
...@@ -613,11 +556,10 @@ $this->title = 'My page title'; ...@@ -613,11 +556,10 @@ $this->title = 'My page title';
### メタタグを登録する <a name="registering-meta-tags"></a> ### メタタグを登録する <a name="registering-meta-tags"></a>
ウェブページは、通常、いろいろな関係者によって必要とされるさまざまなメタタグを生成する必要があります。ページタイトルと同じように、 ウェブページは、通常、いろいろな関係者によって必要とされるさまざまなメタタグを生成する必要があります。
タグは `<head>` セクションに出現して、通常はレイアウトの中で生成されます。 ージタイトルと同じように、メタタグは `<head>` セクションに出現して、通常はレイアウトの中で生成されます。
どのようなメタタグを生成するかをコンテンツビューの中で指定したい場合は、下記のように、 どのようなメタタグを生成するかをコンテンツビューの中で指定したい場合は、下記のように、[[yii\web\View::registerMetaTag()]] をコンテンツビューの呼ぶことが出来ます。
[[yii\web\View::registerMetaTag()]] をコンテンツビューの呼ぶことが出来ます:
```php ```php
<?php <?php
...@@ -625,20 +567,17 @@ $this->registerMetaTag(['name' => 'keywords', 'content' => 'yii, framework, php' ...@@ -625,20 +567,17 @@ $this->registerMetaTag(['name' => 'keywords', 'content' => 'yii, framework, php'
?> ?>
``` ```
上記のコードは、ビューコンポーネントによって "keywords" メタタグを登録するものです。登録されたメタタグは、 上記のコードは、ビューコンポーネントによって "keywords" メタタグを登録するものです。登録されたメタタグは、レイアウトがレンダリングを完了した後でレンダリングされます。
レイアウトがレンダリングを完了した後でレンダリングされます。すなわち、レイアウトの中で [[yii\web\View::head()]] すなわち、レイアウトの中で [[yii\web\View::head()]] を呼び出した場所に、次の HTML コードが生成されて挿入されます。
を呼び出した場所に、次の HTML コードが生成されて挿入されます:
```php ```php
<meta name="keywords" content="yii, framework, php"> <meta name="keywords" content="yii, framework, php">
``` ```
[[yii\web\View::registerMetaTag()]] を複数回呼び出した場合は、メタタグが同じものか否かに関係なく、 [[yii\web\View::registerMetaTag()]] を複数回呼び出した場合は、メタタグが同じものか否かに関係なく、複数のメタタグが登録されることに注意してください。
複数のメタタグが登録されることに注意してください。
ある型のメタタグのインスタンスが一つだけになることを保証したい場合は、このメソッドを呼ぶときに第二のパラメータとして ある型のメタタグのインスタンスが一つだけになることを保証したい場合は、このメソッドを呼ぶときに第二のパラメータとしてキーを指定することが出来ます。
キーを指定することが出来ます。例えば、次のコードでは、二つの "description" メタタグを登録していますが、 例えば、次のコードでは、二つの "description" メタタグを登録していますが、二番目のものだけがレンダリングされることになります。
二番目のものだけがレンダリングされることになります。
```html ```html
$this->registerMetaTag(['name' => 'description', 'content' => '俺が Yii で作ったクールなウェブサイトだぜぃ!!'], 'description'); $this->registerMetaTag(['name' => 'description', 'content' => '俺が Yii で作ったクールなウェブサイトだぜぃ!!'], 'description');
...@@ -648,9 +587,10 @@ $this->registerMetaTag(['name' => 'description', 'content' => '髱「逋ス縺い繝ゥ繧 ...@@ -648,9 +587,10 @@ $this->registerMetaTag(['name' => 'description', 'content' => '髱「逋ス縺い繝ゥ繧
### リンクタグを登録する <a name="registering-link-tags"></a> ### リンクタグを登録する <a name="registering-link-tags"></a>
[メタタグ](#registering-meta-tags) と同じように、リンクタグも多くの場合において有用なものです。例えば、favicon をカスタマイズしたり、 [メタタグ](#registering-meta-tags) と同じように、リンクタグも多くの場合において有用なものです。
RSS フィードを指し示したり、OpenID を別のサーバに委任したり、等々。リンクタグも、[[yii\web\View::registerLinkTag()]] を使って、 例えば、favicon をカスタマイズしたり、RSS フィードを指し示したり、OpenID を別のサーバに委任したり、等々。
メタタグと同じような方法で取り扱うことが出来ます。例えば、コンテンツビューにおいて、次のようにしてリンクタグを登録することが出来ます。 リンクタグも、[[yii\web\View::registerLinkTag()]] を使って、メタタグと同じような方法で取り扱うことが出来ます。
例えば、コンテンツビューにおいて、次のようにしてリンクタグを登録することが出来ます。
```php ```php
$this->registerLinkTag([ $this->registerLinkTag([
...@@ -674,20 +614,18 @@ $this->registerLinkTag([ ...@@ -674,20 +614,18 @@ $this->registerLinkTag([
## ビューのイベント <a name="view-events"></a> ## ビューのイベント <a name="view-events"></a>
[[yii\base\View|ビューコンポーネント]] はビューをレンダリングする過程においていくつかのイベントをトリガします。 [[yii\base\View|ビューコンポーネント]] はビューをレンダリングする過程においていくつかのイベントをトリガします。
これらのイベントに反応することによって、ビューにコンテンツを注入したり、 これらのイベントに反応することによって、ビューにコンテンツを注入したり、エンドユーザに送信される前にレンダリング結果を加工したりすることが出来ます。
エンドユーザに送信される前にレンダリング結果を加工したりすることが出来ます。
- [[yii\base\View::EVENT_BEFORE_RENDER|EVENT_BEFORE_RENDER]]: コントローラでファイルをレンダリングする前にトリガされます。 - [[yii\base\View::EVENT_BEFORE_RENDER|EVENT_BEFORE_RENDER]]: コントローラでファイルをレンダリングする前にトリガされます。
このイベントのハンドラは、[[yii\base\ViewEvent::isValid]] を false にセットして、レンダリングのプロセスをキャンセルすることが出来ます。 このイベントのハンドラは、[[yii\base\ViewEvent::isValid]] を false にセットして、レンダリングのプロセスをキャンセルすることが出来ます。
- [[yii\base\View::EVENT_AFTER_RENDER|EVENT_AFTER_RENDER]]: ファイルのレンダリングの後、[[yii\base\View::afterRender()]] を呼ぶことによってトリガされます。 - [[yii\base\View::EVENT_AFTER_RENDER|EVENT_AFTER_RENDER]]: ファイルのレンダリングの後、[[yii\base\View::afterRender()]] を呼ぶことによってトリガされます。
このイベントのハンドラは、レンダリング結果を [[yii\base\ViewEvent::output]] によって取得することが出来、 このイベントのハンドラは、レンダリング結果をプロパティ [[yii\base\ViewEvent::output]] を通じて取得して、それを修正してレンダリング結果を変更することが出来ます。
このプロパティを修正してレンダリング結果を変更することが出来ます。
- [[yii\base\View::EVENT_BEGIN_PAGE|EVENT_BEGIN_PAGE]]: レイアウトの中で [[yii\base\View::beginPage()]] を呼ぶことによってトリガされます。 - [[yii\base\View::EVENT_BEGIN_PAGE|EVENT_BEGIN_PAGE]]: レイアウトの中で [[yii\base\View::beginPage()]] を呼ぶことによってトリガされます。
- [[yii\base\View::EVENT_END_PAGE|EVENT_END_PAGE]]: レイアウトの中で [[yii\base\View::endPage()]] を呼ぶことによってトリガされます。 - [[yii\base\View::EVENT_END_PAGE|EVENT_END_PAGE]]: レイアウトの中で [[yii\base\View::endPage()]] を呼ぶことによってトリガされます。
- [[yii\web\View::EVENT_BEGIN_BODY|EVENT_BEGIN_BODY]]: レイアウトの中で [[yii\web\View::beginBody()]] を呼ぶことによってトリガされます。 - [[yii\web\View::EVENT_BEGIN_BODY|EVENT_BEGIN_BODY]]: レイアウトの中で [[yii\web\View::beginBody()]] を呼ぶことによってトリガされます。
- [[yii\web\View::EVENT_END_BODY|EVENT_END_BODY]]: レイアウトの中で [[yii\web\View::endBody()]] を呼ぶことによってトリガされます。 - [[yii\web\View::EVENT_END_BODY|EVENT_END_BODY]]: レイアウトの中で [[yii\web\View::endBody()]] を呼ぶことによってトリガされます。
例えば、次のコードはページの body の最後に現在の日付を注入するものです: 例えば、次のコードはページの body の最後に現在の日付を注入するものです。
```php ```php
\Yii::$app->view->on(View::EVENT_END_BODY, function () { \Yii::$app->view->on(View::EVENT_END_BODY, function () {
...@@ -698,10 +636,9 @@ $this->registerLinkTag([ ...@@ -698,10 +636,9 @@ $this->registerLinkTag([
## 静的なページをレンダリングする <a name="rendering-static-pages"></a> ## 静的なページをレンダリングする <a name="rendering-static-pages"></a>
静的なページというのは、主たるコンテンツのほとんどが静的なもので、コントローラからプッシュされる動的なデータに 静的なページというのは、主たるコンテンツのほとんどが静的なもので、コントローラからプッシュされる動的なデータにアクセスする必要がないページを指します。
アクセスする必要がないページを指します。
静的なページは、そのコードをビューに置き、そして、コントローラで次のようなコードを使うと表示することが出来ます: 静的なページは、そのコードをビューに置き、そして、コントローラで次のようなコードを使うと表示することが出来ます。
```php ```php
public function actionAbout() public function actionAbout()
...@@ -732,8 +669,7 @@ class SiteController extends Controller ...@@ -732,8 +669,7 @@ class SiteController extends Controller
} }
``` ```
このようにすると、ディレクトリ `@app/views/site/pages` の下に `about` という名前のビューを作成したときに、 このようにすると、ディレクトリ `@app/views/site/pages` の下に `about` という名前のビューを作成したときに、次の URL によってこのビューを表示することが出来るようになります。
次の URL によってこのビューを表示することが出来るようになります:
``` ```
http://localhost/index.php?r=site/page&view=about http://localhost/index.php?r=site/page&view=about
...@@ -748,18 +684,17 @@ http://localhost/index.php?r=site/page&view=about ...@@ -748,18 +684,17 @@ http://localhost/index.php?r=site/page&view=about
ビューはエンドユーザが望む形式でモデルを表現することに対して責任を持ちます。一般的に、ビューは ビューはエンドユーザが望む形式でモデルを表現することに対して責任を持ちます。一般的に、ビューは
* 主として表示目的のコードを含むべきです。例えば、HTML、そしてデータをたどり、書式化してレンダリングする簡単な PHP コードなど。 * 主として表示目的のコードを含むべきです。例えば、HTML、または、データをたどって書式化してレンダリングする簡単な PHP コードなど。
* DB クエリを実行するコードは含むべきではありません。そのようなコードはモデルの中で実行されるべきです。 * DB クエリを実行するコードは含むべきではありません。そのようなコードはモデルの中で実行されるべきです。
* `$_GET``$_POST` のようなリクエストデータに直接アクセスするべきではありません。それはコントローラの仕事です。 * `$_GET``$_POST` のようなリクエストデータに直接アクセスするべきではありません。それはコントローラの仕事です。
リクエストデータが必要な場合は、コントローラからビューにプッシュされるべきです。 リクエストデータが必要な場合は、コントローラからビューにプッシュされるべきです。
* モデルのプロパティを読み出すことが出来ます。しかし、それを修正するべきではありません。 * モデルのプロパティを読み出すことが出来ます。しかし、それを修正するべきではありません。
ビューを管理しやすいものにするために、複雑すぎるビューや、冗長なコードをあまりに多く含むビューを作ることは避けましょう。 ビューを管理しやすいものにするために、複雑すぎるビューや、冗長なコードをあまりに多く含むビューを作ることは避けましょう。
この目的を達するために、次のテクニックを使うことが出来ます: この目的を達するために、次のテクニックを使うことが出来ます。
* 共通の表示セクション (ページのヘッダやフッタなど) を表すために [レイアウト](#layouts) を使う。 * 共通の表示セクション (ページのヘッダやフッタなど) を表すために [レイアウト](#layouts) を使う。
* 複雑なビューはいくつかの小さなビューに分割する。既に説明したレンダリングのメソッドを使えば、 * 複雑なビューはいくつかの小さなビューに分割する。既に説明したレンダリングのメソッドを使えば、小さなビューをレンダリングして大きなビューを組み上げることが出来る。
小さなビューをレンダリングして大きなビューを組み上げることが出来る。
* ビューの構成要素として [ウィジェット](structure-widgets.md) を使う。 * ビューの構成要素として [ウィジェット](structure-widgets.md) を使う。
* ビューでデータを変換し書式化するためのヘルパークラスを作成して使う。 * ビューでデータを変換し書式化するためのヘルパクラスを作成して使う。
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
============ ============
ウィジェットは、[ビュー](structure-views.md) で使用される再利用可能な構成ブロックで、 ウィジェットは、[ビュー](structure-views.md) で使用される再利用可能な構成ブロックで、
複雑かつコンフィギュレーション可能なユーザインタフェイス要素をオブジェクト指向のやり方で作成するためのものです。 複雑かつ構成可能なユーザインタフェイス要素をオブジェクト指向のやり方で作成するためのものです。
例えば、日付選択ウィジェットを使うと、入力として日付を選択することを可能にする素敵なデイトピッカーを生成することが出来ます。 例えば、日付選択ウィジェットを使うと、入力として日付を選択することを可能にする素敵なデイトピッカーを生成することが出来ます。
このとき、あなたがしなければならないことは、次のようなコードをビューに挿入することだけです: このとき、あなたがしなければならないことは、次のようなコードをビューに挿入することだけです:
...@@ -13,8 +13,8 @@ use yii\jui\DatePicker; ...@@ -13,8 +13,8 @@ use yii\jui\DatePicker;
<?= DatePicker::widget(['name' => 'date']) ?> <?= DatePicker::widget(['name' => 'date']) ?>
``` ```
数多くのウィジェットが Yii にバンドルされています。例えば、[[yii\widgets\ActiveForm|アクティブフォーム]] や、 数多くのウィジェットが Yii にバンドルされています。
[[yii\widgets\Menu|メニュー]]、[jQuery UI ウィジェット](widget-jui.md)[Twitter Bootstrap ウィジェット](widget-bootstrap.md) などです。 例えば、[[yii\widgets\ActiveForm|アクティブフォーム]] や、[[yii\widgets\Menu|メニュー]]、[jQuery UI ウィジェット](widget-jui.md)[Twitter Bootstrap ウィジェット](widget-bootstrap.md) などです。
下記では、ウィジェットに関する基本的な知識の手引きをします。 下記では、ウィジェットに関する基本的な知識の手引きをします。
特定のウィジェットの使い方について学ぶ必要がある場合は、クラス API ドキュメントを参照してください。 特定のウィジェットの使い方について学ぶ必要がある場合は、クラス API ドキュメントを参照してください。
...@@ -23,9 +23,8 @@ use yii\jui\DatePicker; ...@@ -23,9 +23,8 @@ use yii\jui\DatePicker;
ウィジェットは主として [ビュー](structure-views.md) で使われます。 ウィジェットは主として [ビュー](structure-views.md) で使われます。
ビューでウィジェットを使うためには、[[yii\base\Widget::widget()]] メソッドを使うことが出来ます。 ビューでウィジェットを使うためには、[[yii\base\Widget::widget()]] メソッドを使うことが出来ます。
このメソッドは、ウィジェットを初期化するための [コンフィギュレーション](concept-configurations.md) 配列を受け取り、ウィジェットのレンダリング結果を返します。 このメソッドは、ウィジェットを初期化するための [構成情報](concept-configurations.md) 配列を受け取り、ウィジェットのレンダリング結果を返します。
例えば、下記のコードは、日本語を使い、入力を `$model``from_date` 例えば、下記のコードは、日本語を使い、入力を `$model``from_date` 属性に保存するように構成された日付選択ウィジェットを挿入するものです。
属性に保存するように構成された日付選択ウィジェットを挿入するものです。
```php ```php
<?php <?php
...@@ -41,8 +40,8 @@ use yii\jui\DatePicker; ...@@ -41,8 +40,8 @@ use yii\jui\DatePicker;
]) ?> ]) ?>
``` ```
ウィジェットの中には、コンテンツのブロックを受け取ることが出来るものもあります。その場合、コンテンツのブロックは ウィジェットの中には、コンテンツのブロックを受け取ることが出来るものもあります。
[[yii\base\Widget::begin()]] と [[yii\base\Widget::end()]] の呼び出しの間に包むようにしなければなりません。 その場合、コンテンツのブロックは [[yii\base\Widget::begin()]] と [[yii\base\Widget::end()]] の呼び出しの間に包むようにしなければなりません。
例えば、次のコードは [[yii\widgets\ActiveForm]] ウィジェットを使ってログインフォームを生成するものです。 例えば、次のコードは [[yii\widgets\ActiveForm]] ウィジェットを使ってログインフォームを生成するものです。
このウィジェットは、`begin()``end()` が呼ばれる場所で、それぞれ、開始と終了の `<form>` タグを生成します。 このウィジェットは、`begin()``end()` が呼ばれる場所で、それぞれ、開始と終了の `<form>` タグを生成します。
その間に置かれたものは全てそのままレンダリングされます。 その間に置かれたものは全てそのままレンダリングされます。
...@@ -66,17 +65,15 @@ use yii\helpers\Html; ...@@ -66,17 +65,15 @@ use yii\helpers\Html;
<?php ActiveForm::end(); ?> <?php ActiveForm::end(); ?>
``` ```
[[yii\base\Widget::widget()]] がウィジェットのレンダリング結果を返すのとは違って、[[yii\base\Widget::begin()]] メソッドが [[yii\base\Widget::widget()]] がウィジェットのレンダリング結果を返すのとは違って、[[yii\base\Widget::begin()]] メソッドがウィジェットのインスタンスを返すことに注意してください。
ウィジェットのインスタンスを返すことに注意してください。返されたウィジェットのインスタンスを使って、ウィジェットのコンテンツを 返されたウィジェットのインスタンスを使って、ウィジェットのコンテンツを構築することが出来ます。
構築することが出来ます。
## ウィジェットを作成する <a name="creating-widgets"></a> ## ウィジェットを作成する <a name="creating-widgets"></a>
ウィジェットを作成するためには、[[yii\base\Widget]] を拡張して、[[yii\base\Widget::init()]] および/または [[yii\base\Widget::run()]] ウィジェットを作成するためには、[[yii\base\Widget]] を拡張して、[[yii\base\Widget::init()]] および/または [[yii\base\Widget::run()]] メソッドをオーバーライドします。
メソッドをオーバーライドします。通常、`init()` メソッドはウィジェットのプロパティを正規化するコードを含むべきものであり、 通常、`init()` メソッドはウィジェットのプロパティを正規化するコードを含むべきものであり、`run()` メソッドはウィジェットのレンダリング結果を生成するコードを含むべきものです。
`run()` メソッドはウィジェットのレンダリング結果を生成するコードを含むべきものです。レンダリング結果は、直接に "echo" レンダリング結果は、直接に "echo" しても、`run()` の返り値として文字列として返しても構いません。
しても、`run()` の返り値として文字列として返しても構いません。
次の例では、`HelloWidget``message` プロパティとして割り当てられたコンテンツを HTML エンコードして表示します。 次の例では、`HelloWidget``message` プロパティとして割り当てられたコンテンツを HTML エンコードして表示します。
プロパティがセットされていない場合は、デフォルトとして "Hello World" を表示します。 プロパティがセットされていない場合は、デフォルトとして "Hello World" を表示します。
...@@ -115,8 +112,7 @@ use app\components\HelloWidget; ...@@ -115,8 +112,7 @@ use app\components\HelloWidget;
<?= HelloWidget::widget(['message' => 'おはよう']) ?> <?= HelloWidget::widget(['message' => 'おはよう']) ?>
``` ```
下記は `HelloWidget` の変種で、`begin()``end()` の間に包まれたコンテンツを受け取り、それを 下記は `HelloWidget` の変種で、`begin()``end()` の間に包まれたコンテンツを受け取り、それを HTML エンコードして表示するものです。
HTML エンコードして表示するものです。
```php ```php
namespace app\components; namespace app\components;
...@@ -140,12 +136,10 @@ class HelloWidget extends Widget ...@@ -140,12 +136,10 @@ class HelloWidget extends Widget
} }
``` ```
ご覧のように、`init()` の中で PHP の出力バッファが開始され、`init()``run()` の呼び出しの間の全ての出力がキャプチャされ、 ご覧のように、`init()` の中で PHP の出力バッファが開始され、`init()``run()` の呼び出しの間の全ての出力がキャプチャされ、`run()` の中で処理されて返されます。
`run()` の中で処理されて返されます。
> Info|情報: [[yii\base\Widget::begin()]] を呼ぶと、ウィジェットの新しいインスタンスが作成され、ウィジェットのコンストラクタの > Info|情報: [[yii\base\Widget::begin()]] を呼ぶと、ウィジェットの新しいインスタンスが作成され、ウィジェットのコンストラクタの最後で `init()` メソッドが呼ばれます。
最後で `init()` メソッドが呼ばれます。[[yii\base\Widget::end()]] を呼ぶと、`run()` メソッドが呼ばれて、その返り値が `end()` [[yii\base\Widget::end()]] を呼ぶと、`run()` メソッドが呼ばれて、その返り値が `end()` によって echo されます。
によって echo されます。
次のコードは、この `HelloWidget` の新しい変種をどのように使うかを示すものです: 次のコードは、この `HelloWidget` の新しい変種をどのように使うかを示すものです:
...@@ -160,9 +154,10 @@ use app\components\HelloWidget; ...@@ -160,9 +154,10 @@ use app\components\HelloWidget;
<?php HelloWidget::end(); ?> <?php HelloWidget::end(); ?>
``` ```
場合によっては、ウィジェットが大きな固まりのコンテンツを表示する必要があるかもしれません。コンテンツを `run()` 場合によっては、ウィジェットが大きな固まりのコンテンツを表示する必要があるかもしれません。
メソッドの中に埋め込むことも出来ますが、より良い方法は、コンテンツを [ビュー](structure-views.md) の中に置いて、 コンテンツを `run()` メソッドの中に埋め込むことも出来ますが、より良い方法は、コンテンツを [ビュー](structure-views.md)
[[yii\base\Widget::render()]] を呼んでレンダリングすることです。例えば、 の中に置いて、[[yii\base\Widget::render()]] を呼んでレンダリングすることです。
例えば、
```php ```php
public function run() public function run()
...@@ -171,25 +166,24 @@ public function run() ...@@ -171,25 +166,24 @@ public function run()
} }
``` ```
既定では、ウィジェット用のビューは `WidgetPath/views` ディレクトリの中のファイルに保存すべきものです。ここで 既定では、ウィジェット用のビューは `WidgetPath/views` ディレクトリの中のファイルに保存すべきものです。
`WidgetPath` はウィジェットのクラスファイルを含むディレクトリを指します。したがって、上記の例では、ウィジェットクラスが ここで `WidgetPath` はウィジェットのクラスファイルを含むディレクトリを指します。
`@app/components` に配置されていると仮定すると、`@app/components/views/hello.php` というビューファイルがレンダリングされる したがって、上記の例では、ウィジェットクラスが `@app/components` に配置されていると仮定すると、`@app/components/views/hello.php` というビューファイルがレンダリングされることになります。
ことになります。[[yii\base\Widget::getViewPath()]] メソッドをオーバーライドして、ウィジェットのビューファイルを含むディレクトリを [[yii\base\Widget::getViewPath()]] メソッドをオーバーライドして、ウィジェットのビューファイルを含むディレクトリをカスタマイズすることが出来ます。
カスタマイズすることが出来ます。
## 最善の慣行 <a name="best-practices"></a> ## 最善の慣行 <a name="best-practices"></a>
ウィジェットはビューのコードを再利用するためのオブジェクト指向の方法です。 ウィジェットはビューのコードを再利用するためのオブジェクト指向の方法です。
ウィジェットを作成するときでも、MVC パターンに従うべきです。一般的に言うと、ロジックはウィジェットクラスに保持し、 ウィジェットを作成するときでも、MVC パターンに従うべきです。
表現は [ビュー](structure-views.md) に保持すべきです。 一般的に言うと、ロジックはウィジェットクラスに保持し、表現は [ビュー](structure-views.md) に保持すべきです。
ウィジェットは自己完結的に設計されるべきです。言い換えると、ウィジェットを使うときに、他に何もしないでも ウィジェットは自己完結的に設計されるべきです。
ビューに挿入することが出来るようにすべきです。この要求は、ウィジェットが CSS、JavaScript、画像などの外部リソースを必要とする場合は、 言い換えると、ウィジェットを使うときに、他に何もしないでもビューに挿入することが出来るようにすべきです。
扱いにくい問題になり得ます。幸いなことに、Yii はこの問題を解決するのに利用することが出来る [アセットバンドル](structure-assets.md) この要求は、ウィジェットが CSS、JavaScript、画像などの外部リソースを必要とする場合は、扱いにくい問題になり得ます。
のサポートを提供しています。 幸いなことに、Yii はこの問題を解決するのに利用することが出来る [アセットバンドル](structure-assets.md) のサポートを提供しています。
ウィジェットがビューコードだけを含む場合は、[ビュー](structure-views.md) と非常に似たものになります。実際のところ、この場合、 ウィジェットがビューコードだけを含む場合は、[ビュー](structure-views.md) と非常に似たものになります。
両者の唯一の違いは、ウィジェットが再配布可能なクラスである一方で、ビューはアプリケーション内に保持することが望ましい 実際のところ、この場合、両者の唯一の違いは、ウィジェットが再配布可能なクラスである一方で、
素の PHP スクリプトである、というぐらいの事です。 ビューはアプリケーション内に保持することが望ましい素の PHP スクリプトである、というぐらいの事です。
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