配置 ¶

配置在 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 元素指定具名屬性的初始值。 鍵是屬性名稱，值是相應的初始值。 只有公共成員變數和由 getter/setter 定義的屬性可以配置。
• 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() 根據配置建立物件。 在本小節中，我們將描述應用程式配置和小工具配置 - 配置的兩個主要用途。

應用程式配置 ¶

應用程式的配置可能是 Yii 中最複雜的陣列之一。 這是因為 application 類別有很多可配置的屬性和事件。 更重要的是，它的 components 屬性可以接收配置陣列，用於建立通過應用程式註冊的組件。 以下是來自 基本專案範本的應用程式配置檔案的摘要。

$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 鍵。

配置檔案 ¶

當配置非常複雜時，常見的做法是將其儲存在一個或多個 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() 來指定。

例如，如果您想自訂 yii\widgets\LinkPager，以便所有連結分頁器最多顯示 5 個頁面按鈕（預設值為 10），您可以使用以下程式碼來實現此目標：

\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，則這是 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;