コンフィグレーション ¶

コンフィグレーションは、Yiiで新しいオブジェクトを作成したり、既存のオブジェクトを初期化するときに広く使用されます。コンフィグレーションには通常、作成するオブジェクトのクラス名と、オブジェクトのプロパティに割り当てるべき初期値のリストが含まれています。プロパティに加えて、オブジェクトのイベントにアタッチするハンドラのリストや、オブジェクトにアタッチするビヘイビアのリストを含めることもできます。

次に、コンフィグレーションを使用してデータベース接続を作成し、初期化する方法を示します。

$config = [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
];

$db = Yii::createObject($config);

Yii::createObject()メソッドは、コンフィグレーション配列を引数として受け取り、コンフィグレーションで指定されたクラス名をインスタンス化することでオブジェクトを作成します。オブジェクトがインスタンス化されると、残りのコンフィグレーションを使用して、オブジェクトのプロパティ、イベントハンドラ、ビヘイビアを初期化します。

既にオブジェクトがある場合は、Yii::configure()を使用して、コンフィグレーション配列でオブジェクトのプロパティを初期化できます。

Yii::configure($object, $config);

この場合、コンフィグレーション配列には`class`要素を含めるべきではないことに注意してください。

コンフィグレーション形式 ¶

コンフィグレーションの形式は、正式には次のように記述できます。

[
    'class' => 'ClassName',
    'propertyName' => 'propertyValue',
    'on eventName' => $eventHandler,
    'as behaviorName' => $behaviorConfig,
]

ここで

• `class`要素は、作成するオブジェクトの完全修飾クラス名を指定します。
• `propertyName`要素は、名前付きプロパティの初期値を指定します。キーはプロパティ名、値は対応する初期値です。公開メンバー変数と、ゲッター/セッターで定義されたプロパティのみをコンフィグレーションできます。
• `on eventName`要素は、オブジェクトのイベントにアタッチするハンドラを指定します。配列のキーは、イベント名に`on `をプレフィックスとして付けたものです。サポートされているイベントハンドラの形式については、イベントセクションを参照してください。
• `as behaviorName`要素は、オブジェクトにアタッチするビヘイビアを指定します。配列のキーは、ビヘイビア名に`as `をプレフィックスとして付けたものです。値`$behaviorConfig`は、ここで説明されている通常のコンフィグレーションのように、ビヘイビアを作成するためのコンフィグレーションを表します。

以下は、初期プロパティ値、イベントハンドラ、ビヘイビアを含むコンフィグレーションの例を示しています。

[
    'class' => 'app\components\SearchEngine',
    'apiKey' => 'xxxxxxxx',
    'on search' => function ($event) {
        Yii::info("Keyword searched: " . $event->keyword);
    },
    'as indexer' => [
        'class' => 'app\components\IndexerBehavior',
        // ... property init values ...
    ],
]

コンフィグレーションの使用 ¶

設定はYiiの多くの場所で利用されます。このセクションの冒頭では、Yii::createObject() を使用して、設定に基づいてオブジェクトを作成する方法を示しました。この小節では、アプリケーション設定とウィジェット設定という、設定の2つの主要な使用方法について説明します。

アプリケーション設定 ¶

アプリケーション の設定は、おそらくYiiで最も複雑な配列の1つです。これは、アプリケーション クラスには多くの設定可能なプロパティとイベントがあるためです。さらに重要なのは、そのcomponents プロパティが、アプリケーションを通じて登録されたコンポーネントを作成するための設定の配列を受け取ることができることです。Basic Project Templateのアプリケーション設定ファイルからの抜粋を以下に示します。

$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require __DIR__ . '/../vendor/yiisoft/extensions.php',
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'mailer' => [
            'class' => 'yii\symfonymailer\Mailer',
        ],
        'log' => [
            'class' => 'yii\log\Dispatcher',
            'traceLevel' => YII_DEBUG ? 3 : 0,
            'targets' => [
                [
                    'class' => 'yii\log\FileTarget',
                ],
            ],
        ],
        'db' => [
            'class' => 'yii\db\Connection',
            'dsn' => 'mysql:host=localhost;dbname=stay2',
            'username' => 'root',
            'password' => '',
            'charset' => 'utf8',
        ],
    ],
];

この設定には、classキーがありません。これは、クラス名が既に指定されているエントリスクリプトで次のように使用されるためです。

(new yii\web\Application($config))->run();

アプリケーションのcomponentsプロパティの設定に関する詳細は、アプリケーションセクションとサービスロケータセクションを参照してください。

バージョン2.0.11以降、アプリケーション設定は、containerプロパティを使用して依存性注入コンテナの設定をサポートしています。例えば

