AboutCommand::add(),无需实现专用命令,就能在 php artisan about 的输出中添加包专用的分区。
官方文档中有注册的基本示例。本页会深入到 Laravel 13 的实现,探讨信息的收集时机、JSON 的类型、分区名称冲突以及测试中的注册状态。
在 Provider 中注册显示内容
下面的示例假设courier.enabled 和 courier.driver 已经作为包的配置完成注册。配置的注册方法请参阅包配置的合并与缓存。
runningInConsole() 是用于避免在 HTTP 请求中进行不必要注册的条件。它并不只在执行 about 时成立,其他 Artisan 命令中也会进行注册。不过,上面闭包内的配置读取在注册时并不会执行。
区分注册时机与求值时机
Laravelv13.35.0 的 add() 不会当场收集数据,而是将注册用的闭包添加到静态的 $customDataResolvers 中。执行 about 时才会组装用于显示的数据,并对已注册的数据获取闭包进行求值。
与其在 add() 外部预先读取配置值并固定到数组中,不如在闭包内获取,这样能够反映命令执行时的状态。另一方面,--only 筛选是在数据获取闭包求值之后进行的。
Acme Courier 的闭包也会被求值。不显示与不处理是两回事。
因此,附加信息应从配置值或轻量的本地状态中获取。如果加入对外部 API 的连通性检查、数据库查询、文件改写等操作,就连查看无关分区的命令也可能变慢或失败。请将连通性检查和修复拆分到专用的 Artisan 命令中。
兼顾 CLI 显示与 JSON 类型
若只想查看包的信息,请指定将分区名称转换为小写 snake case 后的值。对于Acme Courier,即为 acme_courier。
courier.enabled 为 true、courier.driver 为 log 时,JSON 的形式如下。
Enabled 显示为 ENABLED。AboutCommand::format() 是一个可以分别指定 CLI 用的 console 和 JSON 用的 json 的辅助方法。上面的示例只指定了 console,因此 JSON 中返回原始的 boolean 值。无需将 CLI 的显示字符串原样用于 JSON。
像示例那样使用以空格分隔的普通英文单词作为名称,可以让筛选和 JSON 键更容易处理。自动化处理所引用的键可能会随显示名称的变更而改变,因此请在发布时确认兼容性。
为分区使用包专用的名称
add() 会向同一分区追加项目。即使指定了同名分区,也不会替换掉之前注册的全部内容。
请选择像 Acme Courier 这样能与其他包区分开的名称,并仅在必要时才向 Laravel 标准的 Environment、Cache、Drivers、Storage 中添加内容。
如果在同一分区中重复注册同名项目,CLI 中可能会保留为多行,而 JSON 中会合并到同一个键,只保留后注册的值。另外,即使写法不同,也请避免转换为 snake case 后成为相同键的名称。请将注册位置集中到一处,设计成在 CLI 和 JSON 中项目都唯一。
在测试中处理静态注册状态
about 开始执行时,用于显示的 $data 会被初始化,但附加信息的注册列表 $customDataResolvers 会被保留。这样每次都能根据相同的注册重新收集信息,但如果在同一个 PHP 进程中重复执行 Provider 的 boot(),注册可能会不断累积。
AboutCommand::flushState() 是清除所有包的注册以及显示用数据的方法。请不要为了避免自身分区重复而在生产环境的 Provider 中调用它,否则连其他包的诊断信息也会丢失。
如果在自己的测试基础设施中重建应用,请明确由谁负责在测试之间初始化状态。若要初始化,请在启动目标 Provider 之前进行,然后再完成所有必要的注册。另外也请确认现有的测试基础设施是否已经初始化了状态。
发布前的检查项
请在使用 Orchestra Testbench 测试 Laravel 包以及实际使用的应用中确认以下组合。相关页面
Laravel 包开发
确认 Provider 与资源注册的基础知识。
包配置的合并与缓存
确认默认值、用户覆盖与配置缓存之间的关系。