配置（Configurations）

配置

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

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

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

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

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

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

配置的格式

一個(gè)配置的格式可以描述為以下形式：

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

其中

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

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

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

使用配置

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

應(yīng)用的配置

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

$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',
        ],
    ],
];

配置中沒(méi)有?class?鍵的原因是這段配置應(yīng)用在下面的入口腳本中，類名已經(jīng)指定了。

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

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

小部件的配置

使用小部件時(shí)，常常需要配置以便自定義其屬性。 yii\base\Widget::widget() 和 yii\base\Widget::begin() 方法都可以用來(lái)創(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)建了一個(gè)小部件?Menu?并將其?activateItems?屬性初始化為 false。item?屬性也配置成了將要顯示的菜單條目。

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

配置文件

當(dāng)配置的內(nèi)容十分復(fù)雜，通用做法是將其存儲(chǔ)在一或多個(gè) PHP 文件中，這些文件被稱為配置文件。一個(gè)配置文件返回的是 PHP 數(shù)組。例如，像這樣把應(yīng)用配置信息存儲(chǔ)在名為?web.php?的文件中：

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

鑒于?components?配置也很復(fù)雜，上述代碼把它們存儲(chǔ)在單獨(dú)的?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”，就可以取得一個(gè)配置文件的配置內(nèi)容，像這樣：

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

默認(rèn)配置

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

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

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

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

環(huán)境常量

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

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

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

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

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

$config = [...];

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

return $config;