應用（Applications） · Yii 2.0 權威指南

# 應用主體應用主體是管理 Yii 應用系統整體結構和生命周期的對象。每個Yii應用系統只能包含一個應用主體，應用主體在?[入口腳本](http://www.yiichina.com/doc/guide/2.0/structure-entry-scripts)?中創建并能通過表達式?`\Yii::$app`?全局范圍內訪問。 > 補充: 當我們說"一個應用"，它可能是一個應用主體對象，也可能是一個應用系統，是根據上下文來決定[譯：中文為避免歧義，Application翻譯為應用主體]。 Yii有兩種應用主體: yii\web\Application and yii\console\Application，如名稱所示，前者主要處理網頁請求，后者處理控制臺請求。 ## 應用主體配置如下所示，當?[入口腳本](http://www.yiichina.com/doc/guide/2.0/structure-entry-scripts)?創建了一個應用主體，它會加載一個?[配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations)?文件并傳給應用主體。 ~~~ require(__DIR__ . '/../vendor/autoload.php'); require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php'); // 加載應用主體配置 $config = require(__DIR__ . '/../config/web.php'); // 實例化應用主體、配置應用主體 (new yii\web\Application($config))->run(); ~~~ 類似其他?[配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations)?文件, 應用主體配置文件標明如何設置應用對象初始屬性。由于應用主體配置比較復雜，一般保存在多個類似如上web.php的?[配置文件](http://www.yiichina.com/doc/guide/2.0/concept-configurations#configuration-files)?當中。 ## 應用主體屬性應用主體配置文件中有許多重要的屬性要配置，這些屬性指定應用主體的運行環境。比如，應用主體需要知道如何加載?[控制器](http://www.yiichina.com/doc/guide/2.0/structure-controllers)?，臨時文件保存到哪兒等等。以下我們簡述這些屬性。 ### 必要屬性在一個應用中，至少要配置2個屬性: yii\base\Application::id 和 yii\base\Application::basePath。 #### yii\base\Application::id yii\base\Application::id 屬性用來區分其他應用的唯一標識ID。主要給程序使用。為了方便協作，最好使用數字作為應用主體ID，但不強制要求為數字。 #### yii\base\Application::basePath yii\base\Application::basePath 指定該應用的根目錄。根目錄包含應用系統所有受保護的源代碼。在根目錄下可以看到對應MVC設計模式的`models`,?`views`,?`controllers`等子目錄。可以使用路徑或?[路徑別名](http://www.yiichina.com/doc/guide/2.0/concept-aliases)?來在配置 yii\base\Application::basePath 屬性。兩種格式所對應的目錄都必須存在，否則系統會拋出一個異常。系統會使用?`realpath()`?函數規范化配置的路徑. yii\base\Application::basePath 屬性經常用于派生一些其他重要路徑（如runtime路徑），因此，系統預定義?`@app`?代表這個路徑。派生路徑可以通過這個別名組成（如`@app/runtime`代表runtime的路徑）。 ### 重要屬性本小節所描述的屬性通常需要設置，因為不同的應用屬性不同。 #### yii\base\Application::aliases 該屬性允許你用一個數組定義多個?[別名](http://www.yiichina.com/doc/guide/2.0/concept-aliases)。數組的key為別名名稱，值為對應的路徑。例如： ~~~ [ 'aliases' => [ '@name1' => 'path/to/path1', '@name2' => 'path/to/path2', ], ] ~~~ 使用這個屬性來定義別名，代替 Yii::setAlias() 方法來設置。 #### yii\base\Application::bootstrap 這個屬性很實用，它允許你用數組指定啟動階段yii\base\Application::bootstrap()需要運行的組件。比如，如果你希望一個?[模塊](http://www.yiichina.com/doc/guide/2.0/structure-modules)?自定義[URL 規則](http://www.yiichina.com/doc/guide/2.0/runtime-url-handling)，你可以將模塊ID加入到bootstrap數組中。屬性中的每個組件需要指定以下一項: * 應用?[組件](http://www.yiichina.com/doc/guide/2.0/structure-applications#components)?ID. * [模塊](http://www.yiichina.com/doc/guide/2.0/structure-applications#modules)?ID. * 類名. * 配置數組. * 創建并返回一個組件的無名稱函數. 例如： ~~~ [ 'bootstrap' => [ // 應用組件ID或模塊ID 'demo', // 類名 'app\components\Profiler', // 配置數組 [ 'class' => 'app\components\Profiler', 'level' => 3, ], // 無名稱函數 function () { return new app\components\Profiler(); } ], ] ~~~ > 補充: 如果模塊ID和應用組件ID同名，優先使用應用組件ID，如果你想用模塊ID，可以使用如下無名稱函數返回模塊ID。?`````php [ > > ~~~ > function () { > return Yii::$app->getModule('user'); > }, > ~~~ > > ]?````` 在啟動階段，每個組件都會實例化。如果組件類實現接口 yii\base\BootstrapInterface,也會調用 yii\base\BootstrapInterface::bootstrap() 方法。舉一個實際的例子，[Basic Application Template](http://www.yiichina.com/doc/guide/2.0/start-installation)?應用主體配置中，開發環境下會在啟動階段運行?`debug`?和?`gii`?模塊。 ~~~ if (YII_ENV_DEV) { // configuration adjustments for 'dev' environment $config['bootstrap'][] = 'debug'; $config['modules']['debug'] = 'yii\debug\Module'; $config['bootstrap'][] = 'gii'; $config['modules']['gii'] = 'yii\gii\Module'; } ~~~ > 注: 啟動太多的組件會降低系統性能，因為每次請求都需要重新運行啟動組件，因此謹慎配置啟動組件。 #### yii\web\Application::catchAll 該屬性僅 yii\web\Application 網頁應用支持。它指定一個要處理所有用戶請求的?[控制器方法](http://www.yiichina.com/doc/guide/2.0/structure-controllers)，通常在維護模式下使用，同一個方法處理所有用戶請求。該配置為一個數組，第一項指定動作的路由，剩下的數組項(key-value 成對)指定傳遞給動作的參數，例如： ~~~ [ 'catchAll' => [ 'offline/notice', 'param1' => 'value1', 'param2' => 'value2', ], ] ~~~ #### yii\base\Application::components 這是最重要的屬性，它允許你注冊多個在其他地方使用的[應用組件](http://www.yiichina.com/doc/guide/2.0/#structure-application-components). 例如 ~~~ [ 'components' => [ 'cache' => [ 'class' => 'yii\caching\FileCache', ], 'user' => [ 'identityClass' => 'app\models\User', 'enableAutoLogin' => true, ], ], ] ~~~ 每一個應用組件指定一個key-value對的數組，key代表組件ID，value代表組件類名或?[配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations)。在應用中可以任意注冊組件，并可以通過表達式?`\Yii::$app->ComponentID`?全局訪問。詳情請閱讀?[應用組件](http://www.yiichina.com/doc/guide/2.0/structure-application-components)?一節. #### yii\base\Application::controllerMap 該屬性允許你指定一個控制器ID到任意控制器類。Yii遵循一個默認的?[規則](http://www.yiichina.com/doc/guide/2.0/structure-applications#controllerNamespace)指定控制器ID到任意控制器類（如`post`對應`app\controllers\PostController`）。通過配置這個屬性，可以打破這個默認規則，在下面的例子中，`account`對應到`app\controllers\UserController`，?`article`?對應到?`app\controllers\PostController`。 ~~~ [ 'controllerMap' => [ [ 'account' => 'app\controllers\UserController', 'article' => [ 'class' => 'app\controllers\PostController', 'enableCsrfValidation' => false, ], ], ], ] ~~~ 數組的鍵代表控制器ID，數組的值代表對應的類名。 #### yii\base\Application::controllerNamespace 該屬性指定控制器類默認的命名空間，默認為`app\controllers`。比如控制器ID為?`post`?默認對應?`PostController`?（不帶命名空間），類全名為?`app\controllers\PostController`。控制器類文件可能放在這個命名空間對應目錄的子目錄下，例如，控制器ID?`admin/post`?對應的控制器類全名為`app\controllers\admin\PostController`。控制器類全面能被?[自動加載](http://www.yiichina.com/doc/guide/2.0/concept-autoloading)，這點是非常重要的，控制器類的實際命名空間對應這個屬性，否則，訪問時你會收到"Page Not Found"[譯：頁面找不到]。如果你想打破上述的規則，可以配置?[controllerMap](http://www.yiichina.com/doc/guide/2.0/structure-applications#controllerMap)?屬性。 #### yii\base\Application::language 該屬性指定應用展示給終端用戶的語言，默認為?`en`?標識英文。如果需要之前其他語言可以配置該屬性。該屬性影響各種?[國際化](http://www.yiichina.com/doc/guide/2.0/tutorial-i18n)?，包括信息翻譯、日期格式、數字格式等。例如 yii\jui\DatePicker 小部件會根據該屬性展示對應語言的日歷以及日期格式。推薦遵循?[IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag)?來設置語言，例如?`en`?代表英文，?`en-US`?代表英文(美國). 該屬性的更多信息可參考?[國際化](http://www.yiichina.com/doc/guide/2.0/tutorial-i18n)?一節. #### yii\base\Application::modules 該屬性指定應用所包含的?[模塊](http://www.yiichina.com/doc/guide/2.0/structure-modules)。該屬性使用數組包含多個模塊類?[配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations)，數組的鍵為模塊ID，例： ~~~ [ 'modules' => [ // "booking" 模塊以及對應的類 'booking' => 'app\modules\booking\BookingModule', // "comment" 模塊以及對應的配置數組 'comment' => [ 'class' => 'app\modules\comment\CommentModule', 'db' => 'db', ], ], ] ~~~ 更多詳情請參考?[模塊](http://www.yiichina.com/doc/guide/2.0/structure-modules)?一節。 #### yii\base\Application::name 該屬性指定你可能想展示給終端用戶的應用名稱，不同于需要唯一性的 yii\base\Application::id 屬性，該屬性可以不唯一，該屬性用于顯示應用的用途。如果其他地方的代碼沒有用到，可以不配置該屬性。 #### yii\base\Application::params 該屬性為一個數組，指定可以全局訪問的參數，代替程序中硬編碼的數字和字符，應用中的參數定義到一個單獨的文件并隨時可以訪問是一個好習慣。例如用參數定義縮略圖的長寬如下： ~~~ [ 'params' => [ 'thumbnail.size' => [128, 128], ], ] ~~~ 然后簡單的使用如下代碼即可獲取到你需要的長寬參數： ~~~ $size = \Yii::$app->params['thumbnail.size']; $width = \Yii::$app->params['thumbnail.size'][0]; ~~~ 以后想修改縮略圖長寬，只需要修改該參數而不需要相關的代碼。 #### yii\base\Application::sourceLanguage 該屬性指定應用代碼的語言，默認為?`'en-US'`?標識英文（美國），如果應用不是英文請修改該屬性。和?[語言](http://www.yiichina.com/doc/guide/2.0/structure-applications#language)?屬性類似，配置該屬性需遵循?[IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag). 例如?`en`?代表英文，?`en-US`?代表英文(美國)。該屬性的更多信息可參考?[國際化](http://www.yiichina.com/doc/guide/2.0/tutorial-i18n)?一節. #### yii\base\Application::timeZone 該屬性提供一種方式修改PHP運行環境中的默認時區，配置該屬性本質上就是調用PHP函數?[date_default_timezone_set()](http://php.net/manual/en/function.date-default-timezone-set.php)，例如： ~~~ [ 'timeZone' => 'America/Los_Angeles', ] ~~~ #### yii\base\Application::version 該屬性指定應用的版本，默認為`'1.0'`，其他代碼不使用的話可以不配置。 ### 實用屬性本小節描述的屬性不經常設置，通常使用系統默認值。如果你想改變默認值，可以配置這些屬性。 #### yii\base\Application::charset 該屬性指定應用使用的字符集，默認值為?`'UTF-8'`，絕大部分應用都在使用，除非已有的系統大量使用非unicode數據才需要更改該屬性。 #### yii\base\Application::defaultRoute 該屬性指定未配置的請求的響應?[路由](http://www.yiichina.com/doc/guide/2.0/runtime-routing)?規則，路由規則可能包含模塊ID，控制器ID，動作ID。例如`help`,?`post/create`,`admin/post/create`，如果動作ID沒有指定，會使用yii\base\Controller::defaultAction中指定的默認值。對于 yii\web\Application 網頁應用，默認值為?`'site'`?對應?`SiteController`?控制器，并使用默認的動作。因此你不帶路由的訪問應用，默認會顯示?`app\controllers\SiteController::actionIndex()`?的結果。對于 yii\console\Application 控制臺應用，默認值為?`'help'`?對應 yii\console\controllers\HelpController::actionIndex()。因此，如果執行的命令不帶參數，默認會顯示幫助信息。 #### yii\base\Application::extensions 該屬性用數組列表指定應用安裝和使用的?[擴展](http://www.yiichina.com/doc/guide/2.0/structure-extensions)，默認使用`@vendor/yiisoft/extensions.php`文件返回的數組。當你使用?[Composer](https://getcomposer.org/)安裝擴展，`extensions.php`?會被自動生成和維護更新。所以大多數情況下，不需要配置該屬性。特殊情況下你想自己手動維護擴展，可以參照如下配置該屬性： ~~~ [ 'extensions' => [ [ 'name' => 'extension name', 'version' => 'version number', 'bootstrap' => 'BootstrapClassName', // 可選配，可為配置數組 'alias' => [ // 可選配 '@alias1' => 'to/path1', '@alias2' => 'to/path2', ], ], // ... 更多像上面的擴展 ... ], ] ~~~ 如上所示，該屬性包含一個擴展定義數組，每個擴展為一個包含?`name`?和?`version`?項的數組。如果擴展要在?[引導啟動](http://www.yiichina.com/doc/guide/2.0/runtime-bootstrapping)?階段運行，需要配置?`bootstrap`以及對應的引導啟動類名或?[configuration](http://www.yiichina.com/doc/guide/2.0/concept-configurations)?數組。擴展也可以定義?[別名](http://www.yiichina.com/doc/guide/2.0/concept-aliases) #### yii\base\Application::layout 該屬性指定渲染?[視圖](http://www.yiichina.com/doc/guide/2.0/structure-views)?默認使用的布局名字，默認值為?`'main'`?對應[布局路徑](http://www.yiichina.com/doc/guide/2.0/structure-applications#layoutPath)下的?`main.php`?文件，如果?[布局路徑](http://www.yiichina.com/doc/guide/2.0/structure-applications#layoutPath)?和?[視圖路徑](http://www.yiichina.com/doc/guide/2.0/structure-applications#viewPath)?都是默認值，默認布局文件可以使用路徑別名`@app/views/layouts/main.php` 如果不想設置默認布局文件，可以設置該屬性為?`false`，這種做法比較罕見。 #### yii\base\Application::layoutPath 該屬性指定查找布局文件的路徑，默認值為?[視圖路徑](http://www.yiichina.com/doc/guide/2.0/structure-applications#viewPath)?下的?`layouts`?子目錄。如果?[視圖路徑](http://www.yiichina.com/doc/guide/2.0/structure-applications#viewPath)?使用默認值，默認的布局路徑別名為`@app/views/layouts`。該屬性需要配置成一個目錄或路徑?[別名](http://www.yiichina.com/doc/guide/2.0/concept-aliases)。 #### yii\base\Application::runtimePath 該屬性指定臨時文件如日志文件、緩存文件等保存路徑，默認值為帶別名的?`@app/runtime`。可以配置該屬性為一個目錄或者路徑?[別名](http://www.yiichina.com/doc/guide/2.0/concept-aliases)，注意應用運行時有對該路徑的寫入權限，以及終端用戶不能訪問該路徑因為臨時文件可能包含一些敏感信息。為了簡化訪問該路徑，Yii預定義別名?`@runtime`?代表該路徑。 #### yii\base\Application::viewPath 該路徑指定視圖文件的根目錄，默認值為帶別名的?`@app/views`，可以配置它為一個目錄或者路徑?[別名](http://www.yiichina.com/doc/guide/2.0/concept-aliases). #### yii\base\Application::vendorPath 該屬性指定?[Composer](https://getcomposer.org/)?管理的供應商路徑，該路徑包含應用使用的包括Yii框架在內的所有第三方庫。默認值為帶別名的`@app/vendor`?。可以配置它為一個目錄或者路徑?[別名](http://www.yiichina.com/doc/guide/2.0/concept-aliases)，當你修改時，務必修改對應的 Composer 配置。為了簡化訪問該路徑，Yii預定義別名?`@vendor`?代表該路徑。 #### yii\console\Application::enableCoreCommands 該屬性僅 yii\console\Application 控制臺應用支持，用來指定是否啟用Yii中的核心命令，默認值為?`true`。 ## 應用事件應用在處理請求過程中會觸發事件，可以在配置文件配置事件處理代碼，如下所示： ~~~ [ 'on beforeRequest' => function ($event) { // ... }, ] ~~~ `on eventName`?語法的用法在?[Configurations](http://www.yiichina.com/doc/guide/2.0/concept-configurations#configuration-format)?一節有詳細描述. 另外，在應用主體實例化后，你可以在[引導啟動](http://www.yiichina.com/doc/guide/2.0/runtime-bootstrapping)?階段附加事件處理代碼，例如： ~~~ \Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) { // ... }); ~~~ ### yii\base\Application::EVENT_BEFORE_REQUEST 該事件在應用處理請求*before*之前，實際的事件名為?`beforeRequest`。在事件觸發前，應用主體已經實例化并配置好了，所以通過事件機制將你的代碼嵌入到請求處理過程中非常不錯。例如在事件處理中根據某些參數動態設置yii\base\Application::language語言屬性。 ### yii\base\Application::EVENT_AFTER_REQUEST 該事件在應用處理請求*after*之后但在返回響應*before*之前觸發，實際的事件名為`afterRequest`。該事件觸發時，請求已經被處理完，可以做一些請求后處理或自定義響應。注意 yii\web\Response 組件在發送響應給終端用戶時也會觸發一些事件，這些事件都在本事件*after*之后觸發。 ### yii\base\Application::EVENT_BEFORE_ACTION 該事件在每個?[控制器動作](http://www.yiichina.com/doc/guide/2.0/structure-controllers)?運行*before*之前會被觸發，實際的事件名為?`beforeAction`. 事件的參數為一個 yii\base\ActionEvent 實例，事件處理中可以設置yii\base\ActionEvent::isValid 為?`false`?停止運行后續動作，例如： ~~~ [ 'on beforeAction' => function ($event) { if (some condition) { $event->isValid = false; } else { } }, ] ~~~ 注意?[模塊](http://www.yiichina.com/doc/guide/2.0/structure-modules)?和?[控制器](http://www.yiichina.com/doc/guide/2.0/structure-controllers)?都會觸發?`beforeAction`?事件。應用主體對象首先觸發該事件，然后模塊觸發（如果存在模塊），最后控制器觸發。任何一個事件處理中設置 yii\base\ActionEvent::isValid 設置為?`false`?會停止觸發后面的事件。 ### yii\base\Application::EVENT_AFTER_ACTION 該事件在每個?[控制器動作](http://www.yiichina.com/doc/guide/2.0/structure-controllers)?運行*after*之后會被觸發，實際的事件名為?`afterAction`. 該事件的參數為 yii\base\ActionEvent 實例，通過yii\base\ActionEvent::result屬性，事件處理可以訪問和修改動作的結果。例如： ~~~ [ 'on afterAction' => function ($event) { if (some condition) { // 修改 $event->result } else { } }, ] ~~~ 注意?[模塊](http://www.yiichina.com/doc/guide/2.0/structure-modules)?和?[控制器](http://www.yiichina.com/doc/guide/2.0/structure-controllers)?都會觸發?`afterAction`?事件。這些對象的觸發順序和?`beforeAction`?相反，也就是說，控制器最先觸發，然后是模塊（如果有模塊），最后為應用主體。 ## 應用主體生命周期當運行?[入口腳本](http://www.yiichina.com/doc/guide/2.0/structure-entry-scripts)?處理請求時，應用主體會經歷以下生命周期: 1. 入口腳本加載應用主體配置數組。 2. 入口腳本創建一個應用主體實例： * 調用 yii\base\Application::preInit() 配置幾個高級別應用主體屬性，比如yii\base\Application::basePath。 * 注冊 yii\base\Application::errorHandler 錯誤處理方法. * 配置應用主體屬性. * 調用 yii\base\Application::init() 初始化，該函數會調用 yii\base\Application::bootstrap() 運行引導啟動組件. 3. 入口腳本調用 yii\base\Application::run() 運行應用主體: * 觸發 yii\base\Application::EVENT_BEFORE_REQUEST 事件。 * 處理請求：解析請求?[路由](http://www.yiichina.com/doc/guide/2.0/runtime-routing)?和相關參數；創建路由指定的模塊、控制器和動作對應的類，并運行動作。 * 觸發 yii\base\Application::EVENT_AFTER_REQUEST 事件。 * 發送響應到終端用戶. 4. 入口腳本接收應用主體傳來的退出狀態并完成請求的處理。