php/yii2

mirror of https://github.com/yiisoft/yii2.git synced 2025-11-04 14:46:19 +08:00

Files

Nobuo Kihara 74e0fee725 docs/guide-ja/structure-applications.md - "config" => "構成(情報)" [ci skip]

2014-11-28 21:37:49 +09:00

アプリケーション

アプリケーションは 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

このプロパティは、リクエストがルートを指定していないときにアプリケーションが使用すべきルートを規定します。ルートは、チャイルドモジュール ID、コントローラ ID、および/またはアクション ID を構成要素とすることが出来ます。例えば、help、post/create、admin/post/create などです。アクション ID が与えられていない場合は、yii\base\Controller::defaultAction で規定されるデフォルト値を取ります。

yii\web\Application では、このプロパティのデフォルト値は 'site' であり、その意味するところは、SiteController コントローラとそのデフォルトアクションが使用されるべきである、ということです。結果として、ルートを指定せずにアプリケーションにアクセスすると、app\controllers\SiteController::actionIndex() の結果が表示されます。

yii\console\Application では、デフォルト値は 'help' であり、コアコマンドの yii\console\controllers\HelpController::actionIndex() が使用されるべきであるという意味です。結果として、引数を与えずに yii というコマンドを走らせると、ヘルプ情報が表示されることになります。

yii\base\Application::extensions

このプロパティは、アプリケーションにインストールされて使われるエクステンションを規定するリストです。デフォルトでは、@vendor/yiisoft/extensions.php というファイルによって返される配列を取ります。 extensions.php は、Composer を使ってエクステンションをインストールすると、自動的に生成され保守されます。ですから、たいていの場合、このプロパティをあなたが構成する必要はありません。

エクステンションを手作業で保守したいという特殊なケースにおいては、次のようにしてこのプロパティを構成することが出来ます。

[
    'extensions' => [
        [
            'name' => 'extension name',
            'version' => 'version number',
            'bootstrap' => 'BootstrapClassName',  // オプション、構成情報の配列でもよい
            'alias' => [  // optional
                '@alias1' => 'to/path1',
                '@alias2' => 'to/path2',
            ],
        ],

        // ... 上記と同じように、更にエクステンションを構成 ...

    ],
]

見て分かるように、このプロパティはエクステンションの仕様を示す配列を取ります。それぞれのエクステンションは、name と version の要素を含む配列によって規定されます。エクステンションがブートストラップの過程で走る必要がある場合には、bootstrap 要素をブートストラップのクラス名または構成情報の配列によって規定することが出来ます。また、エクステンションはいくつかのエイリアスを定義することも出来ます。

yii\base\Application::layout

このプロパティは、ビューをレンダリングするときに使われるべきデフォルトのレイアウトを規定します。デフォルト値は 'main' であり、レイアウトパスの下にある main.php というファイルが使われるべき事を意味します。レイアウトパスとビューパスの両方がデフォルト値を取る場合、デフォルトのレイアウトファイルは @app/views/layouts/main.php というパスエイリアスとして表すことが出来ます。

滅多には無いことですが、レイアウトをデフォルトで無効にしたい場合は、このプロパティを false として構成することが出来ます。

yii\base\Application::layoutPath

このプロパティは、レイアウトファイルが捜されるべきパスを規定します。デフォルト値は、ビューパスの下の layouts サブディレクトリです。ビューパスがデフォルト値を取る場合、デフォルトのレイアウトパスは @app/views/layouts というパスエイリアスとして表すことが出来ます。

このプロパティはディレクトリまたはパスエイリアスとして構成することが出来ます。

yii\base\Application::runtimePath

このプロパティは、ログファイルやキャッシュファイルなどの一時的ファイルを生成することが出来るパスを規定します。デフォルト値は、@app/runtime というエイリアスで表現されるディレクトリです。

このプロパティはディレクトリまたはパスエイリアスとして構成することが出来ます。ランタイムパスは、アプリケーションを走らせているプロセスによって書き込みが可能なものでなければならないことに注意してください。そして、この下にある一時的ファイルは秘匿を要する情報を含みうるものですので、ランタイムパスはエンドユーザによるアクセスから保護されるべきです。

このパスに簡単にアクセスできるように、Yii は @runtime というパスエイリアスを事前に定義しています。

yii\base\Application::viewPath

このプロパティはビューファイルが配置されるルートディレクトリを規定します。デフォルト値は、@app/views というエイリアスで表現されるディレクトリです。このプロパティはディレクトリまたはパスエイリアスとして構成することが出来ます。

yii\base\Application::vendorPath

このプロパティは、Composer によって管理される vendor ディレクトリを規定します。 Yii フレームワークを含めて、あなたのアプリケーションによって使われる全てのサードパーティライブラリを格納するディレクトリです。デフォルト値は、@app/vendor というエイリアスで表現されるディレクトリです。

このプロパティはディレクトリまたはパスエイリアスとして構成することが出来ます。このプロパティを修正するときは、必ず、Composer の構成もそれに合せて調整してください。

このパスに簡単にアクセスできるように、Yii は @vendor というパスエイリアスを事前に定義しています。

