Yii 2 应用对象(Application)深入解析:配置属性、请求事件与生命周期

原创2026-09-22 12:41:251,962 阅读
文章标签:后端Web框架

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 提供两种类型的应用:

从源码结构看,两者都继承自 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)

当入口脚本处理一次请求时,应用会经历如下生命周期(文档原文的四个步骤):

  1. 入口脚本加载应用配置(以数组形式);
  2. 入口脚本创建新的应用实例:
    • 调用 preInit(),配置 basePath 等高优先级属性;
    • 注册错误处理器;
    • 配置应用属性;
    • 调用 init(),init() 内部调用 bootstrap() 运行引导组件;
  3. 入口脚本调用 run() 执行应用:
    • 触发 EVENT_BEFORE_REQUEST;
    • 处理请求:把请求解析为路由及关联参数;按路由创建模块、控制器和 action 对象;执行 action;
    • 触发 EVENT_AFTER_REQUEST;
    • 向最终用户发送响应;
  4. 入口脚本接收应用的退出状态码,完成请求处理。

对照源码 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 的底层实现,本仓库中以下文件是最直接的阅读入口:

配套的官方文档还建议继续阅读:入口脚本、配置、应用组件、模块、控制器、运行引导以及路由等章节,从而把"应用对象"这一顶层骨架与控制器、模块、组件、路由等具体部件串联成完整的 Yii 2 运行图景。

登录后查看全文
yii2