Yii 2 框架应用(Application)深入解析:配置、属性、事件与完整生命周期

原创2026-09-22 21:13:291,606 阅读
文章标签:后端Web框架

Yii 2 框架应用(Application)深入解析:配置、属性、事件与完整生命周期

本指南以 Yii 2 官方文档 structure-applications.md(法语版)为骨架,结合仓库内 framework/base/Application.php 等核心源码与 tests/framework/base/ApplicationTest.php 测试用例,系统讲解 Yii 2 应用对象的本质、两种应用类型、配置方式、全部核心属性、生命周期事件与请求处理流程。读完本文,你将能独立编写入口脚本与配置文件,正确设置 id、basePath、bootstrap、components 等关键属性,并利用应用事件在合适的时机注入自定义逻辑。

Yii 2 应用生命周期图

Yii 2 应用从入口脚本加载到响应发送的完整生命周期(图片来源:docs/guide-fr/images/application-lifecycle.png)

一、什么是 Yii 2 应用(Application)

在 Yii 2 中,应用(Application) 是统辖整个系统结构与生命周期运行的对象。每一个基于 Yii 2 实现的系统都包含一个唯一的应用对象,它由 入口脚本 创建,并可通过全局表达式 \Yii::$app 在任何地方访问。

Info:根据上下文,「应用」一词可能指代应用对象本身,也可能指代整个基于 Yii 2 实现的系统。

在源码中,应用基类定义于 framework/base/Application.php,它继承自 Module.php(模块基类)。从源码结构看,Application 与模块共享大量路径、命名空间与路由逻辑,可以理解为「应用是一个特殊的顶层模块」。

Yii 2 提供两种应用类型:

类型 类名 职责
Web 应用 yii\web\Application 处理 HTTP Web 请求
控制台应用 yii\console\Application 处理命令行(Console)请求

对应源码位于 framework/web/Application.php 与 framework/console/Application.php。两种应用各自实现 handleRequest() 抽象方法:Web 应用负责将 HTTP 请求解析为 路由 并执行动作,控制台应用则将命令行参数解析为命令并执行。

二、应用配置(Application Configurations)

当 入口脚本 创建应用时,它会加载一份 配置 并应用到应用对象上。典型的 Web 入口脚本(如 Basic 项目模板的 web/index.php)如下:

require __DIR__ . '/../vendor/autoload.php';
require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';

// 加载应用配置
$config = require __DIR__ . '/../config/web.php';

// 实例化并配置应用
(new yii\web\Application($config))->run();

与普通 配置 一样,应用配置指明了如何初始化应用对象的各个属性。由于应用配置通常非常复杂,实践中一般将其保存在 配置文件 中(如上述示例中的 web.php),而不是内联在入口脚本里。

从源码角度看,Application::__construct() 的构造顺序非常关键:

  1. 将 $this 赋给 Yii::$app,并调用 static::setInstance($this) 注册为模块单例;
  2. 将状态置为 STATE_BEGIN(状态机初态);
  3. 调用 preInit($config) 预处理高优先级属性(basePath、vendorPath、runtimePath、timeZone、container 等);
  4. 调用 registerErrorHandler($config) 注册错误处理器组件;
  5. 最后通过 Component::__construct($config) 完成其余属性的配置。

需要特别注意的是,preInit() 中会强制校验 id 与 basePath 必须存在,否则抛出 InvalidConfigException;同时它会将 coreComponents() 返回的核心组件(log、view、formatter、i18n、urlManager、assetManager、security、mailer 等,见 coreComponents())与用户自定义的 components 合并,确保核心组件始终可用。

三、应用属性(Application Properties)

应用有许多重要属性需要在配置中指定,它们描述了应用运行的环境,例如如何加载 控制器、临时文件存放在哪里等。以下按「必需属性 → 重要属性 → 有用属性」三档逐一说明。

3.1 必需属性(Required Properties)

任何应用中至少必须指定两个属性:id 与 basePath。

id

属性 id 指定一个区分于其他应用的唯一标识,主要用于程序指令中。虽然不是硬性要求,但建议仅使用字母数字字符,以保证更好的互操作性。

源码侧,preInit() 在缺失 id 时直接抛出异常:The "id" configuration for the Application is required.,可见 id 是应用可创建的前提。

basePath

属性 basePath 指定应用的根目录,即存放应用全部受保护源码的目录,通常包含 models、views、controllers 等 MVC 子目录。