$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require __DIR__ . '/../vendor/yiisoft/extensions.php',
    'container' => [
        'definitions' => [
            'yii\widgets\LinkPager' => ['maxButtonCount' => 5]
        ],
        'singletons' => [
            // Dependency Injection Container singletons configuration
        ]
    ]
];

definitionsとsingletonsの設定配列の可能な値と現実の例については、依存性注入コンテナの記事の高度な実践的な使用方法の小節を参照してください。

ウィジェット設定 ¶

ウィジェットを使用する場合、ウィジェットのプロパティをカスタマイズするために設定を使用する必要があることがよくあります。yii\base\Widget::widget()とyii\base\Widget::begin()の両方のメソッドを使用してウィジェットを作成できます。これらは、次のようない設定配列を受け取ります。

use yii\widgets\Menu;

echo Menu::widget([
    'activateItems' => false,
    'items' => [
        ['label' => 'Home', 'url' => ['site/index']],
        ['label' => 'Products', 'url' => ['product/index']],
        ['label' => 'Login', 'url' => ['site/login'], 'visible' => Yii::$app->user->isGuest],
    ],
]);

上記のコードはMenuウィジェットを作成し、そのactivateItemsプロパティをfalseに初期化します。itemsプロパティも、表示するメニュー項目で設定されています。

クラス名が既に指定されているため、設定配列にはclassキーを含めるべきではありません。

設定ファイル ¶

設定が非常に複雑な場合、一般的な方法は、設定ファイルと呼ばれる1つまたは複数のPHPファイルに格納することです。設定ファイルは、設定を表すPHP配列を返します。たとえば、アプリケーション設定をweb.phpという名前のファイルに次のように保存できます。

return [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require __DIR__ . '/../vendor/yiisoft/extensions.php',
    'components' => require __DIR__ . '/components.php',
];

componentsの設定も複雑なため、それをcomponents.phpという別のファイルに格納し、上記のようにweb.phpでこのファイルを「require」します。components.phpの内容は以下のとおりです。

return [
    'cache' => [
        'class' => 'yii\caching\FileCache',
    ],
    'mailer' => [
        'class' => 'yii\symfonymailer\Mailer',
    ],
    'log' => [
        'class' => 'yii\log\Dispatcher',
        'traceLevel' => YII_DEBUG ? 3 : 0,
        'targets' => [
            [
                'class' => 'yii\log\FileTarget',
            ],
        ],
    ],
    'db' => [
        'class' => 'yii\db\Connection',
        'dsn' => 'mysql:host=localhost;dbname=stay2',
        'username' => 'root',
        'password' => '',
        'charset' => 'utf8',
    ],
];

設定ファイルに格納されている設定を取得するには、単に「require」します。例えば

$config = require 'path/to/web.php';
(new yii\web\Application($config))->run();

デフォルト設定 ¶

Yii::createObject()メソッドは、依存性注入コンテナに基づいて実装されています。Yii::createObject()を使用して作成される場合、指定されたクラスのすべてのインスタンスに適用される、いわゆるデフォルト設定のセットを指定できます。デフォルト設定は、ブートストラップコードでYii::$container->set()を呼び出すことで指定できます。

たとえば、すべてのリンカーページャーが最大5つのページボタンを表示するように（デフォルト値は10）、yii\widgets\LinkPagerをカスタマイズする場合は、次のコードを使用してこの目標を達成できます。

\Yii::$container->set('yii\widgets\LinkPager', [
    'maxButtonCount' => 5,
]);

デフォルト設定を使用しない場合、リンカーページャーを使用するすべての場所でmaxButtonCountを設定する必要があります。

環境定数 ¶

設定は、アプリケーションが実行される環境によって異なることがよくあります。たとえば、開発環境ではmydb_devという名前のデータベースを使用する場合がありますが、本番サーバーではmydb_prodデータベースを使用する場合があります。環境の切り替えを容易にするために、Yiiは、アプリケーションのエントリスクリプトで定義できるYII_ENVという定数を提供しています。例えば

defined('YII_ENV') or define('YII_ENV', 'dev');

YII_ENVを以下の値のいずれかに定義できます。

• prod：本番環境。定数YII_ENV_PRODはtrueとして評価されます。これは、定義しない場合のYII_ENVのデフォルト値です。
• dev：開発環境。定数YII_ENV_DEVはtrueとして評価されます。
• test：テスト環境。定数YII_ENV_TESTはtrueとして評価されます。

これらの環境定数を使用すると、現在の環境に基づいて設定を条件付きで指定できます。たとえば、アプリケーション設定には、開発環境でデバッグツールバーとデバッガーを有効にする次のコードを含めることができます。

$config = [...];

if (YII_ENV_DEV) {
    // configuration adjustments for 'dev' environment
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';
}

return $config;