31 KiB
アプリケーション
アプリケーションは Yii アプリケーションシステム全体の構造とライフサイクルを統制するオブジェクトです。
全ての Yii アプリケーションシステムは、それぞれ、エントリスクリプト において作成され、\Yii::$app という式でグローバルにアクセス可能な、単一のアプリケーションオブジェクトを持ちます。
Info|情報: ガイドの中で「アプリケーション」という言葉は、文脈に応じて、 アプリケーションオブジェクトを意味したり、アプリケーションシステムを意味したりします。
二種類のアプリケーションがあります: すなわち、yii\web\Application と yii\console\Application です。 名前が示すように、前者は主にウェブのリクエストを処理し、後者はコンソールコマンドのリクエストを処理します。
アプリケーションのコンフィギュレーション
エントリスクリプト は、アプリケーションを作成するときに、 下記のように、コンフィギュレーション を読み込んで、それをアプリケーションに適用します:
require(__DIR__ . '/../vendor/autoload.php');
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
// アプリケーションのコンフィギュレーションを読み込む
$config = require(__DIR__ . '/../config/web.php');
// アプリケーションのインスタンスを作成し、コンフィギュレーションを適用する
(new yii\web\Application($config))->run();
通常の コンフィギュレーション と同じように、アプリケーションのコンフィギュレーションは、アプリケーションオブジェクトのプロパティをどのように初期化するかを規定するものです。
アプリケーションのコンフィギュレーションは、たいていは非常に複雑なものですから、通常は、上記の例の web.php ファイルのように、コンフィギュレーションファイル に保管されます。
アプリケーションのプロパティ
アプリケーションのコンフィギュレーションで構成すべき重要なアプリケーションのプロパティは数多くあります。 それらのプロパティの典型的なものは、アプリケーションが走る環境を記述するものです。 例えば、アプリケーションは、どのようにして コントローラ をロードするか、また、どこにテンポラリファイルを保存するかなどを知らなければなりません。 以下において、それらのプロパティを要約します。
必須のプロパティ
どのアプリケーションでも、最低二つのプロパティは構成しなければなりません: すなわち、yii\base\Application::id と yii\base\Application::basePath です。
yii\base\Application::id
yii\base\Application::id プロパティは、アプリケーションを他のアプリケーションから区別するユニークな ID を規定します。 このプロパティは主としてプログラム的に使われます。 必須ではありませんが、最良の相互運用性を確保するために、アプリケーション ID を規定するときに英数字だけを使うことが推奨されます。
yii\base\Application::basePath
yii\base\Application::basePath プロパティは、アプリケーションのルートディレクトリを規定します。
これは、アプリケーションシステムの全ての保護されたソースコードを収容するディレクトリです。
通常、このディレクトリの下に、MVC パターンに対応するソースコードを収容した models、views、controllers などのサブディレクトリがあります。
yii\base\Application::basePath プロパティの構成には、ディレクトリパスを使っても、パスエイリアス を使っても構いません。
どちらの形式においても、対応するディレクトリが存在しなければなりません。
さもなくば、例外が投げられます。
パスは realpath() 関数を呼び出して正規化されます。
yii\base\Application::basePath プロパティは、しばしば、他の重要なパス (例えば、runtime のパス) を派生させるために使われます。
このため、basePath を示す @app というパスエイリアスが、あらかじめ定義されています。
その結果、派生的なパスはこのエイリアスを使って形成することが出来ます
(例えば、runtime ディレクトリを示す @app/runtime など)。
重要なプロパティ
この項で説明するプロパティは、アプリケーションが異なるごとに異なってくるものであるため、たいてい、構成する必要が生じます。
yii\base\Application::aliases
このプロパティを使って、配列形式で一連の エイリアス を定義することが出来ます。 配列のキーがエイリアスの名前であり、配列の値が対応するパスの定義です。 例えば、
[
'aliases' => [
'@name1' => 'path/to/path1',
'@name2' => 'path/to/path2',
],
]
このプロパティが提供されているのは、Yii::setAlias() メソッドを呼び出す代りに、アプリケーションのコンフィギュレーションを使ってエイリアスを定義することが出来るようにするためです。
yii\base\Application::bootstrap
これは非常に有用なプロパティです。 これによって、アプリケーションの yii\base\Application::bootstrap() において走らせるべきコンポーネントを配列として規定することが出来ます。 例えば、ある モジュール に URL 規則 をカスタマイズさせたいときに、モジュールの ID をこのプロパティの要素として挙げることが出来ます。
このプロパティに挙げるコンポーネントは、それぞれ、以下の形式のいずれかによって規定することが出来ます:
- components によって規定されるアプリケーションコンポーネントの ID。
- modules によって規定されるモジュールの ID。
- クラス名。
- コンフィギュレーション配列。
- コンポーネントを作成して返す無名関数。
例えば、
[
'bootstrap' => [
// アプリケーションコンポーネント ID、または、モジュール ID
'demo',
// クラス名
'app\components\Profiler',
// コンフィギュレーション配列
[
'class' => 'app\components\Profiler',
'level' => 3,
],
// 無名関数
function () {
return new app\components\Profiler();
}
],
]
Info|情報: モジュール ID と同じ ID のアプリケーションコンポーネントがある場合は、ブートストラップの過程ではアプリケーションコンポーネントが使われます。 代りにモジュールを使いたいときは、次のように、無名関数を使って指定することが出来ます:
[ function () { return Yii::$app->getModule('user'); }, ]
ブートストラップの過程で、各コンポーネントのインスタンスが作成されます。
そして、コンポーネントクラスが [[yii\base\BootstrapInterface]] を実装している場合は、その [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] メソッドも呼び出されます。
もう一つの実用的な例が [ベーシックアプリケーションテンプレート](start-installation.md) のアプリケーションのコンフィギュレーションの中にあります。
そこでは、アプリケーションが開発環境で走るときには `debug` モジュールと `gii` モジュールがブートストラップコンポーネントとして構成されています。
```php
if (YII_ENV_DEV) {
// 'dev' 環境のためのコンフィギュレーションの調整
$config['bootstrap'][] = 'debug';
$config['modules']['debug'] = 'yii\debug\Module';
$config['bootstrap'][] = 'gii';
$config['modules']['gii'] = 'yii\gii\Module';
}
Note|注意: あまり多くのコンポーネントを
bootstrapに置くと、アプリケーションのパフォーマンスを劣化させます。 なぜなら、リクエストごとに同じ一連のコンポーネントを走らせなければならないからです。 ですから、ブートストラップコンポーネントは賢く使ってください。
yii\web\Application::catchAll
このプロパティは yii\web\Application においてのみサポートされます。 これは、全てのユーザリクエストを処理すべき コントローラアクション を規定します。 これは主としてアプリケーションがメンテナンスモードにあって、入ってくる全てのリクエストを単一のアクションで処理する必要があるときに使われます。
コンフィギュレーションは配列の形を取り、最初の要素はアクションのルートを指定します。 そして、配列の残りの要素 (キー・値のペア) は、アクションに渡されるパラメータを指定します。 例えば、
[
'catchAll' => [
'offline/notice',
'param1' => 'value1',
'param2' => 'value2',
],
]
yii\base\Application::components
これが唯一最重要なプロパティです。これによって、アプリケーションコンポーネント と呼ばれる一連の名前付きのコンポーネントを登録して、それらを他の場所で使うことが出来るようになります。 例えば、
[
'components' => [
'cache' => [
'class' => 'yii\caching\FileCache',
],
'user' => [
'identityClass' => 'app\models\User',
'enableAutoLogin' => true,
],
],
]
全てのアプリケーションコンポーネントは、それぞれ、配列の中で「キー・値」のペアとして規定されます。 キーはコンポーネントの ID を示し、値はコンポーネントのクラス名または コンフィギュレーション を示します。
どのようなコンポーネントでもアプリケーションとともに登録することが出来ます。
そして登録されたコンポーネントは、後で、\Yii::$app->ComponentID という式を使ってグローバルにアクセスすることが出来ます。
詳細は アプリケーションコンポーネント の節を呼んでください。
yii\base\Application::controllerMap
このプロパティは、コントローラ ID を任意のコントローラクラスに割り付けることを可能にするものです。
既定では、Yii は 規約 に基いてコントローラ ID をコントローラクラスに割り付けます
(例えば、post という ID は app\controllers\PostController に割り付けられます)。
このプロパティを構成することによって、特定のコントローラに対する規約を破ることが出来ます。
下記の例では、account は app\controllers\UserController に割り付けられ、
article は app\controllers\PostController に割り付けられることになります。
[
'controllerMap' => [
[
'account' => 'app\controllers\UserController',
'article' => [
'class' => 'app\controllers\PostController',
'enableCsrfValidation' => false,
],
],
],
]
このプロパティの配列のキーはコントローラ ID を表し、配列の値は対応するコントローラクラスの名前または コンフィギュレーション を表します。
yii\base\Application::controllerNamespace
このプロパティは、コントローラクラスが配置されるべき既定の名前空間を指定するものです。
デフォルト値は app\controllers です。
コントローラ ID が post である場合、規約によって対応するコントローラの (名前空間を略した) クラス名は PostController となり、
完全修飾クラス名は app\controllers\PostController となります。
コントローラクラスは、この名前空間に対応するディレクトリのサブディレクトリに配置されても構いません。
例えば、コントローラ ID として admin/post を仮定すると、対応するコントローラの完全修飾クラス名は app\controllers\admin\PostController となります。
完全修飾のコントローラクラスが オートロード可能 でなければならず、 コントローラクラスの実際の名前空間がこのプロパティと合致していなければならない、 ということは非常に重要なことです。 そうでないと、アプリケーションにアクセスしたときに "ページがみつかりません" というエラーを受け取ることになります。
上述の規約を破りたい場合は、controllerMap プロパティを構成することが出来ます。
yii\base\Application::language
このプロパティは、アプリケーションがコンテンツをエンドユーザに表示するときに使うべき言語を規定します。
このプロパティのデフォルト値は en であり、英語を意味します。
アプリケーションが多言語をサポートする必要があるときは、このプロパティを構成すべきです。
このプロパティの値が、メッセージの翻訳、日付の書式、数字の書式などを含めて、国際化 のさまざまな側面を決定します。 例えば、yii\jui\DatePicker ウィジェットは、どの言語でカレンダーを表示すべきか、そして日付をどのように書式設定すべきかを、既定では、このプロパティを使用して決定します。
言語を指定するのには、IETF 言語タグ に従うことが推奨されます。
例えば、en は英語を意味し、en-US はアメリカ合衆国の英語を意味します。
このプロパティに関する更なる詳細は 国際化 の節で読むことが出来ます。
yii\base\Application::modules
このプロパティはアプリケーションが含む モジュール を規定します。
このプロパティは、モジュールのクラスまたは コンフィギュレーション の配列であり、 その配列のキーはモジュールの ID です。例えば、
[
'modules' => [
// モジュールクラスで規定された "booking" モジュール
'booking' => 'app\modules\booking\BookingModule',
// コンフィギュレーション配列で規定された "comment" モジュール
'comment' => [
'class' => 'app\modules\comment\CommentModule',
'db' => 'db',
],
],
]
詳細は モジュール の節を参照してください。
yii\base\Application::name
このプロパティはアプリケーション名を規定します。これは、エンドユーザに対して表示されるかも知れません。 yii\base\Application::id プロパティがユニークな値でなければならないのとは違って、このプロパティの値は 主として表示目的であり、ユニークである必要はありません。
コードで使わないのであれば、このプロパティを構成する必要はありません。
yii\base\Application::params
このプロパティは、グローバルにアクセス可能なアプリケーションパラメータの配列を規定します。 コードの中のいたる処でハードコードされた数値や文字列を使う代りに、それらをアプリケーションパラメータとして 一ヶ所で定義し、必要な場所ではそのパラメータを使うというのが良い慣行です。 例えば、次のように、サムネール画像のサイズをパラメータとして定義することが出来ます:
[
'params' => [
'thumbnail.size' => [128, 128],
],
]
そして、このサイズの値を使う必要があるコードにおいては、ただ単に下記のようなコードを使うことが出来ます:
$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];
後でサムネールのサイズを変更すると決めたときは、アプリケーションのコンフィギュレーションにおいてのみサイズを修正すればよく、 これに依存するコードには少しも触れる必要がありません。
yii\base\Application::sourceLanguage
このプロパティはアプリケーションコードが書かれている言語を規定します。デフォルト値は'en-US'、アメリカ合衆国の英語です。
あなたのコードのテキスト内容が英語以外で書かれているときは、このプロパティを構成すべきです。
language プロパティと同様に、このプロパティは IETF 言語タグ に従って構成すべきです。
例えば、en は英語を意味し、en-US はアメリカ合衆国の英語を意味します。
このプロパティに関する更なる詳細は 国際化 の節で読むことが出来ます。
yii\base\Application::timeZone
このプロパティは、PHP ランタイムのデフォルトタイムゾーンを設定する代替手段として提供されています。 このプロパティを構成すると、本質的には PHP 関数 date_default_timezone_set() を呼ぶことになります。 例えば、
[
'timeZone' => 'Asia/Tokyo',
]
yii\base\Application::version
このプロパティはアプリケーションのバージョンを規定します。デフォルト値は '1.0' です。
コードの中で使わないのであれば、必ずしも構成する必要はありません。
有用なプロパティ
この項で説明されるプロパティは通常は構成されません。というのは、そのデフォルト値が通常の規約を規定するものだからです。 しかしながら、規約を破る必要がある場合には、これらのプロパティを構成することが出来ます。
yii\base\Application::charset
このプロパティはアプリケーションが使う文字セットを規定します。デフォルト値は 'UTF-8' であり、
あなたのアプリケーションが多数の非ユニコードデータを使うレガシーシステムと連携するのでなければ、
そのままにしておくべきです。
yii\base\Application::defaultRoute
This property specifies the route that an application should use when a request
does not specify one. The route may consist of child module ID, controller ID, and/or action ID.
For example, help, post/create, admin/post/create. If action ID is not given, it will take the default
value as specified in yii\base\Controller::defaultAction.
For yii\web\Application, the default value of this property is 'site', which means
the SiteController controller and its default action should be used. As a result, if you access
the application without specifying a route, it will show the result of app\controllers\SiteController::actionIndex().
For yii\console\Application, the default value is 'help', which means the core command
yii\console\controllers\HelpController::actionIndex() should be used. As a result, if you run the command yii
without providing any arguments, it will display the help information.
yii\base\Application::extensions
This property specifies the list of extensions that are installed and used by the application.
By default, it will take the array returned by the file @vendor/yiisoft/extensions.php. The extensions.php file
is generated and maintained automatically when you use Composer to install extensions.
So in most cases, you do not need to configure this property.
In the special case when you want to maintain extensions manually, you may configure this property like the following:
[
'extensions' => [
[
'name' => 'extension name',
'version' => 'version number',
'bootstrap' => 'BootstrapClassName', // optional, may also be a configuration array
'alias' => [ // optional
'@alias1' => 'to/path1',
'@alias2' => 'to/path2',
],
],
// ... more extensions like the above ...
],
]
As you can see, the property takes an array of extension specifications. Each extension is specified with an array
consisting of name and version elements. If an extension needs to run during the bootstrap
process, a bootstrap element may be specified with a bootstrapping class name or a configuration
array. An extension may also define a few aliases.
yii\base\Application::layout
This property specifies the name of the default layout that should be used when rendering a view.
The default value is 'main', meaning the layout file main.php under the layout path should be used.
If both of the layout path and the view path are taking the default values,
the default layout file can be represented as the path alias @app/views/layouts/main.php.
You may configure this property to be false if you want to disable layout by default, although this is very rare.
yii\base\Application::layoutPath
This property specifies the path where layout files should be looked for. The default value is
the layouts sub-directory under the view path. If the view path is taking
its default value, the default layout path can be represented as the path alias @app/views/layouts.
You may configure it as a directory or a path alias.
yii\base\Application::runtimePath
This property specifies the path where temporary files, such as log files, cache files, can be generated.
The default value is the directory represented by the alias @app/runtime.
You may configure it as a directory or a path alias. Note that the runtime path must be writable by the process running the application. And the path should be protected from being accessed by end users because the temporary files under it may contain sensitive information.
To simplify accessing to this path, Yii has predefined a path alias named @runtime for it.
yii\base\Application::viewPath
This property specifies the root directory where view files are located. The default value is the directory
represented by the alias @app/views. You may configure it as a directory or a path alias.
yii\base\Application::vendorPath
This property specifies the vendor directory managed by Composer. It contains
all third party libraries used by your application, including the Yii framework. The default value is
the directory represented by the alias @app/vendor.
You may configure this property as a directory or a path alias. When you modify this property, make sure you also adjust the Composer configuration accordingly.
To simplify accessing to this path, Yii has predefined a path alias named @vendor for it.
yii\console\Application::enableCoreCommands
This property is supported by yii\console\Application only. It specifies
whether the core commands included in the Yii release should be enabled. The default value is true.
Application Events
An application triggers several events during the lifecycle of handling an request. You may attach event handlers to these events in application configurations like the following,
[
'on beforeRequest' => function ($event) {
// ...
},
]
The use of the on eventName syntax is described in the Configurations
section.
Alternatively, you may attach event handlers during the bootstrapping process process after the application instance is created. For example,
\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
// ...
});
yii\base\Application::EVENT_BEFORE_REQUEST
This event is triggered before an application handles a request. The actual event name is beforeRequest.
When this event is triggered, the application instance has been configured and initialized. So it is a good place to insert your custom code via the event mechanism to intercept the request handling process. For example, in the event handler, you may dynamically set the yii\base\Application::language property based on some parameters.
yii\base\Application::EVENT_AFTER_REQUEST
This event is triggered after an application finishes handling a request but before sending the response.
The actual event name is afterRequest.
When this event is triggered, the request handling is completed and you may take this chance to do some postprocessing of the request or customize the response.
Note that the yii\web\Response component also triggers some events while it is sending out response content to end users. Those events are triggered after this event.
yii\base\Application::EVENT_BEFORE_ACTION
This event is triggered before running every controller action.
The actual event name is beforeAction.
The event parameter is an instance of yii\base\ActionEvent. An event handler may set
the yii\base\ActionEvent::isValid property to be false to stop running the action.
For example,
[
'on beforeAction' => function ($event) {
if (some condition) {
$event->isValid = false;
} else {
}
},
]
Note that the same beforeAction event is also triggered by modules
and controllers. Application objects are the first ones
triggering this event, followed by modules (if any), and finally controllers. If an event handler
sets yii\base\ActionEvent::isValid to be false, all the following events will NOT be triggered.
yii\base\Application::EVENT_AFTER_ACTION
This event is triggered after running every controller action.
The actual event name is afterAction.
The event parameter is an instance of yii\base\ActionEvent. Through the yii\base\ActionEvent::result property, an event handler may access or modify the action result. For example,
[
'on afterAction' => function ($event) {
if (some condition) {
// modify $event->result
} else {
}
},
]
Note that the same afterAction event is also triggered by modules
and controllers. These objects trigger this event in the reverse order
as for that of beforeAction. That is, controllers are the first objects triggering this event,
followed by modules (if any), and finally applications.
Application Lifecycle
When an entry script is being executed to handle a request, an application will undergo the following lifecycle:
- The entry script loads the application configuration as an array.
- The entry script creates a new instance of the application:
- yii\base\Application::preInit() is called, which configures some high priority application properties, such as yii\base\Application::basePath.
- Register the yii\base\Application::errorHandler.
- Configure application properties.
- yii\base\Application::init() is called which further calls yii\base\Application::bootstrap() to run bootstrapping components.
- The entry script calls yii\base\Application::run() to run the application:
- Trigger the yii\base\Application::EVENT_BEFORE_REQUEST event.
- Handle the request: resolve the request into a route and the associated parameters; create the module, controller and action objects as specified by the route; and run the action.
- Trigger the yii\base\Application::EVENT_AFTER_REQUEST event.
- Send response to the end user.
- The entry script receives the exit status from the application and completes the request processing.