配置该属性可以使用目录路径或 路径别名。无论哪种方式,对应的目录必须存在,否则会抛出异常;路径会通过 realpath() 函数规范化。

从源码看,Module::setBasePath() 的实现为:

$path = Yii::getAlias($path);
$p = strncmp($path, 'phar://', 7) === 0 ? $path : realpath($path);
if (is_string($p) && is_dir($p)) {
    $this->_basePath = $p;
} else {
    throw new InvalidArgumentException("The directory does not exist: $path");
}

它先解析别名,再调用 realpath() 规范化并校验目录是否存在;若未配置 basePath,则 Module::getBasePath() 会通过反射(ReflectionClass)从应用类文件所在目录推断。设置 basePath 后,Application::setBasePath() 还会同步预定义别名 @app 指向该根目录。

basePath 经常被用来派生其他重要路径(如 runtime 路径),例如 @app/runtime 即指向应用的 runtime 目录。

3.2 重要属性(Important Properties)

以下属性通常需要显式配置,因为它们在不同应用中往往取值不同。

aliases

该属性允许以关联数组形式定义一组 别名:键为别名名称,值为路径定义。例如:

[
    'aliases' => [
        '@name1' => 'chemin/vers/dossier1', // 路径/目录1
        '@name2' => 'chemin/vers/dossier2', // 路径/目录2
    ],
]

提供该属性是为了避免你在代码中通过 Yii::setAlias() 逐个定义别名。

bootstrap(引导组件)

该属性非常有用,它允许指定一个组件数组,这些组件会在 引导(bootstrap)过程 中被执行。例如,若想使用 模块 定制 URL 规则,可以把该模块的 ID 作为该属性的元素。

bootstrap 中的每个组件可以以下列任意一种形式指定:

  • 通过 components 指定的应用组件 ID;
  • 通过 modules 指定的模块 ID;
  • 一个类名;
  • 一个配置数组;
  • 一个创建并返回组件的匿名函数。

例如:

[
    'bootstrap' => [
        // 应用组件 ID 或模块 ID
        'demo',

        // 类名
        'app\components\Profiler',

        // 配置数组
        [
            'class' => 'app\components\Profiler',
            'level' => 3,
        ],

        // 匿名函数
        function () {
            return new app\components\Profiler();
        }
    ],
]

Info:如果某模块 ID 与某应用组件 ID 相同,引导时会优先使用应用组件。若确实想引导模块,可通过匿名函数指定,例如:

[
    function () {
        return Yii::$app->getModule('user');
    },
]

引导过程中每个组件都会被实例化;若组件类实现了 BootstrapInterface,其 bootstrap() 方法也会被调用。

源码实现见 Application::bootstrap():它首先加载 @vendor/yiisoft/extensions.php 中的扩展列表并执行扩展的引导;随后遍历 bootstrap 属性——匿名函数通过 call_user_func 调用,字符串优先匹配已注册组件($this->has())与模块($this->hasModule()),含命名空间反斜杠的字符串会被当作类名通过 Yii::createObject() 创建,否则抛出 InvalidConfigException。

测试用例 ApplicationTest::testBootstrap() 验证了组件 ID、模块 ID 与匿名函数三种引导形式,并断言实现了 BootstrapInterface 的组件其 bootstrap() 方法确实被调用(日志中出现 Bootstrap with ...::bootstrap())。

一个实用的例子来自 Basic 项目模板 的应用配置:开发环境下将 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';
}

Note:在 bootstrap 中放置过多组件会降低应用性能,因为每次请求都要执行同一组组件。因此应谨慎使用引导组件。

catchAll(Web 应用专用)

该属性仅由 Web 应用 支持。它指定一个接管所有用户请求的 控制器动作,主要用于维护模式:用一个动作统一处理所有请求。配置是一个数组,第一个元素指定动作路由,其余元素(键值对)指定传给该动作的参数。例如:

[
    'catchAll' => [
        'offline/notice',
        'param1' => 'valeur1',
        'param2' => 'valeur2',
    ],
]

Info:启用该属性后,开发环境下的调试面板将无法工作。

源码侧,web/Application::handleRequest() 中会先判断 catchAll 是否为空:非空时直接取 $route = $this->catchAll[0],并把 catchAll 数组去掉首元素后作为动作参数,从而绕过正常的请求路由解析。

components(组件)

