后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载Yii 2 在提供完善的 Web 开发能力之外还内置了与 Web 应用同等成熟的控制台Console应用体系用于实现定时任务、后台作业、数据库迁移、缓存清理、资源压缩等维护性工作。本文以 docs/guide-uk/tutorial-console.md 为核心骨架结合框架源码framework/console/目录与主文档 docs/guide/tutorial-console.md系统讲解 Yii 2 控制台应用的结构、入口脚本、配置方式以及如何基于yii\console\Controller编写带选项、参数、退出码与彩色输出的自定义命令。读完本文你将能独立设计并交付一套可投入生产环境、支持自动补全与脚本化调用的 Yii 2 命令行工具。图为 Yii 2 控制台应用不带参数运行./yii时的默认输出列出全部可用内置命令底部提示可通过yii help command-name查看单个命令的详细帮助。控制台应用概述与内置命令Yii 2 控制台应用主要面向需要在网站之外执行的后台与维护任务其结构与 Web 应用高度相似由一个或多个继承自yii\console\Controller的类构成这些类在命令行环境中通常被称为命令Command每个控制器同样可以包含一个或多个动作Action与 Web 控制器一一对应。在官方的基础版basic与高级版advanced项目模板中控制台应用已经随模板内置。只需在应用根目录执行yii脚本无任何参数即可看到所有可用命令的列表如上图所示。这一默认输出由HelpController产生——它在控制台应用中扮演默认路由的角色。从 framework/console/Application.php#L192-L203 的coreCommands()方法可以看到框架开箱即用的核心命令共有 7 个命令 ID控制器类主要用途assetAssetController组合并压缩 JavaScript 与 CSS 资源文件详见资源管理章节cacheCacheController清空应用缓存支持全部缓存、指定缓存组件、数据库表结构缓存等fixtureFixtureController管理测试数据夹具的加载与卸载详见测试夹具章节helpHelpController提供命令帮助信息为默认命令yii help command即由它处理messageMessageController从源码文件中提取待翻译的消息详见国际化I18N章节migrateMigrateController管理数据库迁移创建、执行、回滚等详见数据库迁移章节serveServeController直接启动 PHP 内置 Web 服务器便于本地快速预览其中serve命令在较旧语言版本文档中未列出但自 Yii 2.0.8 起即已加入核心命令集Application.php#L201 中可确认其注册。值得说明的是这些核心命令并非硬编码进框架入口而是通过Application::init()中的controllerMap注入Application.php#L123-L137。因此你可以在console.php配置中用同名 key 覆盖它们实现替换内置命令的效果也可以通过Application::$enableCoreCommands falseApplication.php#L77整体关闭内置命令。命令调用语法执行一个控制台控制器动作的通用语法为yii route [--option1value1 --option2value2 ... argument1 argument2 ...]route指向控制器动作的路由形如controller/action模块中则为module/controller/action--optionNamevalue命名选项运行时会赋值给控制器类对应的公有属性位置参数作为参数按顺序传给动作方法。选项可以出现在任意位置不必集中在参数之前。例如调用MigrateController::actionUp()并设置其属性migrationTable为migrations、限制执行 5 条迁移可写作yii migrate/up 5 --migrationTablemigrations其中5作为第一个位置参数传给actionUp($limit)而--migrationTablemigrations则被解析为控制器属性赋值。shell 通配符提示当在控制台使用*字符时务必用引号包裹为*否则 shell 会将其当作 glob 通配符展开为当前目录下的所有文件名导致参数被意外替换。命令解析的底层原理命令行的解析由yii\console\Request::resolve()完成framework/console/Request.php#L59-L108。其核心规则包括--namevalue形式解析为命名参数并存入$params数组--name不带值默认取布尔true支持--option value的分离写法$prevOption机制会把下一个裸参数当作该选项的值单横线-namevalue形式会被收集到$_aliases中供后续optionAliases()映射纯数字开头的选项名会被判定非法并抛出异常特殊记号--表示之后的所有内容均为位置参数不再按选项解析选项值赋值动作发生在Controller::runAction()framework/console/Controller.php#L121-L189中未知选项会抛出 Unknown option 异常并列出当前动作所有可用选项提示用户。此外从 Yii 2.0.11 起./yii还开箱即用地支持 Bash 与 ZSH 的命令补全脚本位于仓库的 contrib/completion/bash/yii 与 contrib/completion/zsh/_yii。Bash 下可将脚本放入/etc/bash_completion.d/后重启终端或source ~/.bashrcZSH 下则需将_yii放入~/.zsh/completion/并在~/.zshrc中加入fpath(~/.zsh/completion $fpath)与autoload -Uz compinit compinit -i最后exec $SHELL -l重载 shell。入口脚本Entry Script控制台应用的入口脚本等价于 Web 应用的index.php引导文件。它通常命名为yii位于应用根目录内容如下仓库中framework/yii即为官方模板同款脚本可对照 framework/yii 查看#!/usr/bin/env php ?php /** * Yii console bootstrap file. */ defined(YII_DEBUG) or define(YII_DEBUG, true); defined(YII_ENV) or define(YII_ENV, dev); require __DIR__ . /vendor/autoload.php; require __DIR__ . /vendor/yiisoft/yii2/Yii.php; $config require __DIR__ . /config/console.php; $application new yii\console\Application($config); $exitCode $application-run(); exit($exitCode);该脚本是应用自身的一部分可自由按需修改YII_DEBUG设为false可关闭错误堆栈追踪并提升整体性能设为true则提供更友好的开发调试体验。基础版与高级版模板默认均开启调试模式YII_ENV指定运行环境dev/prod/test影响日志、错误处理等组件的默认行为注意脚本最后将$application-run()的返回值直接exit()这意味着动作返回的整数就是进程退出码——这正是退出码机制得以在 shell 脚本、CI 流水线中被可靠使用的关键链路详见下文退出码一节。配置控制台应用与 Web 应用类似控制台应用使用独立的配置文件默认名为console.php位于config/目录。在该文件中可以配置各种应用组件数据库、缓存、日志、邮件等以及控制台应用特有的属性。Application类中几个常用配置属性包括defaultRoute默认路由默认为helpApplication.php#L72所以无参数运行yii即展示帮助列表enableCoreCommands是否启用框架核心命令默认truecontrollerNamespace自定义命令控制器的命名空间模板中通常为app\commands。共享配置技巧如果 Web 应用与控制台应用存在大量取值相同的公共配置建议把公共部分抽离成独立文件再在config/web.php与config/console.php中分别require引入。高级版项目模板即采用这种公共配置合并的组织方式。动态切换配置appconfig选项有时你希望以非入口脚本所加载的配置来执行命令。典型场景是用yii migrate更新各测试套件独立配置的测试数据库。此时只需在执行命令时通过appconfig选项指定目标配置文件即可yii route --appconfigpath/to/config.php ...其底层实现位于 Application::loadConfig()Application构造时会扫描$_SERVER[argv]一旦发现--appconfig前缀参数便将该路径支持 Yii 别名对应的 PHP 数组作为应用配置整体加载若文件不存在会直接输出 The configuration file does not exist 并以非零码退出。创建自定义控制台命令控制器与动作一个控制台命令就是一个继承自yii\console\Controller的控制器类类中定义一个或多个actionXxx()动作方法每个动作对应一个子命令。执行命令时需给出指向该动作的路由。例如路由migrate/create对应调用MigrateController::actionCreate()若路由中未包含动作 ID则执行默认动作与 Web 控制器行为一致默认动作可通过$defaultAction属性指定基类默认为index。以基础版模板为例自定义命令类放在commands/目录下、命名空间为app\commands。一个最小可运行的控制台控制器?php namespace app\commands; use yii\console\Controller; /** * 演示用的示例命令。 */ class HelloController extends Controller { public function actionIndex() { echo Hello, console world!\n; } }保存后执行./yii hello/index或简写./yii hello命中默认动作即可看到输出。选项Options通过重写options($actionID)方法可以声明当前命令controller/actionID可用的选项集合。该方法应返回控制器类的公有属性名列表。执行命令时用--optionNameoptionValue语法给属性赋值。关于选项框架源码Controller.php#L148-L181提供了几个值得注意的实现细节类型自动转换若属性已有默认值则传入值会按settype()转换为与该默认值相同的 PHP 类型例如默认值为int的$limit传入5会被转为整数 5数组选项若选项默认值为数组运行期赋给的字符串会按逗号拆分成数组正则/\s*,\s*(?![^()]*\))/会在拆分时跳过括号内的逗号kebab-case 兼容从 Yii 2.0.14 起camelCase属性名对应的选项也可用--kebab-case形式输入解析时会自动用Inflector::id2camel()还原未知选项报错任何未在options()中声明的--xxx都会抛出 Unknown option 异常并提示可用选项帮助开发者快速定位拼写错误基类默认声明了 4 个通用选项Controller.php#L453-L457color是否启用 ANSI 颜色、interactive是否交互式运行、help显示帮助、silentExitOnException异常时是否以ExitCode::OK静默退出。基类属性interactive true意味着默认会向用户发起确认式提问在脚本/CI 中可通过--interactive0关闭此时confirm()直接返回true、prompt()返回默认值见 Controller.php#L384-L418避免自动化流程被卡在交互提示上。选项别名Option Aliases自 Yii 2.0.8 起控制台命令支持通过optionAliases()方法为长选项定义短别名。重写该方法返回[别名 选项名]映射即可namespace app\commands; use yii\console\Controller; class HelloController extends Controller { public $message; public function options($actionID) { return [message]; } public function optionAliases() { return [m message]; } public function actionIndex() { echo $this-message . \n; } }现在即可用短别名执行./yii hello -mhola基类默认提供h help别名Controller.php#L469-L474所以yii help migrate与yii -h migrate等价。别名解析发生在 Controller::runAction()-xxx形式的参数由Request::resolve()先归入$_aliases再按映射写入对应属性未注册的别名会抛出 Unknown alias 异常并列出所有可用别名。参数Arguments除选项外命令还可以接收位置参数它们按顺序映射到动作方法的形参第一个参数对应第一个形参第二个对应第二个以此类推。若调用时提供的参数不足则使用形参的默认值如果声明了若既无默认值、运行期也未提供命令会抛出 Missing required arguments 异常并以错误状态退出Controller.php#L266-L268。使用array类型提示可以声明数组参数运行时传入的字符串会按逗号拆分为数组Controller.php#L242-L244空字符串则得到空数组。class ExampleController extends \yii\console\Controller { // 命令 yii example/create test 将调用 actionCreate(test) public function actionCreate($name) { ... } // 命令 yii example/index city 将调用 actionIndex(city, name) // 命令 yii example/index city id 将调用 actionIndex(city, id) public function actionIndex($category, $order name) { ... } // 命令 yii example/add test 将调用 actionAdd([test]) // 命令 yii example/add test1,test2 将调用 actionAdd([test1, test2]) public function actionAdd(array $name) { ... } }除array类型外bindActionParams()Controller.php#L204-L276还支持依赖注入如果形参声明为某个类类型且未在命令行提供对应值则自动从容器中解析该对象注入非内置类型分支这使得命令动作可以直接注入服务、组件等对象代码更简洁、更易测试。变长参数variadic也得到支持可收集任意数量的位置参数。退出码Exit Code退出码是控制台应用开发的最佳实践约定返回0表示成功返回大于0的整数表示出错该数值即错误码可用于脚本与外部程序定位错误细节。例如1通常代表未指定的通用错误更高的数值可约定为输入错误、文件缺失等特定错误类型。只需让动作方法返回一个整数框架便会将其作为进程退出码传递入口脚本中exit($exitCode)完成收尾。示例public function actionIndex() { if (/* 某种问题 */) { echo A problem occurred!\n; return 1; } // 正常执行…… return 0; }框架提供了两套预定义常量方便使用旧式自 2.0.13 起标记为deprecated见 Controller.php#L50-L57Controller::EXIT_CODE_NORMAL值为 0、Controller::EXIT_CODE_ERROR值为 1推荐方式使用 yii\console\ExitCode 类。它自 2.0.13 引入常量定义遵循 FreeBSD sysexits(3) 规范部分常用值如下use yii\console\ExitCode; public function actionIndex() { if (/* 某种问题 */) { echo A problem occurred!\n; return ExitCode::UNSPECIFIED_ERROR; } // 正常执行…… return ExitCode::OK; }常量值含义ExitCode::OK0命令成功完成ExitCode::UNSPECIFIED_ERROR1未指明具体原因的错误ExitCode::USAGE64命令用法不正确参数数量、选项语法等ExitCode::DATAERR65输入数据错误ExitCode::NOINPUT66输入文件不存在或不可读ExitCode::NOUSER67用户不存在ExitCode::UNAVAILABLE69所需服务不可用ExitCode::SOFTWARE70内部软件错误ExitCode::OSERR71系统调用或系统服务出错ExitCode::OSFILE72系统文件访问错误ExitCode::CANTCREAT73无法创建输出文件ExitCode::IOERR74I/O 错误ExitCode::TEMPFAIL75临时性失败可稍后重试ExitCode::PROTOCOL76远端服务返回异常协议行为ExitCode::NOPERM77权限不足ExitCode::CONFIG78配置缺失或配置错误对于需要区分更多错误类型的场景建议在控制器中为错误码定义语义化常量提高可读性与可维护性。ExitCode::getReason($code)ExitCode.php#L156-L159还可将错误码转换为人类可读的简短说明文本。格式化输出与颜色Yii 控制台支持 ANSI 格式化输出并且在终端不支持时自动降级为普通纯文本因此可以放心在脚本与管道环境中使用。颜色开关受--color选项与isColorEnabled()控制Controller.php#L106-L109只有显式设为true或未设置且终端确实支持 ANSI 时才会着色。输出加粗文本$this-stdout(Hello?\n, Console::BOLD);若需要动态拼接多种样式推荐用ansiFormat()$name $this-ansiFormat(Alex, Console::FG_YELLOW); echo Hello, my name is $name.;stdout()/stderr()/ansiFormat()均定义于 framework/console/Controller.php可使用的样式常量来自 yii\helpers\Console如FG_YELLOW前景色、BOLD加粗、UNDERLINE下划线等可组合传入多个常量。交互式输入与表格输出控制台控制器还内置了三组交互辅助方法均尊重interactive选项非交互模式下自动使用默认值prompt($text, $options)提示用户输入支持required、default、pattern、validator等校验选项confirm($message, $default false)让用户输入 y/n 确认select($prompt, $options, $default null)让用户在多个候选中选择。自 Yii 2.0.13 起还可使用 yii\console\widgets\Table 组件在终端渲染表格use yii\console\widgets\Table; echo Table::widget([ headers [Project, Status, Participant], rows [ [Yii, OK, samdark], [Yii, OK, cebe], ], ]);Table 组件同样支持setHeaders()/setRows()链式写法见 Table.php#L16-L43并内置DEFAULT_CONSOLE_SCREEN_WIDTH120 字符等布局常量可自动适配屏幕宽度换行。帮助信息与文档注释控制台命令的帮助信息并非手写清单而是自动从 PHPDoc 注释解析而来getHelpSummary()Controller.php#L527-L530取类的第一行文档注释作为一行摘要getHelp()Controller.php#L539-L542取完整描述并支持 Markdown 渲染Console::markdownToAnsi()getActionArgsHelp()与getActionOptionsHelp()则通过反射解析动作方法形参param标签与选项属性var标签生成参数/选项的类型、默认值、说明列表。因此为命令类与动作方法写好 PHPDoc等于免费获得一份结构化的yii help command输出这也是 Yii 官方内置命令帮助信息的生成方式。实战小结综合以上内容一个生产级 Yii 2 控制台命令的编写要点可归纳为在app\commands命名空间下继承yii\console\Controller用actionXxx()定义子命令用公有属性 options()声明选项用optionAliases()提供短别名用动作方法形参接收位置参数需要时可加array或类类型提示通过ExitCode常量返回语义明确的退出码配合stdout()/stderr()/ ANSI 样式输出友好信息必要时用prompt()/confirm()/select()实现交互用Table::widget()输出表格写好 PHPDoc让help命令自动呈现完整用法在config/console.php中配置命令需要的应用组件并通过共享配置 --appconfig实现多环境复用。更进一步可参考框架内置命令的实现framework/console/controllers/与对应测试用例tests/framework/console/以及官方文档中的控制台命令教程、数据库迁移、国际化消息提取与资源压缩命令等章节将控制台能力与业务实践深度结合。赞分享后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载相关推荐Yii 2 控制台应用完全指南从内置命令到自定义 Command 开发实战Yii 2 控制台应用完全指南从内置命令到自定义 Command 开发实战 在 Yii 2 中除了构建 Web 应用的丰富特性外框架还提供了功能完备的控制后端Web框架Yii 2 控制台应用Console Application完全指南命令用法、配置与自定义命令开发Yii 2 控制台应用Console Application完全指南命令用法、配置与自定义命令开发 本篇技术指南以 Yii 2 框架的 控制台应用官方教程后端Web框架Yii 2 控制台应用完全指南命令、入口脚本、配置与自定义命令开发Yii 2 控制台应用完全指南命令、入口脚本、配置与自定义命令开发 Yii 2 除了为构建 Web 应用提供丰富特性之外还内置了完整的控制台命令行应用支后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Yii 2 控制台应用实战指南：从内置命令到自定义 Command 的完整开发手册
后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载Yii 2 在提供完善的 Web 开发能力之外还内置了与 Web 应用同等成熟的控制台Console应用体系用于实现定时任务、后台作业、数据库迁移、缓存清理、资源压缩等维护性工作。本文以 docs/guide-uk/tutorial-console.md 为核心骨架结合框架源码framework/console/目录与主文档 docs/guide/tutorial-console.md系统讲解 Yii 2 控制台应用的结构、入口脚本、配置方式以及如何基于yii\console\Controller编写带选项、参数、退出码与彩色输出的自定义命令。读完本文你将能独立设计并交付一套可投入生产环境、支持自动补全与脚本化调用的 Yii 2 命令行工具。图为 Yii 2 控制台应用不带参数运行./yii时的默认输出列出全部可用内置命令底部提示可通过yii help command-name查看单个命令的详细帮助。控制台应用概述与内置命令Yii 2 控制台应用主要面向需要在网站之外执行的后台与维护任务其结构与 Web 应用高度相似由一个或多个继承自yii\console\Controller的类构成这些类在命令行环境中通常被称为命令Command每个控制器同样可以包含一个或多个动作Action与 Web 控制器一一对应。在官方的基础版basic与高级版advanced项目模板中控制台应用已经随模板内置。只需在应用根目录执行yii脚本无任何参数即可看到所有可用命令的列表如上图所示。这一默认输出由HelpController产生——它在控制台应用中扮演默认路由的角色。从 framework/console/Application.php#L192-L203 的coreCommands()方法可以看到框架开箱即用的核心命令共有 7 个命令 ID控制器类主要用途assetAssetController组合并压缩 JavaScript 与 CSS 资源文件详见资源管理章节cacheCacheController清空应用缓存支持全部缓存、指定缓存组件、数据库表结构缓存等fixtureFixtureController管理测试数据夹具的加载与卸载详见测试夹具章节helpHelpController提供命令帮助信息为默认命令yii help command即由它处理messageMessageController从源码文件中提取待翻译的消息详见国际化I18N章节migrateMigrateController管理数据库迁移创建、执行、回滚等详见数据库迁移章节serveServeController直接启动 PHP 内置 Web 服务器便于本地快速预览其中serve命令在较旧语言版本文档中未列出但自 Yii 2.0.8 起即已加入核心命令集Application.php#L201 中可确认其注册。值得说明的是这些核心命令并非硬编码进框架入口而是通过Application::init()中的controllerMap注入Application.php#L123-L137。因此你可以在console.php配置中用同名 key 覆盖它们实现替换内置命令的效果也可以通过Application::$enableCoreCommands falseApplication.php#L77整体关闭内置命令。命令调用语法执行一个控制台控制器动作的通用语法为yii route [--option1value1 --option2value2 ... argument1 argument2 ...]route指向控制器动作的路由形如controller/action模块中则为module/controller/action--optionNamevalue命名选项运行时会赋值给控制器类对应的公有属性位置参数作为参数按顺序传给动作方法。选项可以出现在任意位置不必集中在参数之前。例如调用MigrateController::actionUp()并设置其属性migrationTable为migrations、限制执行 5 条迁移可写作yii migrate/up 5 --migrationTablemigrations其中5作为第一个位置参数传给actionUp($limit)而--migrationTablemigrations则被解析为控制器属性赋值。shell 通配符提示当在控制台使用*字符时务必用引号包裹为*否则 shell 会将其当作 glob 通配符展开为当前目录下的所有文件名导致参数被意外替换。命令解析的底层原理命令行的解析由yii\console\Request::resolve()完成framework/console/Request.php#L59-L108。其核心规则包括--namevalue形式解析为命名参数并存入$params数组--name不带值默认取布尔true支持--option value的分离写法$prevOption机制会把下一个裸参数当作该选项的值单横线-namevalue形式会被收集到$_aliases中供后续optionAliases()映射纯数字开头的选项名会被判定非法并抛出异常特殊记号--表示之后的所有内容均为位置参数不再按选项解析选项值赋值动作发生在Controller::runAction()framework/console/Controller.php#L121-L189中未知选项会抛出 Unknown option 异常并列出当前动作所有可用选项提示用户。此外从 Yii 2.0.11 起./yii还开箱即用地支持 Bash 与 ZSH 的命令补全脚本位于仓库的 contrib/completion/bash/yii 与 contrib/completion/zsh/_yii。Bash 下可将脚本放入/etc/bash_completion.d/后重启终端或source ~/.bashrcZSH 下则需将_yii放入~/.zsh/completion/并在~/.zshrc中加入fpath(~/.zsh/completion $fpath)与autoload -Uz compinit compinit -i最后exec $SHELL -l重载 shell。入口脚本Entry Script控制台应用的入口脚本等价于 Web 应用的index.php引导文件。它通常命名为yii位于应用根目录内容如下仓库中framework/yii即为官方模板同款脚本可对照 framework/yii 查看#!/usr/bin/env php ?php /** * Yii console bootstrap file. */ defined(YII_DEBUG) or define(YII_DEBUG, true); defined(YII_ENV) or define(YII_ENV, dev); require __DIR__ . /vendor/autoload.php; require __DIR__ . /vendor/yiisoft/yii2/Yii.php; $config require __DIR__ . /config/console.php; $application new yii\console\Application($config); $exitCode $application-run(); exit($exitCode);该脚本是应用自身的一部分可自由按需修改YII_DEBUG设为false可关闭错误堆栈追踪并提升整体性能设为true则提供更友好的开发调试体验。基础版与高级版模板默认均开启调试模式YII_ENV指定运行环境dev/prod/test影响日志、错误处理等组件的默认行为注意脚本最后将$application-run()的返回值直接exit()这意味着动作返回的整数就是进程退出码——这正是退出码机制得以在 shell 脚本、CI 流水线中被可靠使用的关键链路详见下文退出码一节。配置控制台应用与 Web 应用类似控制台应用使用独立的配置文件默认名为console.php位于config/目录。在该文件中可以配置各种应用组件数据库、缓存、日志、邮件等以及控制台应用特有的属性。Application类中几个常用配置属性包括defaultRoute默认路由默认为helpApplication.php#L72所以无参数运行yii即展示帮助列表enableCoreCommands是否启用框架核心命令默认truecontrollerNamespace自定义命令控制器的命名空间模板中通常为app\commands。共享配置技巧如果 Web 应用与控制台应用存在大量取值相同的公共配置建议把公共部分抽离成独立文件再在config/web.php与config/console.php中分别require引入。高级版项目模板即采用这种公共配置合并的组织方式。动态切换配置appconfig选项有时你希望以非入口脚本所加载的配置来执行命令。典型场景是用yii migrate更新各测试套件独立配置的测试数据库。此时只需在执行命令时通过appconfig选项指定目标配置文件即可yii route --appconfigpath/to/config.php ...其底层实现位于 Application::loadConfig()Application构造时会扫描$_SERVER[argv]一旦发现--appconfig前缀参数便将该路径支持 Yii 别名对应的 PHP 数组作为应用配置整体加载若文件不存在会直接输出 The configuration file does not exist 并以非零码退出。创建自定义控制台命令控制器与动作一个控制台命令就是一个继承自yii\console\Controller的控制器类类中定义一个或多个actionXxx()动作方法每个动作对应一个子命令。执行命令时需给出指向该动作的路由。例如路由migrate/create对应调用MigrateController::actionCreate()若路由中未包含动作 ID则执行默认动作与 Web 控制器行为一致默认动作可通过$defaultAction属性指定基类默认为index。以基础版模板为例自定义命令类放在commands/目录下、命名空间为app\commands。一个最小可运行的控制台控制器?php namespace app\commands; use yii\console\Controller; /** * 演示用的示例命令。 */ class HelloController extends Controller { public function actionIndex() { echo Hello, console world!\n; } }保存后执行./yii hello/index或简写./yii hello命中默认动作即可看到输出。选项Options通过重写options($actionID)方法可以声明当前命令controller/actionID可用的选项集合。该方法应返回控制器类的公有属性名列表。执行命令时用--optionNameoptionValue语法给属性赋值。关于选项框架源码Controller.php#L148-L181提供了几个值得注意的实现细节类型自动转换若属性已有默认值则传入值会按settype()转换为与该默认值相同的 PHP 类型例如默认值为int的$limit传入5会被转为整数 5数组选项若选项默认值为数组运行期赋给的字符串会按逗号拆分成数组正则/\s*,\s*(?![^()]*\))/会在拆分时跳过括号内的逗号kebab-case 兼容从 Yii 2.0.14 起camelCase属性名对应的选项也可用--kebab-case形式输入解析时会自动用Inflector::id2camel()还原未知选项报错任何未在options()中声明的--xxx都会抛出 Unknown option 异常并提示可用选项帮助开发者快速定位拼写错误基类默认声明了 4 个通用选项Controller.php#L453-L457color是否启用 ANSI 颜色、interactive是否交互式运行、help显示帮助、silentExitOnException异常时是否以ExitCode::OK静默退出。基类属性interactive true意味着默认会向用户发起确认式提问在脚本/CI 中可通过--interactive0关闭此时confirm()直接返回true、prompt()返回默认值见 Controller.php#L384-L418避免自动化流程被卡在交互提示上。选项别名Option Aliases自 Yii 2.0.8 起控制台命令支持通过optionAliases()方法为长选项定义短别名。重写该方法返回[别名 选项名]映射即可namespace app\commands; use yii\console\Controller; class HelloController extends Controller { public $message; public function options($actionID) { return [message]; } public function optionAliases() { return [m message]; } public function actionIndex() { echo $this-message . \n; } }现在即可用短别名执行./yii hello -mhola基类默认提供h help别名Controller.php#L469-L474所以yii help migrate与yii -h migrate等价。别名解析发生在 Controller::runAction()-xxx形式的参数由Request::resolve()先归入$_aliases再按映射写入对应属性未注册的别名会抛出 Unknown alias 异常并列出所有可用别名。参数Arguments除选项外命令还可以接收位置参数它们按顺序映射到动作方法的形参第一个参数对应第一个形参第二个对应第二个以此类推。若调用时提供的参数不足则使用形参的默认值如果声明了若既无默认值、运行期也未提供命令会抛出 Missing required arguments 异常并以错误状态退出Controller.php#L266-L268。使用array类型提示可以声明数组参数运行时传入的字符串会按逗号拆分为数组Controller.php#L242-L244空字符串则得到空数组。class ExampleController extends \yii\console\Controller { // 命令 yii example/create test 将调用 actionCreate(test) public function actionCreate($name) { ... } // 命令 yii example/index city 将调用 actionIndex(city, name) // 命令 yii example/index city id 将调用 actionIndex(city, id) public function actionIndex($category, $order name) { ... } // 命令 yii example/add test 将调用 actionAdd([test]) // 命令 yii example/add test1,test2 将调用 actionAdd([test1, test2]) public function actionAdd(array $name) { ... } }除array类型外bindActionParams()Controller.php#L204-L276还支持依赖注入如果形参声明为某个类类型且未在命令行提供对应值则自动从容器中解析该对象注入非内置类型分支这使得命令动作可以直接注入服务、组件等对象代码更简洁、更易测试。变长参数variadic也得到支持可收集任意数量的位置参数。退出码Exit Code退出码是控制台应用开发的最佳实践约定返回0表示成功返回大于0的整数表示出错该数值即错误码可用于脚本与外部程序定位错误细节。例如1通常代表未指定的通用错误更高的数值可约定为输入错误、文件缺失等特定错误类型。只需让动作方法返回一个整数框架便会将其作为进程退出码传递入口脚本中exit($exitCode)完成收尾。示例public function actionIndex() { if (/* 某种问题 */) { echo A problem occurred!\n; return 1; } // 正常执行…… return 0; }框架提供了两套预定义常量方便使用旧式自 2.0.13 起标记为deprecated见 Controller.php#L50-L57Controller::EXIT_CODE_NORMAL值为 0、Controller::EXIT_CODE_ERROR值为 1推荐方式使用 yii\console\ExitCode 类。它自 2.0.13 引入常量定义遵循 FreeBSD sysexits(3) 规范部分常用值如下use yii\console\ExitCode; public function actionIndex() { if (/* 某种问题 */) { echo A problem occurred!\n; return ExitCode::UNSPECIFIED_ERROR; } // 正常执行…… return ExitCode::OK; }常量值含义ExitCode::OK0命令成功完成ExitCode::UNSPECIFIED_ERROR1未指明具体原因的错误ExitCode::USAGE64命令用法不正确参数数量、选项语法等ExitCode::DATAERR65输入数据错误ExitCode::NOINPUT66输入文件不存在或不可读ExitCode::NOUSER67用户不存在ExitCode::UNAVAILABLE69所需服务不可用ExitCode::SOFTWARE70内部软件错误ExitCode::OSERR71系统调用或系统服务出错ExitCode::OSFILE72系统文件访问错误ExitCode::CANTCREAT73无法创建输出文件ExitCode::IOERR74I/O 错误ExitCode::TEMPFAIL75临时性失败可稍后重试ExitCode::PROTOCOL76远端服务返回异常协议行为ExitCode::NOPERM77权限不足ExitCode::CONFIG78配置缺失或配置错误对于需要区分更多错误类型的场景建议在控制器中为错误码定义语义化常量提高可读性与可维护性。ExitCode::getReason($code)ExitCode.php#L156-L159还可将错误码转换为人类可读的简短说明文本。格式化输出与颜色Yii 控制台支持 ANSI 格式化输出并且在终端不支持时自动降级为普通纯文本因此可以放心在脚本与管道环境中使用。颜色开关受--color选项与isColorEnabled()控制Controller.php#L106-L109只有显式设为true或未设置且终端确实支持 ANSI 时才会着色。输出加粗文本$this-stdout(Hello?\n, Console::BOLD);若需要动态拼接多种样式推荐用ansiFormat()$name $this-ansiFormat(Alex, Console::FG_YELLOW); echo Hello, my name is $name.;stdout()/stderr()/ansiFormat()均定义于 framework/console/Controller.php可使用的样式常量来自 yii\helpers\Console如FG_YELLOW前景色、BOLD加粗、UNDERLINE下划线等可组合传入多个常量。交互式输入与表格输出控制台控制器还内置了三组交互辅助方法均尊重interactive选项非交互模式下自动使用默认值prompt($text, $options)提示用户输入支持required、default、pattern、validator等校验选项confirm($message, $default false)让用户输入 y/n 确认select($prompt, $options, $default null)让用户在多个候选中选择。自 Yii 2.0.13 起还可使用 yii\console\widgets\Table 组件在终端渲染表格use yii\console\widgets\Table; echo Table::widget([ headers [Project, Status, Participant], rows [ [Yii, OK, samdark], [Yii, OK, cebe], ], ]);Table 组件同样支持setHeaders()/setRows()链式写法见 Table.php#L16-L43并内置DEFAULT_CONSOLE_SCREEN_WIDTH120 字符等布局常量可自动适配屏幕宽度换行。帮助信息与文档注释控制台命令的帮助信息并非手写清单而是自动从 PHPDoc 注释解析而来getHelpSummary()Controller.php#L527-L530取类的第一行文档注释作为一行摘要getHelp()Controller.php#L539-L542取完整描述并支持 Markdown 渲染Console::markdownToAnsi()getActionArgsHelp()与getActionOptionsHelp()则通过反射解析动作方法形参param标签与选项属性var标签生成参数/选项的类型、默认值、说明列表。因此为命令类与动作方法写好 PHPDoc等于免费获得一份结构化的yii help command输出这也是 Yii 官方内置命令帮助信息的生成方式。实战小结综合以上内容一个生产级 Yii 2 控制台命令的编写要点可归纳为在app\commands命名空间下继承yii\console\Controller用actionXxx()定义子命令用公有属性 options()声明选项用optionAliases()提供短别名用动作方法形参接收位置参数需要时可加array或类类型提示通过ExitCode常量返回语义明确的退出码配合stdout()/stderr()/ ANSI 样式输出友好信息必要时用prompt()/confirm()/select()实现交互用Table::widget()输出表格写好 PHPDoc让help命令自动呈现完整用法在config/console.php中配置命令需要的应用组件并通过共享配置 --appconfig实现多环境复用。更进一步可参考框架内置命令的实现framework/console/controllers/与对应测试用例tests/framework/console/以及官方文档中的控制台命令教程、数据库迁移、国际化消息提取与资源压缩命令等章节将控制台能力与业务实践深度结合。赞分享后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载相关推荐Yii 2 控制台应用完全指南从内置命令到自定义 Command 开发实战Yii 2 控制台应用完全指南从内置命令到自定义 Command 开发实战 在 Yii 2 中除了构建 Web 应用的丰富特性外框架还提供了功能完备的控制后端Web框架Yii 2 控制台应用Console Application完全指南命令用法、配置与自定义命令开发Yii 2 控制台应用Console Application完全指南命令用法、配置与自定义命令开发 本篇技术指南以 Yii 2 框架的 控制台应用官方教程后端Web框架Yii 2 控制台应用完全指南命令、入口脚本、配置与自定义命令开发Yii 2 控制台应用完全指南命令、入口脚本、配置与自定义命令开发 Yii 2 除了为构建 Web 应用提供丰富特性之外还内置了完整的控制台命令行应用支后端Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考