yii\console\Application::enableCoreCommands

このプロパティは yii\console\Application においてのみサポートされています。 Yii リリースに含まれているコアコマンドを有効にすべきか否かを規定します。デフォルト値は true です。

アプリケーションのイベント

アプリケーションはリクエストを処理するライフサイクルの中でいくつかのイベントをトリガします。これらのイベントに対して、下記のようにして、アプリケーションの構成情報の中でイベントハンドラをアタッチすることが出来ます。

[
    'on beforeRequest' => function ($event) {
        // ...
    },
]

on eventName という構文の使い方については、構成情報の節で説明されています。

別の方法として、アプリケーションのインスタンスが生成された後、ブートストラップの過程の中でイベントハンドラをアタッチすることも出来ます。例えば、

\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
    // ...
});

yii\base\Application::EVENT_BEFORE_REQUEST

このイベントは、アプリケーションがリクエストを処理する前にトリガされます。実際のイベント名は beforeRequest です。

このイベントがトリガされるときには、アプリケーションのインスタンスは既に構成されて初期化されています。ですから、イベントメカニズムを使って、リクエスト処理のプロセスに干渉するカスタムコードを挿入するのには、ちょうど良い場所です。例えば、このイベントハンドラの中で、何らかのパラメータに基づいて yii\base\Application::language プロパティを動的にセットすることが出来ます。

yii\base\Application::EVENT_AFTER_REQUEST

このイベントは、アプリケーションがリクエストの処理を完了した後、レスポンスを送信する前にトリガされます。実際のイベント名は afterRequest です。

このイベントがトリガされるときにはリクエストの処理は完了していますので、この機をとらえて、リクエストに対する何らかの後処理をしたり、レスポンスをカスタマイズしたりすることが出来ます。

yii\web\Response コンポーネントも、エンドユーザにレスポンスのコンテンツを送出する間にいくつかのイベントをトリガすることに注意してください。それらのイベントは、このイベントの後にトリガされます。

yii\base\Application::EVENT_BEFORE_ACTION

このイベントは、コントローラアクションを走らせる前に毎回トリガされます。実際のイベント名は beforeAction です。

イベントのパラメータは yii\base\ActionEvent のインスタンスです。イベントハンドラは、yii\base\ActionEvent::isValid プロパティを false にセットして、アクションが走るのを止めることが出来ます。例えば、

[
    'on beforeAction' => function ($event) {
        if (some condition) {
            $event->isValid = false;
        } else {
        }
    },
]

同じ beforeAction イベントが、モジュールとコントローラからもトリガされることに注意してください。アプリケーションオブジェクトが最初にこのイベントをトリガし、次に (もし有れば) モジュールが、そして最後にコントローラがこのイベントをトリガします。イベントハンドラが yii\base\ActionEvent::isValid を false にセットすると、後続のイベントはトリガされません。

yii\base\Application::EVENT_AFTER_ACTION

このイベントは、コントローラアクションが走った後に毎回トリガされます。実際のイベント名は afterAction です。

イベントのパラメータは yii\base\ActionEvent のインスタンスです。 yii\base\ActionEvent::result プロパティを通じて、イベントハンドラはアクションの結果にアクセスしたり、またはアクションの結果を修正したり出来ます。例えば、

[
    'on afterAction' => function ($event) {
        if (some condition) {
            // $event->result を修正する
        } else {
        }
    },
]

同じ afterAction イベントが、モジュールとコントローラからもトリガされることに注意してください。これらのオブジェクトは、beforeAction の場合とは逆の順でイベントをトリガします。すなわち、コントローラオブジェクトが最初にこのイベントをトリガし、次に (もし有れば) モジュールが、そして最後にアプリケーションがこのイベントをトリガします。

アプリケーションのライフサイクル

エントリスクリプトが実行されて、リクエストが処理されるとき、アプリケーションは次のようなライフサイクルを経ます。

エントリスクリプトがアプリケーションの構成情報を配列として読み出す。
エントリスクリプトがアプリケーションの新しいインスタンスを作成する。

yii\base\Application::preInit() が呼び出されて、yii\base\Application::basePath のような、優先度の高いアプリケーションプロパティを構成する。
yii\base\Application::errorHandler を登録する。
アプリケーションのプロパティを構成する。
yii\base\Application::init() が呼ばれ、そこから更に、ブートストラップコンポーネントを走らせるために、yii\base\Application::bootstrap() が呼ばれる。

エントリスクリプトが yii\base\Application::run() を呼んで、アプリケーションを走らせる。

yii\base\Application::EVENT_BEFORE_REQUEST イベントをトリガする。
リクエストを処理する: リクエストをルートとそれに結び付くパラメータとして解決する; ルートによって指定されたモジュール、コントローラ、および、アクションを作成する; そしてアクションを走らせる。
yii\base\Application::EVENT_AFTER_REQUEST イベントをトリガする。
エンドユーザにレスポンスを送信する。

エントリスクリプトがアプリケーションから終了ステータスを受け取り、リクエストの処理を完了する。

35 KiB Raw Blame History