这是最重要的属性,没有之一。它允许按名称注册一组可在任何地方使用的 应用组件。例如:

[
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'user' => [
            'identityClass' => 'app\models\User',
            'enableAutoLogin' => true,
        ],
    ],
]

每个应用组件以数组中的键值对形式指定:键为组件 ID,值为组件类名或 配置 数组。注册后即可通过 \Yii::$app->componentID 全局访问(例如 \Yii::$app->cache、\Yii::$app->user)。

从源码看,核心组件在 coreComponents() 中预定义(log、view、formatter、i18n、urlManager、assetManager、security,以及存在 swiftmailer 时的 mailer),并在 preInit() 阶段与自定义配置合并;Application.php 还提供了 getDb()、getLog()、getErrorHandler()、getCache()、getRequest()、getResponse()、getView()、getUrlManager()、getI18n()、getMailer()、getAuthManager()、getAssetManager()、getSecurity() 等便捷访问器。详细说明参见 应用组件 一节。

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。

关键点:控制器类必须能被 自动加载,且类实际命名空间必须与属性值一致,否则访问应用时会得到「页面未找到(Page not found)」错误。要绕过该约定,需配置 controllerMap。

源码中该属性定义于 Application.php,默认值即 'app\\controllers'。

language(语言)

该属性指定应用向最终用户呈现内容所用的语言,默认值为 en(英语)。若应用需要支持多语言,则必须配置该属性。

该属性值会影响 国际化 的诸多方面,例如消息翻译、日期与数字格式化等。比如 DatePicker 组件会根据该属性决定日历以何种语言显示、日期如何格式化。

建议使用 IETF 语言标签 指定语言,例如 en 表示英语,en-US 表示英语(美国)。

更多信息参见 国际化 一节。补充源码细节:基类默认值实为 'en-US'(见 Application.php),而文档正文以指南语境描述的 en 为最小表达形式,两者并不冲突——en 与 en-US 都是合法的 IETF 标签。

modules(模块)

该属性指定应用包含的 模块。它接受模块类数组或 配置 数组,数组键为模块 ID。例如:

[
    'modules' => [
        // 以类名指定的 "booking"(预订)模块
        'booking' => 'app\modules\booking\BookingModule',

        // 以配置数组指定的 "comment"(评论)模块
        'comment' => [
            'class' => 'app\modules\comment\CommentModule',
            'db' => 'db',
        ],
    ],
]

完整说明参见 模块 一节。

name(名称)

该属性指定展示给最终用户的应用名称。与只能取唯一值的 id 不同,name 仅用于显示,不要求唯一。若代码中不使用它,则无需配置。

params(参数)

该属性指定一个全局可访问的应用参数数组。好的实践是:不要在你的代码中到处硬编码数字与字符串,而是将它们一次性定义为参数,在需要处引用;这样修改取值时只需改动配置,无需触碰代码。例如,将图片缩略图尺寸定义为参数:

[
    'params' => [
        'thumbnail.size' => [128, 128],
    ],
]

随后在代码中使用:

$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];

以后若要修改缩略图尺寸,只需改应用配置中的参数值,无需改动代码。

sourceLanguage(源码语言)

该属性指定应用编写时所用的语言,默认值为 'en-US'(英语——美国)。如果代码中的文本不是美式英语,应配置该属性。

与 language 属性一样,建议使用 IETF 语言标签 指定,如 en 表示英语,en-US 表示英语(美国)。

更多信息参见 国际化 一节。

timeZone(时区)

该属性提供了一种在 PHP 脚本运行时设置默认时区的替代方式。配置该属性本质上等价于调用 PHP 函数 date_default_timezone_set()。例如:

[
    'timeZone' => 'America/Los_Angeles',
]

源码侧,Application::setTimeZone() 正是对 date_default_timezone_set($value) 的简单封装,而 getTimeZone() 返回 date_default_timezone_get()。值得注意的是,preInit() 中若既未在配置里设置时区、php.ini 也未配置 date.timezone,Yii 会自动将时区设为 UTC。

version(版本)

该属性指定应用的版本号,默认值为 '1.0'。若代码中不使用它,则无需配置。

3.3 有用属性(Useful Properties)

以下属性通常无需配置,因为其默认值已由常规约定推导出来;但你可以显式配置以覆盖约定。

charset(字符集)

