Yii 2 应用（Application）完全指南：配置、核心属性、事件与请求生命周期

后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载导读在 Yii 2 中应用Application是管理整个应用系统结构与生命周期的核心对象每个 Yii 应用系统只包含一个应用对象它在入口脚本中被创建并通过全局表达式\Yii::$app随处访问。本指南以官方文档 structure-applications 为主体结合仓库源码framework/base/Application.php、framework/web/Application.php、framework/console/Application.php深入讲解应用的两种类型、配置加载方式、全部关键属性、生命周期事件与内部状态机读完你即可独立完成应用级配置、维护模式开关、启动组件注册与请求拦截等实战任务。什么是应用两种类型应用这一术语根据上下文既可以指应用对象object也可以指应用系统application system整体。每个 Yii 应用系统包含且仅包含一个应用对象它在入口脚本中创建全局可访问// 入口脚本如 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();Yii 提供两种应用类型二者都继承自抽象基类yii\base\Application类型类名职责默认路由Web 应用[[yii\web\Application]]处理 Web 请求HTTPsite控制台应用[[yii\console\Application]]处理控制台命令请求CLIhelp从源码结构看framework/base/Application.phpApplication本身是抽象类它继承自yii\base\Module因此应用本质上也具备模块的一切能力web与console两个子类分别实现handleRequest()抽象方法见 framework/web/Application.php 与 framework/console/Application.php从而决定请求如何被解析和执行。应用配置入口脚本如何初始化应用与普通配置一样应用配置以名-值对数组的形式指定如何初始化应用对象的属性。由于应用配置通常非常复杂实践中被拆分为多个配置文件存放典型如config/web.php、config/console.php。在构造应用对象时Yii 会执行一套固定的初始化流程。以源码__construct()framework/base/Application.php为准顺序如下将自身注册到Yii::$app与模块静态实例中将state置为STATE_BEGIN调用preInit($config)——处理basePath、vendorPath、runtimePath、timeZone、container等高优先级属性并将核心组件与自定义组件合并见 framework/base/Application.php调用registerErrorHandler($config)——注册错误处理器组件framework/base/Application.php通过Component::__construct($config)完成其余属性的批量配置init()被调用其中再调用bootstrap()执行扩展与启动组件的引导framework/base/Application.php。值得注意preInit()中如果配置里缺少id或basePath会直接抛出InvalidConfigExceptionvendorPath、runtimePath未显式配置时会自动按默认约定建立vendor、runtime别名。timeZone若未配置且php.ini中date.timezone为空则默认设为UTC。必填属性在任何应用中你至少必须配置两个属性idid是应用的唯一标识符用于在程序层面区分不同应用。它不是严格必填的校验项但为了最佳互操作性官方强烈建议只使用字母数字字符如app-frontend、app-backend。basePathbasePath指定应用的根目录即包含应用系统全部受保护源码的目录。在该目录下通常可以看到models、views、controllers等对应 MVC 模式的子目录。配置方式有两种直接指定目录路径使用路径别名如app本身。无论哪种形式对应目录必须真实存在否则会抛出异常路径会通过realpath()函数规范化。源码Module::setBasePath()framework/base/Module.php先调用Yii::getAlias()解析别名再对路径执行realpath()并校验is_dir()。basePath常被用来推导其他重要路径因此 Yii 预定义了路径别名app指向它。应用级setBasePath()在设置路径的同时自动调用Yii::setAlias(app, ...)见 framework/base/Application.php。派生路径即可基于该别名构造例如app/runtime指向 runtime 目录。重要属性以下属性在不同应用中通常取值不同最常需要显式配置。aliases允许在配置数组中批量定义别名数组键为别名名称值为对应的路径定义[ aliases [ name1 path/to/path1, name2 path/to/path2, ], ]设置该属性的目的是让你能在应用配置中声明别名而无需在代码里调用Yii::setAlias()方法。bootstrap这是非常实用的属性指定一组在应用启动引导bootstrapping阶段就要执行的组件。典型场景是让某个模块在启动时注册自定义 URL 规则。每个列表项可以有下列 5 种格式应用组件 ID由components定义模块 ID由modules定义类名配置数组匿名函数创建并返回一个组件对象。示例[ bootstrap [ // 应用组件 ID 或模块 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()方法也会被调用。该逻辑在源码Application::bootstrap()中完整实现framework/base/Application.php字符串先依次尝试组件has()与模块hasModule()查找都不是且不含命名空间分隔符\时抛出 Unknown bootstrapping component ID 异常最后统一通过Yii::createObject()创建并检查是否实现BootstrapInterface。另一个实用例子来自基础项目模板在开发环境下把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 应用该属性只被 Web 应用支持指定一个控制器动作来处理所有用户请求主要用于应用处于维护模式时让所有请求统一经过单个动作。配置是一个数组第一个元素是动作的路由其余键-值对是要绑定给该动作的参数[ catchAll [ offline/notice, param1 value1, param2 value2, ], ]源码层面Web Application::handleRequest()framework/web/Application.php在catchAll非空时不再解析真实路由而是直接取catchAll[0]作为路由、其余元素作为参数执行动作。官方文档另有提示启用该属性时开发环境的调试面板将无法工作。components这是最重要的属性用于注册一组命名的应用组件供应用其他位置使用[ components [ cache [ class yii\caching\FileCache, ], user [ identityClass app\models\User, enableAutoLogin true, ], ], ]每个组件以键-值对形式定义键是组件 ID值是组件类名或配置数组。注册后即可通过全局表达式\Yii::$app-componentID访问。补充一个源码事实Yii 内置了一批核心组件在preInit()阶段会与自定义组件自动合并framework/base/Application.php。基类coreComponents()framework/base/Application.php声明了log、view、formatter、i18n、urlManager、assetManager、security等Web 应用在此基础上追加request、response、session、user、errorHandlerframework/web/Application.php。若你的组件配置数组未指定class会自动补上核心类的默认实现。controllerMap允许把控制器 ID 映射到任意控制器类从而打破默认命名约定。默认约定下 IDpost对应app\controllers\PostController配置该属性后可按需覆盖例如account映射到UserController、article映射到PostController并关闭 CSRF 校验[ controllerMap [ account app\controllers\UserController, article [ class app\controllers\PostController, enableCsrfValidation false, ], ], ]数组键为控制器 ID值为控制器类名或配置数组。控制台应用也用此机制注册内置命令见下文enableCoreCommands。controllerNamespace指定控制器类所在的默认命名空间默认值为app\controllers。若控制器 ID 为post按约定类名无命名空间为PostController完全限定类名为app\controllers\PostController。控制器类还可放在该命名空间对应目录的子目录中IDadmin/post对应app\controllers\admin\PostController。关键约束控制器类的完全限定名必须能被自动加载且类的真实命名空间必须与该属性一致否则访问应用时会得到 Page Not Found页面未找到错误。如需打破约定请使用controllerMap。language指定应用向最终用户展示内容的语言默认值为en英文应用需要多语言支持时必须配置。该值会影响国际化的多个方面消息翻译、日期格式化、数字格式化等例如yii\jui\DatePicker组件默认依据它决定日历显示语言与日期格式。推荐使用 IETF 语言标签如en表示英文、en-US表示美国英语。补充当前仓库源码 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主要用于显示不要求唯一。如果没有任何代码使用它可以不配置。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, ]源码佐证setTimeZone()只是对 PHP 函数的薄封装framework/base/Application.php。时区设置的更多影响可参考日期格式化章节。version指定应用的版本号默认值为1.0。若代码未使用它则无需配置。有用属性这些属性默认值来自通用约定通常无需修改但需要打破约定时可以配置。charset指定应用使用的字符集默认UTF-8。除非你在维护使用大量非 Unicode 数据的遗留系统否则大多数应用应保持默认。defaultRoute指定请求未提供路由时应用使用的路由。路由可由子模块 ID、控制器 ID 和/或动作 ID 组成如help、post/create、admin/post/create。未给出动作 ID 时采用yii\base\Controller::defaultAction的默认值。对Web 应用默认值为site即使用SiteController及其默认动作。因此无路由访问时显示app\controllers\SiteController::actionIndex()的结果。该默认值在 framework/web/Application.php 中声明。对控制台应用默认值为help即使用内置命令yii\console\controllers\HelpController::actionIndex()。因此直接执行yii不带参数会显示帮助信息。该默认值在 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()会先加载extensions.php为每个扩展注册alias并实例化执行bootstrap项framework/base/Application.php。layout指定渲染视图时使用的默认布局名默认值main即使用布局路径下的main.php。当layoutPath与viewPath均为默认值时默认布局文件对应别名app/views/layouts/main.php。如需默认禁用布局可设为false极少数场景。layoutPath指定布局文件的查找路径默认值为视图目录下的layouts子目录若viewPath为默认值默认布局路径可用别名app/views/layouts表示。可配置为目录或路径别名。源码中默认值由Module::getLayoutPath()计算viewPath . DIRECTORY_SEPARATOR . layouts见 framework/base/Module.php。runtimePath指定临时文件日志文件、缓存文件等的生成目录默认值为app/runtime对应的目录。可配置为目录或路径别名。两个硬性要求目录必须对运行应用的进程可写目录必须对最终用户不可访问因为其中的临时文件可能包含敏感信息。Yii 为此目录预定义了别名runtime。源码中setRuntimePath()在设置路径的同时自动设置runtime别名framework/base/Application.php。viewPath指定视图文件所在的根目录默认值为app/views对应目录可配置为目录或路径别名。源码默认值由Module::getViewPath()计算basePath . DIRECTORY_SEPARATOR . viewsframework/base/Module.php。vendorPath指定由 Composer 管理的第三方库目录包含应用使用的全部第三方库包括 Yii 框架本身默认值为app/vendor对应目录。可配置为目录或路径别名修改后务必同步调整 Composer 配置。Yii 为此目录预定义了别名vendor。源码中setVendorPath()还会一并设置bower与npm别名framework/base/Application.php。enableCoreCommands仅控制台应用仅被控制台应用支持指定是否启用 Yii 自带的核心命令默认值为true。源码在init()中根据该开关把coreCommands()返回的内置命令合并进controllerMap并确保存在help命令framework/console/Application.php。应用事件应用在请求处理的生命周期中会触发若干事件。有两种方式绑定事件处理器方式一在应用配置中用on eventName语法[ on beforeRequest function ($event) { // ... }, ]该语法详见配置格式。方式二在应用实例创建后的引导过程中编程绑定\Yii::$app-on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) { // ... });EVENT_BEFORE_REQUEST在应用开始处理请求之前触发实际事件名为beforeRequest。触发时应用实例已完成配置与初始化是插入自定义代码拦截请求处理流程的合适位置——例如在处理器中根据某些参数动态设置language属性。事件常量定义于 framework/base/Application.php。EVENT_AFTER_REQUEST在应用完成请求处理之后、发送响应之前触发实际事件名为afterRequest。此时请求处理已结束可用于对请求做后处理或定制响应。注意response组件在向用户发送内容时还会触发自己的事件那些事件在本事件之后发生。EVENT_BEFORE_ACTION在执行每个控制器动作之前触发实际事件名为beforeAction。事件参数是yii\base\ActionEvent实例处理器可将其isValid属性设为false来停止动作执行[ on beforeAction function ($event) { if (some condition) { $event-isValid false; } else { } }, ]注意相同的beforeAction事件也会被模块和控制器触发。触发顺序是应用对象最先其次是模块如有最后是控制器。一旦某处理器把isValid置为false后续所有事件都不会再触发。ActionEvent::isValid默认值为true见 framework/base/ActionEvent.php。EVENT_AFTER_ACTION在执行每个控制器动作之后触发实际事件名为afterAction。事件参数同样是yii\base\ActionEvent通过其result属性可以读取或修改动作结果[ on afterAction function ($event) { if (some condition) { // 修改 $event-result } else { } }, ]与beforeAction相反模块和控制器的afterAction事件按逆序触发控制器最先其次是模块如有最后才是应用对象。ActionEvent::result属性在 framework/base/ActionEvent.php 中定义处理器可直接改写。应用生命周期当入口脚本执行以处理请求时应用经历如下生命周期入口脚本把应用配置作为数组加载。入口脚本创建应用新实例调用preInit()配置高优先级属性如basePath注册错误处理器errorHandler配置应用属性调用init()进而调用bootstrap()运行引导组件。入口脚本调用run()运行应用触发EVENT_BEFORE_REQUEST处理请求把请求解析为路由及关联参数按路由创建模块、控制器与动作对象执行控制器动作触发EVENT_AFTER_REQUEST向最终用户发送响应。入口脚本接收应用返回的退出状态码结束请求处理。这一流程在源码Application::run()framework/base/Application.php中有精确对应且与内部状态机state严格同步状态常量值含义STATE_BEGIN0应用刚启动STATE_INIT1应用初始化中STATE_BEFORE_REQUEST2正在触发EVENT_BEFORE_REQUESTSTATE_HANDLING_REQUEST3正在处理请求STATE_AFTER_REQUEST4正在触发EVENT_AFTER_REQUESTSTATE_SENDING_RESPONSE5即将发送响应STATE_END6应用已结束run()依次推进状态并触发事件最后通过$response-send()输出响应并返回exitStatus。end()方法framework/base/Application.php则在提前终止时保证生命周期完整会补发EVENT_AFTER_REQUEST并发送响应在测试环境下则抛出ExitException以便测试框架接管。控制台应用的特殊行为控制台应用yii\console\Application在构造时会多一步loadConfig()若命令行参数中包含--appconfigpath则加载指定文件作为应用配置framework/console/Application.php。其handleRequest()通过$request-resolve()解析出ModuleID/ControllerID/ActionID形式的路由与命名参数如--since0把动作返回值作为退出状态码写入响应。小结应用是 Yii 2 一切请求处理的起点与终点。本文完整覆盖了应用配置的加载机制、两类应用的区别、必填/重要/有用三组属性的语义与源码实现、四个生命周期事件的触发时机与拦截技巧以及从preInit()到run()再到end()的完整状态机。相关源码与测试还可进一步阅读应用基类实现framework/base/Application.phpWeb 应用实现framework/web/Application.php控制台应用实现framework/console/Application.php模块基类路径/视图/布局推导framework/base/Module.php动作事件参数类framework/base/ActionEvent.php单元测试tests/framework/base/ApplicationTest.php、tests/framework/base/ModuleTest.php赞分享后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载相关推荐Yii 2 应用Application完全指南配置、属性、事件与请求生命周期解析Yii 2 应用Application完全指南配置、属性、事件与请求生命周期解析 本指南以 Yii 2 官方指南印尼语版《Aplikasi》 docs/后端Web框架Yii 2 应用Application全面指南配置、属性、事件与生命周期Yii 2 应用Application全面指南配置、属性、事件与生命周期 本指南以 Yii 2 官方文档 structure applications.m后端Web框架Yii 2 应用Application完全指南配置、属性、事件与生命周期解析Yii 2 应用Application完全指南配置、属性、事件与生命周期解析 应用Application对象是 Yii 2 框架中统领整个应用结构M后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考