# 配置
在 Yii 中，創建新對象和初始化已存在對象時廣泛使用配置。配置通常包含被創建對象的類名和一組將要賦值給對象[屬性](http://www.yiichina.com/doc/guide/2.0/concept-properties)的初始值。還可能包含一組將被附加到對象[事件](http://www.yiichina.com/doc/guide/2.0/concept-events)上的句柄。和一組將被附加到對象上的[行為](http://www.yiichina.com/doc/guide/2.0/concept-behaviors)。
以下代碼中的配置被用來創建并初始化一個數據庫連接：
~~~
$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 定義的[屬性](http://www.yiichina.com/doc/guide/2.0/concept-properties)可以被配置。
* `on eventName`?元素指定了附加到對象[事件](http://www.yiichina.com/doc/guide/2.0/concept-events)上的句柄是什么。請注意，數組的鍵名由?`on?`前綴加事件名組成。請參考[事件](http://www.yiichina.com/doc/guide/2.0/concept-events)章節了解事件句柄格式。
* `as behaviorName`?元素指定了附加到對象的[行為](http://www.yiichina.com/doc/guide/2.0/concept-behaviors)。請注意，數組的鍵名由?`as?`前綴加行為名組成。`$behaviorConfig`?值表示創建行為的配置信息，格式與我們之前描述的配置格式一樣。
下面是一個配置了初始化屬性值，事件句柄和行為的示例：
~~~
[
'class' => 'app\components\SearchEngine',
'apiKey' => 'xxxxxxxx',
'on search' => function ($event) {
Yii::info("搜索的關鍵詞： " . $event->keyword);
},
'as indexer' => [
'class' => 'app\components\IndexerBehavior',
// ... 初始化屬性值 ...
],
]
~~~
## 使用配置
Yii 中的配置可以用在很多場景。本章開頭我們展示了如何使用 Yii::creatObject() 根據配置信息創建對象。本小節將介紹配置的兩種主要用法 —— 配置應用與配置小部件。
### 應用的配置
[應用](http://www.yiichina.com/doc/guide/2.0/structure-applications)的配置可能是最復雜的配置之一。因為 yii\web\Application 類擁有很多可配置的屬性和事件。更重要的是它的 yii\web\Application::components 屬性可以接收配置數組并通過應用注冊為組件。以下是一個針對[基礎應用模板](http://www.yiichina.com/doc/guide/2.0/start-installation)的應用配置概要：
~~~
$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`?鍵的原因是這段配置應用在下面的入口腳本中，類名已經指定了。
~~~
(new yii\web\Application($config))->run();
~~~
更多關于應用?`components`?屬性配置的信息可以查閱[應用](http://www.yiichina.com/doc/guide/2.0/structure-applications)以及[服務定位器](http://www.yiichina.com/doc/guide/2.0/concept-service-locator)章節。
### 小部件的配置
使用[小部件](http://www.yiichina.com/doc/guide/2.0/structure-widgets)時，常常需要配置以便自定義其屬性。 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。`item`?屬性也配置成了將要顯示的菜單條目。
請注意，代碼中已經給出了類名?`yii\widgets\Menu'，配置數組**不應該**再包含?`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`里。`components.php`?的內容如下：
~~~
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”，就可以取得一個配置文件的配置內容，像這樣：
~~~
$config = require('path/to/web.php');
(new yii\web\Application($config))->run();
~~~
## 默認配置
Yii::createObject() 方法基于[依賴注入容器](http://www.yiichina.com/doc/guide/2.0/concept-di-container)實現。使用 Yii::creatObject() 創建對象時，可以附加一系列**默認配置**到指定類的任何實例。默認配置還可以在[入口腳本](http://www.yiichina.com/doc/guide/2.0/runtime-bootstrapping)中調用?`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`?的默認值。
* `dev`：開發環境。常量?`YII_ENV_DEV`?將被看作 true。
* `test`：測試環境。常量?`YII_ENV_TEST`?將被看作 true。
有了這些環境常量，你就可以根據當下應用運行環境的不同，進行差異化配置。例如，應用可以包含下述代碼只在開發環境中開啟[調試工具](http://www.yiichina.com/doc/guide/2.0/tool-debugger)。
~~~
$config = [...];
if (YII_ENV_DEV) {
// 根據 `dev` 環境進行的配置調整
$config['bootstrap'][] = 'debug';
$config['modules']['debug'] = 'yii\debug\Module';
}
return $config;
~~~
- 介紹（Introduction）
- 關于 Yii（About Yii）
- 從 Yii 1.1 升級（Upgrading from Version 1.1）
- 入門（Getting Started）
- 安裝 Yii（Installing Yii）
- 運行應用（Running Applications）
- 第一次問候（Saying Hello）
- 使用 Forms（Working with Forms）
- 玩轉 Databases（Working with Databases）
- 用 Gii 生成代碼（Generating Code with Gii）
- 更上一層樓（Looking Ahead）
- 應用結構（Application Structure）
- 結構概述（Overview）
- 入口腳本（Entry Scripts）
- 應用（Applications）
- 應用組件（Application Components）
- 控制器（Controllers）
- 模型（Models）
- 視圖（Views）
- 模塊（Modules）
- 過濾器（Filters）
- 小部件（Widgets）
- 前端資源（Assets）
- 擴展（Extensions）
- 請求處理（Handling Requests）
- 運行概述（Overview）
- 引導（Bootstrapping）
- 路由引導與創建 URL（Routing and URL Creation）
- 請求（Requests）
- 響應（Responses）
- Sessions and Cookies
- 錯誤處理（Handling Errors）
- 日志（Logging）
- 關鍵概念（Key Concepts）
- 組件（Components）
- 屬性（Properties）
- 事件（Events）
- 行為（Behaviors）
- 配置（Configurations）
- 別名（Aliases）
- 類自動加載（Class Autoloading）
- 服務定位器（Service Locator）
- 依賴注入容器（Dependency Injection Container）
- 配合數據庫工作（Working with Databases）
- 數據庫訪問（Data Access Objects）: 數據庫連接、基本查詢、事務和模式操作
- 查詢生成器（Query Builder）: 使用簡單抽象層查詢數據庫
- 活動記錄（Active Record）: 活動記錄對象關系映射（ORM），檢索和操作記錄、定義關聯關系
- 數據庫遷移（Migrations）: 在團體開發中對你的數據庫使用版本控制
- Sphinx
- Redis
- MongoDB
- ElasticSearch
- 接收用戶數據（Getting Data from Users）
- 創建表單（Creating Forms）
- 輸入驗證（Validating Input）
- 文件上傳（Uploading Files）
- 收集列表輸入（Collecting Tabular Input）
- 多模型同時輸入（Getting Data for Multiple Models）
- 顯示數據（Displaying Data）
- 格式化輸出數據（Data Formatting）
- 分頁（Pagination）
- 排序（Sorting）
- 數據提供器（Data Providers）
- 數據小部件（Data Widgets）
- 操作客戶端腳本（Working with Client Scripts）
- 主題（Theming）
- 安全（Security）
- 認證（Authentication）
- 授權（Authorization）
- 處理密碼（Working with Passwords）
- 客戶端認證（Auth Clients）
- 安全領域的最佳實踐（Best Practices）
- 緩存（Caching）
- 概述（Overview）
- 數據緩存（Data Caching）
- 片段緩存（Fragment Caching）
- 分頁緩存（Page Caching）
- HTTP 緩存（HTTP Caching）
- RESTful Web 服務
- 快速入門（Quick Start）
- 資源（Resources）
- 控制器（Controllers）
- 路由（Routing）
- 格式化響應（Response Formatting）
- 授權驗證（Authentication）
- 速率限制（Rate Limiting）
- 版本化（Versioning）
- 錯誤處理（Error Handling）
- 開發工具（Development Tools）
- 調試工具欄和調試器（Debug Toolbar and Debugger）
- 使用 Gii 生成代碼（Generating Code using Gii）
- TBD 生成 API 文檔（Generating API Documentation）
- 測試（Testing）
- 概述（Overview）
- 搭建測試環境（Testing environment setup）
- 單元測試（Unit Tests）
- 功能測試（Functional Tests）
- 驗收測試（Acceptance Tests）
- 測試夾具（Fixtures）
- 高級專題（Special Topics）
- 高級應用模版（Advanced Project Template）
- 從頭構建自定義模版（Building Application from Scratch）
- 控制臺命令（Console Commands）
- 核心驗證器（Core Validators）
- 國際化（Internationalization）
- 收發郵件（Mailing）
- 性能優化（Performance Tuning）
- 共享主機環境（Shared Hosting Environment）
- 模板引擎（Template Engines）
- 集成第三方代碼（Working with Third-Party Code）
- 小部件（Widgets）
- Bootstrap 小部件（Bootstrap Widgets）
- jQuery UI 小部件（jQuery UI Widgets）
- 助手類（Helpers）
- 助手一覽（Overview）
- Array 助手（ArrayHelper）
- Html 助手（Html）
- Url 助手（Url）