该属性指定应用使用的字符集,默认值为 'UTF-8'。大多数应用应保持默认值,除非你在维护大量非 Unicode 数据的旧系统。

defaultRoute(默认路由)

该属性指定当请求未携带任何路由时应用应使用的 路由。路由可以由模块 ID、控制器 ID 和/或动作 ID 组成,例如 help、post/create 或 admin/post/create。若未提供动作 ID,则使用 Controller::defaultAction 指定的默认动作。

  • 对于 Web 应用,默认值为 'site',即使用 SiteController 及其默认动作。因此不带路由访问应用时,执行的是 app\controllers\SiteController::actionIndex()。
  • 对于 控制台应用,默认值为 'help',即执行 HelpController::actionIndex()。因此直接运行 yii 命令而不带参数时,应用会显示帮助信息。

源码印证:web/Application.php 中 public $defaultRoute = 'site'(framework/web/Application.php),console/Application.php 中 public $defaultRoute = 'help'(framework/console/Application.php),而基类 Module::$defaultRoute 默认值为 'default'。

extensions(扩展)

该属性指定应用安装并使用的 扩展 列表。默认情况下,它取 @vendor/yiisoft/extensions.php 文件返回的数组。该文件由 Composer 安装扩展时自动生成和维护,因此大多数情况下无需手动配置。

特殊情况下若你想手工维护扩展列表,可如下配置:

[
    'extensions' => [
        [
            'name' => 'extension name', // 扩展名
            'version' => 'version number', // 版本号
            'bootstrap' => 'BootstrapClassName',  // 可选,也可以是配置数组
            'alias' => [  // 可选
                '@alias1' => 'vers/chemin1', // 至路径1
                '@alias2' => 'vers/chemin2', // 至路径2
            ],
        ],

        // ... 其他扩展的类似配置 ...

    ],
]

该属性接收扩展规格数组,每个扩展由 name 与 version 构成。若扩展需要在 引导 过程中执行,需通过引导类名(bootstrap)或 配置 数组指定 bootstrap 元素;扩展还可以定义一些 别名。

源码印证见 Application.php 的属性注释,以及 bootstrap() 中对扩展别名与引导类的处理逻辑。

layout(布局)

该属性指定渲染 视图 时使用的默认 布局(layout)名称,默认值为 'main',即使用 layoutPath 下的 main.php 布局文件。当 layoutPath 与 viewPath 均取默认值时,默认布局文件可用别名 @app/views/layouts/main.php 表示。

可将该属性设为 false 来禁用默认布局(虽不常见)。

layoutPath(布局路径)

该属性指定查找布局文件的目录,默认值 layouts 是 viewPath 的子目录。若 viewPath 取默认值,则默认布局路径可用别名 @app/views/layouts 表示。可以将其配置为目录路径或 别名。

源码侧,Module::getLayoutPath() 默认返回 viewPath/layouts。

runtimePath(运行时目录)

该属性指定存放临时文件(如日志、缓存文件)的目录,默认值为 @app/runtime。可以配置为目录路径或 别名。注意:该目录必须对运行应用的用户进程可写,同时必须对最终用户不可访问,因为其中的临时文件可能包含敏感信息。

为方便访问该路径,Yii 预定义了别名 @runtime。源码中 setRuntimePath() 在设置路径的同时会执行 Yii::setAlias('@runtime', ...);getRuntimePath() 默认返回 basePath/runtime(framework/base/Application.php)。

viewPath(视图路径)

该属性指定视图文件的根目录,默认值为别名 @app/views 对应的目录。可配置为目录路径或 别名。源码中 Module::getViewPath() 默认返回 basePath/views。

vendorPath(供应商目录)

该属性指定由 Composer 管理的供应商目录,其中包含应用使用的全部第三方库(包括 Yii 框架本身),默认值为 @app/vendor 对应的目录。可配置为目录路径或 别名;修改该属性时,请务必同步调整 Composer 配置。

为方便访问该路径,Yii 预定义了别名 @vendor。此外,setVendorPath() 还会顺带预定义 @bower 与 @npm 别名,指向供应商目录下的 bower 与 npm 子目录。

enableCoreCommands(控制台应用专用)

该属性仅由 控制台应用 支持,指定是否启用 Yii 版本自带的核心命令,默认值为 true。

源码印证:console/Application::init() 在 enableCoreCommands 为真时,会将 coreCommands() 返回的核心命令逐一注册到 controllerMap,同时确保 help 命令始终可用(用于列出可用命令)。

