配置（Configurations）

配置

在 Yii 中，創(chuàng)建新對象和初始化已存在對象時廣泛使用配置。配置通常包含被創(chuàng)建對象的類名和一組將要賦值給對象屬性的初始值。還可能包含一組將被附加到對象事件上的句柄。和一組將被附加到對象上的行為。

以下代碼中的配置被用來創(chuàng)建并初始化一個數(shù)據(jù)庫連接：

$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() 方法接受一個配置數(shù)組并根據(jù)數(shù)組中指定的類名創(chuàng)建對象。對象實例化后，剩余的參數(shù)被用來初始化對象的屬性，事件處理和行為。

對于已存在的對象，可以使用 Yii::configure() 方法根據(jù)配置去初始化其屬性，就像這樣：

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

請注意，如果配置一個已存在的對象，那么配置數(shù)組中不應該包含指定類名的?class?元素。

配置的格式

一個配置的格式可以描述為以下形式：

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

其中

• class?元素指定了將要創(chuàng)建的對象的完全限定類名。
• propertyName?元素指定了對象屬性的初始值。鍵名是屬性名，值是該屬性對應的初始值。只有公共成員變量以及通過 getter/setter 定義的屬性可以被配置。
• on eventName?元素指定了附加到對象事件上的句柄是什么。請注意，數(shù)組的鍵名由?on?前綴加事件名組成。請參考事件章節(jié)了解事件句柄格式。
• as behaviorName?元素指定了附加到對象的行為。請注意，數(shù)組的鍵名由?as?前綴加行為名組成。$behaviorConfig?值表示創(chuàng)建行為的配置信息，格式與我們之前描述的配置格式一樣。

下面是一個配置了初始化屬性值，事件句柄和行為的示例：

[
    'class' => 'app\components\SearchEngine',
    'apiKey' => 'xxxxxxxx',
    'on search' => function ($event) {
        Yii::info("搜索的關(guān)鍵詞： " . $event->keyword);
    },
    'as indexer' => [
        'class' => 'app\components\IndexerBehavior',
        // ... 初始化屬性值 ...
    ],
]

使用配置

Yii 中的配置可以用在很多場景。本章開頭我們展示了如何使用 Yii::creatObject() 根據(jù)配置信息創(chuàng)建對象。本小節(jié)將介紹配置的兩種主要用法 —— 配置應用與配置小部件。

應用的配置

應用的配置可能是最復雜的配置之一。因為 yii\web\Application 類擁有很多可配置的屬性和事件。更重要的是它的 yii\web\Application::components 屬性可以接收配置數(shù)組并通過應用注冊為組件。以下是一個針對基礎(chǔ)應用模板的應用配置概要：

$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'extensions' => require(__DIR__ . '/../vendor/yiisoft/extensions.php'),
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'mailer' => [
            'class' => 'yii\swiftmailer\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?鍵的原因是這段配置應用在下面的入口腳本中，類名已經(jīng)指定了。

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

更多關(guān)于應用?components?屬性配置的信息可以查閱應用以及服務定位器章節(jié)。

小部件的配置

使用小部件時，常常需要配置以便自定義其屬性。 yii\base\Widget::widget() 和 yii\base\Widget::begin() 方法都可以用來創(chuàng)建小部件。它們可以接受配置數(shù)組：

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],
    ],
]);

上述代碼創(chuàng)建了一個小部件?Menu?并將其?activateItems?屬性初始化為 false。item?屬性也配置成了將要顯示的菜單條目。

請注意，代碼中已經(jīng)給出了類名?yii\widgets\Menu'，配置數(shù)組**不應該**再包含?class` 鍵。

配置文件

當配置的內(nèi)容十分復雜，通用做法是將其存儲在一或多個 PHP 文件中，這些文件被稱為配置文件。一個配置文件返回的是 PHP 數(shù)組。例如，像這樣把應用配置信息存儲在名為?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里。components.php?的內(nèi)容如下：

return [
    'cache' => [
        'class' => 'yii\caching\FileCache',
    ],
    'mailer' => [
        'class' => 'yii\swiftmailer\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”，就可以取得一個配置文件的配置內(nèi)容，像這樣：

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

默認配置

Yii::createObject() 方法基于依賴注入容器實現(xiàn)。使用 Yii::creatObject() 創(chuàng)建對象時，可以附加一系列默認配置到指定類的任何實例。默認配置還可以在入口腳本中調(diào)用?Yii::$container->set()?來定義。

例如，如果你想自定義 yii\widgets\LinkPager 小部件，以便讓分頁器最多只顯示 5 個翻頁按鈕（默認是 10 個），你可以用下述代碼實現(xiàn)：

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

不使用默認配置的話，你就得在任何使用分頁器的地方，都配置?maxButtonCount?的值。

環(huán)境常量

配置經(jīng)常要隨著應用運行的不同環(huán)境更改。例如在開發(fā)環(huán)境中，你可能使用名為?mydb_dev?的數(shù)據(jù)庫，而生產(chǎn)環(huán)境則使用?mydb_prod數(shù)據(jù)庫。為了便于切換使用環(huán)境，Yii 提供了一個定義在入口腳本中的?YII_ENV?常量。如下：

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

你可以把?YII_ENV?定義成以下任何一種值：

• prod：生產(chǎn)環(huán)境。常量?YII_ENV_PROD?將被看作 true。如果你沒修改過，這就是?YII_ENV?的默認值。
• dev：開發(fā)環(huán)境。常量?YII_ENV_DEV?將被看作 true。
• test：測試環(huán)境。常量?YII_ENV_TEST?將被看作 true。

有了這些環(huán)境常量，你就可以根據(jù)當下應用運行環(huán)境的不同，進行差異化配置。例如，應用可以包含下述代碼只在開發(fā)環(huán)境中開啟調(diào)試工具。

$config = [...];

if (YII_ENV_DEV) {
    // 根據(jù) `dev` 環(huán)境進行的配置調(diào)整
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';
}

return $config;