Yii 2 应用对象(Application)深入解析:配置属性、请求事件与生命周期
Yii 2 应用对象(Application)深入解析:配置属性、请求事件与生命周期
本篇技术指南以官方指南 structure-applications(葡萄牙语版)为骨架,系统讲解 Yii 2 框架中 Application 应用对象的本质:它是如何通过入口脚本和配置文件被创建、如何通过 id、basePath、bootstrap、components 等属性掌控应用环境,如何通过四个生命周期事件介入请求处理,以及一次请求从进入应用到输出响应所经历的完整生命周期。读完本文,你将掌握编写可复制的入口脚本与配置文件、合理配置三类应用属性、正确绑定应用事件,并能对照 framework/base/Application.php 源码理解每一步的底层机制。
一、什么是 Application:Web 与 Console 两种应用类型
在 Yii 2 中,Application(应用)是掌管应用整体结构与生命周期的核心对象。每个应用只包含一个唯一的 Application 实例,它在入口脚本中被创建,并可通过全局表达式 \Yii::$app 在任何地方访问。
注意:根据上下文,"一个应用"既可以指 Application 对象,也可以指整个应用系统。
Yii 2 提供两种类型的应用:
- Web 应用(
yii\web\Application):处理 HTTP Web 请求; - 控制台应用(
yii\console\Application):处理命令行(CLI)命令请求。
从源码结构看,两者都继承自 yii\base\Application(抽象基类),而基类又继承自 yii\base\Module,因此 Application 本质上是一个"顶层模块"。在基类的构造函数中(framework/base/Application.php),第一件事就是把当前实例注册为全局单例:
public function __construct($config = [])
{
Yii::$app = $this; // 全局访问入口
static::setInstance($this); // 模块静态实例
$this->state = self::STATE_BEGIN;
$this->preInit($config);
$this->registerErrorHandler($config);
Component::__construct($config);
}
这解释了为什么在控制器、模型、视图乃至任意组件中都能直接使用 \Yii::$app。
二、应用的创建:入口脚本与配置文件
当入口脚本创建应用时,会加载一份配置并应用到 Application 对象上。典型的 Web 入口脚本如下:
require __DIR__ . '/../vendor/autoload.php';
require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';
// 加载应用的配置
$config = require __DIR__ . '/../config/web.php';
// 实例化并配置应用
(new yii\web\Application($config))->run();
与普通配置一样,应用配置以"属性名 => 值"的形式指定如何初始化 Application 对象的属性。由于应用配置通常非常复杂,一般会单独存放在配置文件中,例如上例的 web.php。
在构造函数内部,preInit()(framework/base/Application.php)会先处理一批高优先级属性,这个过程值得关注:
id与basePath必填:缺失任一属性都会抛出InvalidConfigException(分别对应 L217-L219 与 L220-L225);- 提前设置
vendorPath、runtimePath、timeZone、container,这些属性必须在常规属性配置之前就位; - 将核心组件配置与自定义组件配置合并(L255-L262):如果你在
components中自定义了某个核心组件但未指定class,框架会自动补上核心类名; - 随后
registerErrorHandler()(L336-L347)在YII_ENABLE_ERROR_HANDLER开启时注册错误处理组件。
接着 Component::__construct($config) 会把其余配置属性应用到对象上,并在最后调用 init(),而 init() 内部会调用 bootstrap()(L268-L272)来执行引导组件——这正是第三节中 bootstrap 属性发挥作用的地方。
三、应用配置属性全景
应用有很多重要属性需要配置,它们通常描述了应用运行的环境——例如应用如何加载控制器、临时文件存放在哪里等。以下按官方指南的分类逐一展开。
3.1 必需属性(Required Properties)
任何应用至少要配置两个属性:id 和 basePath。
id
id 指定一个唯一 ID,用于把当前应用与其他应用区分开,主要供代码程序化使用。虽然不是强制要求,但为了更好的互操作性,建议只使用字母数字字符。
basePath
basePath 指定应用的根目录,即存放全部受保护源码的目录。在这个目录下,通常能看到 models、views、controllers 等对应 MVC 模式的子目录。
配置 basePath 时可以使用路径别名,无论哪种形式,对应目录必须真实存在,否则会抛出异常;该路径会经 realpath() 函数规范化。
basePath 经常被用来派生其他重要路径(如 runtime 目录),因此框架预先定义了别名 @app 指向该路径,派生路径都可以基于它来构造,例如用 @app/runtime 引用 runtime 目录。在源码中,setBasePath()(framework/base/Application.php)设置路径的同时执行 Yii::setAlias('@app', $this->getBasePath())。
3.2 重要属性(Important Properties)
这些属性在不同应用中往往取值不同,因此经常需要配置。
aliases
允许你以数组形式定义一组别名:数组的键是别名名称,值是别名对应的定义。例如:
[
'aliases' => [
'@name1' => 'path/to/path1',
'@name2' => 'path/to/path2',
],
]
提供该属性是为了让你能在应用配置中直接定义别名,而不必额外调用 Yii::setAlias() 方法。
bootstrap
这是一个非常实用的属性。它允许你指定一组组件,在应用 bootstrap() 引导(初始化)过程中被执行。例如,如果你希望某个模块自定义URL 规则,就可以把它的 ID 列入此属性。
列表中的每个组件可以用以下任意一种格式指定:
- 通过 components 指定的应用组件 ID;
- 通过 modules 指定的模块 ID;
- 一个类名;
- 一个配置数组;
- 一个创建并返回组件的匿名函数。
示例:
[
'bootstrap' => [
// 应用组件或模块的 ID
'demo',
// 一个类名
'app\components\Profiler',
// 一个配置数组
[
'class' => 'app\components\Profiler',
'level' => 3,
],
// 一个匿名函数
function () {
return new app\components\Profiler();
}
],
]
提示:如果某个模块的 ID 与应用组件的 ID 相同,引导过程中会优先使用该组件。若你想改用模块,可以通过匿名函数指定,例如:
[ function () { return Yii::$app->getModule('user'); }, ]
在引导过程中,每个组件都会被实例化;如果组件类实现了 yii\base\BootstrapInterface,其 bootstrap() 方法也会被调用(接口方法签名见 framework/base/BootstrapInterface.php)。
对照源码 framework/base/Application.php,bootstrap() 方法的处理逻辑与文档完全一致:先判断 Closure,再判断字符串(依次尝试组件、模块,若既不是组件/模块、又不含命名空间分隔符 \,则抛出 InvalidConfigException("Unknown bootstrapping component ID: ...")),其余情况统一交给 Yii::createObject() 创建实例,最后对实现 BootstrapInterface 的实例调用 bootstrap($this)。
另一个实际例子来自基础项目模板的配置:在开发环境下,debug 和 gii 模块被配置为引导组件:
if (YII_ENV_DEV) {
// 针对 'dev' 环境的配置调整
$config['bootstrap'][] = 'debug';
$config['modules']['debug'] = 'yii\debug\Module';
$config['bootstrap'][] = 'gii';
$config['modules']['gii'] = 'yii\gii\Module';
}
注意:在
bootstrap中放置过多组件会降低应用性能,因为每次请求都要加载同一批组件。请审慎使用引导组件。
catchAll
该属性仅 Web 应用支持(见 framework/web/Application.php)。它指定一个应处理所有请求的控制器 action,通常用于应用处于维护模式、需要通过单个 action 处理所有请求的场景。
配置是一个数组,第一个元素指定 action 的路由,其余元素(键值对)指定要绑定到该 action 的参数。例如:
[
'catchAll' => [
'offline/notice',
'param1' => 'value1',
'param2' => 'value2',
],
]
在 handleRequest()(framework/web/Application.php)中可以看到:当 catchAll 非空时,路由直接取 catchAll[0],其余元素作为参数,完全跳过正常的 URL 解析流程。
components
这是最重要的属性。它允许你注册一系列称为应用组件的组件,供应用各处使用。例如:
[
'components' => [
'cache' => [
'class' => 'yii\caching\FileCache',
],
'user' => [
'identityClass' => 'app\models\User',
'enableAutoLogin' => true,
],
],
]
每个应用组件以数组中的键值对形式指定:键是组件 ID,值是组件类名或配置数组。你可以向应用注册任意组件,之后即可通过全局表达式 \Yii::$app->组件ID 访问。
补充一个源码细节:preInit() 中会把 coreComponents()(framework/base/Application.php)返回的核心组件(log、view、formatter、i18n、urlManager、assetManager、security 等)与你的自定义配置合并;Web 应用在此基础上追加 request、response、session、user、errorHandler(framework/web/Application.php),控制台应用则追加 request、response、errorHandler(framework/console/Application.php)。更多细节请阅读应用组件一节。
controllerMap
该属性允许你把某个控制器 ID 映射到任意控制器类。默认情况下,Yii 基于约定把控制器 ID 映射到控制器类(例如 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,值是控制器类名或配置数组。
controllerNamespace
该属性指定控制器类所在的默认命名空间,默认值为 app\controllers。若控制器 ID 为 post,按约定对应的控制器类名(不含命名空间)是 PostController,完整限定类名是 app\controllers\PostController。
控制器类也可以放在命名空间对应目录的子目录中。例如控制器 ID 为 admin/post 时,对应的完整限定类名是 app\controllers\admin\PostController。
重要前提是:完整限定类名必须能被自动加载,且控制器类的命名空间必须与 controllerNamespace 的值一致,否则访问应用时会得到 "页面未找到"(404)错误。若想打破上述约定,请配置 controllerMap](#controllermap) 属性。该属性的默认值定义在 [framework/base/Application.php。
language
该属性指定应用向最终用户显示内容所使用的语言,用于多语言场景。它会影响国际化的多个方面,包括消息翻译、日期格式、数字格式等——例如 yii\jui\DatePicker 组件默认会依据此属性决定日历以哪种语言显示、日期如何格式化。
建议使用 IETF 语言标签格式指定语言:如 en 表示英语,en-US 表示美国英语。
版本差异提示:官方指南描述该属性默认值为
en,而当前仓库源码 framework/base/Application.php 中实际定义的默认值是'en-US',请以你所用版本的源码为准。
更多细节参见国际化一节。
modules
该属性指定应用包含的模块。它接收一个数组,数组的键是模块 ID,值是模块类名或配置数组。例如:
[
'modules' => [
// 以模块类名指定 "booking" 模块
'booking' => 'app\modules\booking\BookingModule',
// 以配置数组指定 "comment" 模块
'comment' => [
'class' => 'app\modules\comment\CommentModule',
'db' => 'db',
],
],
]
更多细节参见模块一节。
name
该属性指定应用的名称,可以展示给最终用户。与要求唯一值的 id 不同,name 主要用于展示目的,不需要唯一。如果代码中没有使用它,也可以不配置。源码中的默认值为 'My Application'(framework/base/Application.php)。
params
该属性指定一组可在全局访问的应用参数。与其在代码中到处散布硬编码的数字和字符串,更好的做法是把它们集中定义为应用参数,在需要的地方统一使用。例如,可以把图片缩略图尺寸定义为参数:
[
'params' => [
'thumbnail.size' => [128, 128],
],
]
在代码中需要使用该尺寸时:
$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];
之后如果决定修改缩略图尺寸,只需修改应用配置,无需触碰任何依赖代码。
sourceLanguage
该属性指定应用源码编写所用的语言,默认值为 'en-US'(美国英语)。如果代码中的文本内容不是英文,就应该配置该属性。与 language 一样,建议使用 IETF 语言标签格式。更多细节参见国际化。
timeZone
该属性提供了一种在运行时设置 PHP 时区的替代方式。配置该属性本质上等同于调用 PHP 的 date_default_timezone_set() 函数。例如:
[
'timeZone' => 'America/Los_Angeles',
]
源码中 setTimeZone()(framework/base/Application.php)就是一行 date_default_timezone_set($value) 的封装。另外值得注意:preInit() 中如果既没有配置 timeZone、php.ini 中也没有 date.timezone,框架会默认设置为 UTC(L245-L247)。
version
该属性指定应用的版本号,默认值为 '1.0'。如果代码中没有任何地方使用它,可以不配置。
3.3 常用属性(Useful Properties)
这些属性一般不需要配置,因为它们的默认值已经体现了通用约定;但在需要打破约定时可以自行配置。
charset
指定应用使用的字符集,默认值为 'UTF-8'。对绝大多数应用应保持默认值,除非你在处理包含大量非 Unicode 数据的遗留系统。源码定义见 framework/base/Application.php。
defaultRoute
指定当请求未指定路由时应用应使用的路由。路由可以由模块 ID、控制器 ID 和/或 action ID 组成,例如 help、post/create、admin/post/create。如果未提供 action ID,则取 yii\base\Controller::defaultAction 指定的值。
- 对 Web 应用,默认值为
'site',即使用SiteController及其默认 action。因此不带路由访问应用时,会显示app\controllers\SiteController::actionIndex()的结果; - 对控制台应用,默认值为
'help',即使用核心命令yii\console\controllers\HelpController::actionIndex()。因此不带任何参数运行yii命令时,会显示帮助信息。
两者的默认值分别定义在 framework/web/Application.php 和 framework/console/Application.php。
extensions
指定应用已安装并使用的扩展列表。默认情况下,它取 @vendor/yiisoft/extensions.php 文件返回的数组;该文件由 Composer 在安装扩展时自动生成和维护,因此大多数情况下无需手动配置。
如果你希望手动维护扩展列表,可以这样配置:
[
'extensions' => [
[
'name' => 'extension name',
'version' => 'version number',
'bootstrap' => 'BootstrapClassName', // 可选,也可以是配置数组
'alias' => [ // 可选
'@alias1' => 'to/path1',
'@alias2' => 'to/path2',
],
],
// ... 更多扩展 ...
],
]
该属性接收一组扩展规格数组,每个扩展至少包含 name 和 version。如果扩展需要在引导过程中执行,可以指定 bootstrap 元素(引导类名或配置数组);扩展还可以定义一些别名。在源码的 bootstrap() 方法中(framework/base/Application.php),扩展的别名会先被注册,然后引导类会被实例化并(在实现 BootstrapInterface 时)调用其 bootstrap() 方法。
layout
指定渲染视图时使用的默认布局名称,默认值为 'main',即使用 layoutPath 下的 main.php 布局文件。如果 layoutPath 和 viewPath 都保持默认值,该默认布局文件可用路径别名 @app/views/layouts/main.php 表示。你也可以把该属性设为 false 来默认禁用布局(这种情况非常少见)。
layoutPath
指定查找布局文件的路径,默认值是 viewPath 目录下的 layouts 子目录。如果 viewPath 保持默认值,默认布局路径可用别名 @app/views/layouts 表示。可以配置为目录或路径别名。
runtimePath
指定日志、缓存等临时文件可写入的路径,默认值是别名 @app/runtime 对应的目录。可以配置为目录或路径别名。注意:该路径必须对运行应用进程可写,同时应受到保护、不能被最终用户访问,因为其中的临时文件可能包含敏感信息。
为方便访问,Yii 为该路径预定义了路径别名 @runtime。源码中 setRuntimePath()(framework/base/Application.php)在设置路径的同时会执行 Yii::setAlias('@runtime', ...)。
viewPath
指定视图文件所在的根目录,默认目录用别名 @app/views 表示。可以配置为目录或路径别名。
vendorPath
指定由 Composer 管理的 vendor 目录,其中包含应用使用的全部第三方库,包括 Yii 框架本身。默认值是别名 @app/vendor 对应的目录。可以配置为目录或路径别名;修改该属性时,请确保同步调整 Composer 的配置。
Yii 为它预定义了路径别名 @vendor。源码中 setVendorPath()(framework/base/Application.php)还会顺带定义 @bower 与 @npm 别名(分别指向 vendor 下的 bower 与 npm 子目录)。
enableCoreCommands
该属性仅控制台应用支持,指定是否启用 Yii 框架内置的核心命令,默认值为 true(framework/console/Application.php)。在 init() 方法(L123-L137)中,若该属性为 true,内置命令(asset、cache、fixture、help、message、migrate、serve,见 coreCommands() L192-L203)会被注册进 controllerMap(除非已被自定义覆盖),并且无论怎样都会确保 help 命令存在。
四、应用事件(Application Events)
应用在请求处理的生命周期中会触发多个事件。你可以在应用配置中以如下方式绑定事件处理器:
[
'on beforeRequest' => function ($event) {
// ...
},
]
on 事件名 的语法在配置一节中有详细说明。
另外,你也可以在应用实例创建后的引导过程中,以编程方式绑定事件处理器,例如:
\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
// ...
});
事件常量定义于 framework/base/Application.php:EVENT_BEFORE_REQUEST = 'beforeRequest'、EVENT_AFTER_REQUEST = 'afterRequest'。
EVENT_BEFORE_REQUEST
该事件在应用处理请求之前触发,事件名为 beforeRequest。
触发时,应用实例已经完成配置和初始化,因此这是通过事件机制插入自定义代码、拦截请求处理流程的好时机。例如,在事件处理器中可以根据某些参数动态设置 language 属性。
EVENT_AFTER_REQUEST
该事件在应用结束请求处理之后、发送响应之前触发,事件名为 afterRequest。
触发时请求处理已完成,可以借此机会对请求做后处理,或自定义响应内容。注意:yii\web\Response 响应组件在向最终用户发送内容时也会触发一些事件,这些事件在本事件之后触发。
EVENT_BEFORE_ACTION
该事件在每个控制器 action执行之前触发,事件名为 beforeAction。
事件参数是 yii\base\ActionEvent 实例。事件处理器可以把 ActionEvent::isValid 设为 false 来中断 action 的执行。例如:
[
'on beforeAction' => function ($event) {
if (某种条件) {
$event->isValid = false;
} else {
}
},
]
注意:同样的 beforeAction 事件也会由模块和控制器触发。触发顺序是:Application 对象最先触发,接着是模块(如有),最后是控制器。如果某个事件处理器把 ActionEvent::isValid 设为 false,则后续所有事件都不会再触发。
EVENT_AFTER_ACTION
该事件在每个控制器 action执行之后触发,事件名为 afterAction。
事件参数同样是 yii\base\ActionEvent 实例。通过其 result 属性,事件处理器可以访问或修改 action 的执行结果。例如:
[
'on afterAction' => function ($event) {
if (某种条件) {
// 修改 $event->result
} else {
}
},
]
注意:afterAction 事件同样由模块和控制器触发,但触发顺序与 beforeAction 相反:控制器最先触发,接着是模块(如有),最后才是 Application 对象。
五、应用生命周期(Application Lifecycle)
当入口脚本处理一次请求时,应用会经历如下生命周期(文档原文的四个步骤):
- 入口脚本加载应用配置(以数组形式);
- 入口脚本创建新的应用实例:
- 调用
preInit(),配置basePath等高优先级属性; - 注册错误处理器;
- 配置应用属性;
- 调用
init(),init()内部调用bootstrap()运行引导组件;
- 调用
- 入口脚本调用
run()执行应用:- 触发
EVENT_BEFORE_REQUEST; - 处理请求:把请求解析为路由及关联参数;按路由创建模块、控制器和 action 对象;执行 action;
- 触发
EVENT_AFTER_REQUEST; - 向最终用户发送响应;
- 触发
- 入口脚本接收应用的退出状态码,完成请求处理。
对照源码 run() 方法(framework/base/Application.php),可以看到整个流程由一个显式的状态机驱动,状态常量定义于 L61-L85:
STATE_BEGIN → STATE_INIT → STATE_BEFORE_REQUEST → STATE_HANDLING_REQUEST
→ STATE_AFTER_REQUEST → STATE_SENDING_RESPONSE → STATE_END
具体代码如下:
public function run()
{
try {
$this->state = self::STATE_BEFORE_REQUEST;
$this->trigger(self::EVENT_BEFORE_REQUEST);
$this->state = self::STATE_HANDLING_REQUEST;
$response = $this->handleRequest($this->getRequest());
$this->state = self::STATE_AFTER_REQUEST;
$this->trigger(self::EVENT_AFTER_REQUEST);
$this->state = self::STATE_SENDING_RESPONSE;
$response->send();
$this->state = self::STATE_END;
return $response->exitStatus;
} catch (ExitException $e) {
$this->end($e->statusCode, isset($response) ? $response : null);
return $e->statusCode;
}
}
其中 handleRequest() 是抽象方法,由 Web 与 Console 两个子类分别实现:
- Web 应用的
handleRequest()(framework/web/Application.php)负责解析路由(或使用catchAll)、执行 action,并把结果写入response组件的data;路由非法时抛出NotFoundHttpException(页面未找到)。 - 控制台应用的
handleRequest()(framework/console/Application.php)把 action 的返回值作为exitStatus(退出码),0 表示正常。
另外还有一个实用机制:控制台应用支持在命令行中用 --appconfig=路径 选项显式指定配置文件(见 loadConfig(),framework/console/Application.php),未指定时则使用构造函数传入的配置。
六、结合源码继续深入
如果希望进一步研究 Application 的底层实现,本仓库中以下文件是最直接的阅读入口:
- framework/base/Application.php:抽象基类,包含全部属性声明、
preInit()/init()/bootstrap()/run()/end()核心方法、核心组件注册与状态机; - framework/web/Application.php:Web 应用实现,
defaultRoute、catchAll、@webroot/@web别名与请求处理逻辑; - framework/console/Application.php:控制台应用实现,内置命令注册、
--appconfig选项与命令处理逻辑; - framework/base/BootstrapInterface.php:引导接口,实现该接口的类会在应用引导阶段被调用
bootstrap($app); - framework/base/ActionEvent.php:
beforeAction/afterAction事件参数对象,提供isValid与result属性。
配套的官方文档还建议继续阅读:入口脚本、配置、应用组件、模块、控制器、运行引导以及路由等章节,从而把"应用对象"这一顶层骨架与控制器、模块、组件、路由等具体部件串联成完整的 Yii 2 运行图景。