四、应用事件(Application Events)

应用在整个请求处理的生命周期中会触发多个事件。你可以在应用配置中以如下方式为这些事件挂接处理器:

[
    'on beforeRequest' => function ($event) {
        // ...
    },
]

on 事件名 的语法在 配置格式 一节有详细说明。

另一种方式是:在应用对象实例化之后、引导过程 中编程式挂接处理器,例如:

\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
    // ...
});

事件常量定义于 Application.php,核心四个事件如下。

4.1 EVENT_BEFORE_REQUEST

该事件在应用开始处理请求之前触发,事件名称为 beforeRequest。

触发时应用对象已完成配置与初始化,因此这是通过事件机制插入自定义代码来拦截请求处理流程的好时机。例如,在事件处理器中可以根据某些参数动态设置 language(语言) 属性。

源码印证:run() 中先置状态为 STATE_BEFORE_REQUEST 再 trigger(self::EVENT_BEFORE_REQUEST)。

4.2 EVENT_AFTER_REQUEST

该事件在应用处理完请求之后、发送响应之前触发,事件名称为 afterRequest。

触发时请求处理已经完成,可以利用这个时机执行一些请求后置处理,并定制响应。注意:响应组件在向浏览器发送响应时还会触发一些自己的事件,这些事件都在该事件之后触发。

源码印证:run() 在 handleRequest() 返回后置状态为 STATE_AFTER_REQUEST 并触发该事件。另外,end() 在应用提前终止时(如调用 exit 的场景)也会兜底触发 EVENT_AFTER_REQUEST,确保生命周期完整。

4.3 EVENT_BEFORE_ACTION

该事件在执行任意 控制器动作 之前触发,事件名称为 beforeAction,事件参数是 ActionEvent 实例。处理器可以将 ActionEvent::isValid 置为 false 以阻止动作执行。例如:

[
    'on beforeAction' => function ($event) {
        if (some condition) {
            $event->isValid = false;
        } else {
        }
    },
]

注意:相同的 beforeAction 事件也会被 模块 和 控制器 触发。触发顺序为:应用最先触发,然后是模块(若有),最后是控制器。若某处理器将 ActionEvent::isValid 置为 false,则后续所有应触发的事件都不会再触发。

4.4 EVENT_AFTER_ACTION

该事件在每个 控制器动作 执行之后触发,事件参数为 ActionEvent。处理器可以通过 ActionEvent::result 属性访问并修改动作结果。例如:

[
    'on afterAction' => function ($event) {
        if (some condition) {
            // 修改 $event->result
        } else {
        }
    },
]

注意:相同的 afterAction 事件也会被模块和控制器触发,且触发顺序与 beforeAction 相反:控制器最先触发,然后是模块(若有),最后才是应用。

五、应用生命周期(Application Lifecycle)

上图(见文首)展示了应用从入口脚本到响应返回的完整生命周期。当 入口脚本 被执行为处理一次请求时,应用经历以下生命周期:

  1. 入口脚本以数组形式加载应用配置。
  2. 入口脚本创建新的应用对象:
    • 调用其 preInit() 方法,配置一些高优先级属性(如 basePath、vendorPath、runtimePath、timeZone、container 等);
    • 注册 错误处理器;
    • 配置应用其余属性;
    • 调用 init(),后者继而调用 bootstrap() 执行引导组件。
  3. 入口脚本调用 run() 方法运行应用,该过程:
    • 触发 EVENT_BEFORE_REQUEST;
    • 处理请求:将请求解析为 路由 及其关联参数;
    • 创建路由指定的模块、控制器与动作,并执行动作;
    • 触发 EVENT_AFTER_REQUEST;
    • 将响应发送给浏览器。
  4. 入口脚本接收应用的退出状态码,完成请求处理流程。

从源码角度,run() 内部使用显式状态机推进(状态常量定义于 Application.php):STATE_BEGIN → STATE_INIT → STATE_BEFORE_REQUEST → STATE_HANDLING_REQUEST → STATE_AFTER_REQUEST → STATE_SENDING_RESPONSE → STATE_END。在 Web 应用中,handleRequest()(framework/web/Application.php)会先检查 catchAll,否则通过 $request->resolve() 解析路由,再调用 runAction() 执行动作,最终由 $response->send() 输出响应。

六、延伸阅读

登录后查看全文
yii2