10: 工具和 CLI
Phlo 应用程序具有用于 build、lint、release 和 reflection 的 CLI 层。始终通过应用程序的开发入口点使用它。
10.1: 构建命令
php www/app.php build::run
php www/app.php build::lint
php www/app.php build::release
php www/app.php build::config
php www/app.php build::changedbuild::lint 应该返回一个空数组：
[]如果 lint 报告错误，请修复 .phlo 源文件并重新构建。切勿修补生成的 PHP。
| 命令 | 返回值 |
|---|---|
build::run |
触发构建；返回更改的文件路径 |
build::lint |
转换文件中的 PHP 解析错误；空数组 = 干净 |
build::release |
使用发布钩子转换发布构建 |
build::config |
来自 data/app.json 的完整构建配置 |
build::changed |
自上次构建以来更改的源文件 |
build::buildFiles |
所有转换后的输出路径（php/ + www/） |
build::releaseFiles |
发布构建的转换输出路径 |
build::flush |
删除所有转换后的文件 |
build::traceShadow |
从 functions.php 重新生成 functions.trace.php |
build::help |
所有方法及其签名和描述 |
10.2: 反射命令
反射帮助你在更改应用程序之前理解它：
php www/app.php reflect::context
php www/app.php reflect::compactRoutes
php www/app.php reflect::compactViews
php www/app.php reflect::resourceSummary
php www/app.php reflect::objectIndex
php www/app.php reflect::functionIndex这些命令返回 JSON，并且旨在开发环境中使用 build: true。
相同的自省驱动了 Phlo 控制中心的图形视图：您的应用程序的每个类、资源和依赖边缘，实时呈现自 reflect::graph：
完整参考：
| 命令 | 返回 |
|---|---|
reflect::context |
单次调用快照：身份、路由/视图计数、包、最近错误。最佳首选调用。 |
reflect::appInfo |
data/app.md 的内容，或 null |
reflect::runtime |
运行时常量：主机、路径、功能标志、自定义参数 |
reflect::errors [limit] |
最近的运行时错误（默认 10；0 = 全部） |
reflect::compactRoutes |
带有文件、行、方法、依赖使用的路由图 |
reflect::compactViews |
带有名称、文件、行的视图列表 |
reflect::routes |
所有路由节点的完整细节和注释 |
reflect::views [withBody] |
所有视图节点；传递 true 以获取主体 |
reflect::sourceFiles |
所有 .phlo 源文件路径 |
reflect::sourceNodes [withBody] |
所有源文件的完整解析 AST |
reflect::fileContent <relPath> |
按显示路径获取源文件内容 |
reflect::find <type> [name] [withBody] [scope] |
一种类型的节点；范围 app/resources/all |
reflect::nodeBody <name> [type] |
命名节点的主体（默认类型为 method） |
reflect::search <query> [scope] [maxHits] [contextLines] |
在 .phlo 文件中进行文本搜索 |
reflect::graph |
类型化后端图：节点和语义边 |
reflect::selectorGraph |
类型化前端图：样式/脚本/选择器边 |
reflect::resourceDependencies <name> [transitive] [full] |
从 @ requires 获取的所需资源 |
reflect::fileDependencies |
从 phlo() 和 Class:: 调用生成的每个文件依赖图 |
reflect::functionIndex |
所有函数的签名、源、组、加载状态 |
reflect::objectIndex |
所有资源对象的函数、属性、构造函数、元数据 |
reflect::resourceSummary |
包计数、函数/对象总数、外部要求 |
reflect::resourceFiles |
所有资源文件路径 |
reflect::availableResources |
所有可发现的资源，带有类型、种类、加载状态 |
reflect::editorIndex |
函数、对象、路由、视图的综合索引 |
reflect::findFunction <name> |
按名称查找函数的资源条目，或 null |
reflect::findClass <name> |
按名称或别名查找类的资源条目，或 null |
reflect::help |
所有方法的签名和描述 |
10.3: 通用 CLI 调度
build:: 和 reflect:: 只是一个更通用机制的两个例子。Phlo 的 CLI 可以调用您应用中的 任何 static、method 或 function：
php www/app.php tasks::run # static method on a class
php www/app.php app.heartbeat # method on a Phlo instance
php www/app.php answer "is an eel a fish" # global function三种模式：
| 模式 | 调度 | 示例 |
|---|---|---|
Class::method args |
类上的静态方法 | tasks::run, backup::nightly |
object.method args |
通过 phlo(object) 的实例方法 |
app.heartbeat, cms.reindex |
function args |
全局函数 | answer "question" |
输出以 JSON 格式发送到 stdout，错误以非零退出代码发送到 stderr。这使得您应用中的每个例程都可以直接从 cron、部署脚本、监控或终端中使用，而无需为此构建单独的 CLI 层。
phlo_eval: 在实时应用中运行 Phlo
最强大的函数调度是 phlo_eval，它将一串 Phlo 转换并在实时应用中运行。它是 reflect:: 的运行时补充：反射读取静态源，phlo_eval 则针对真实数据、资源和视图执行。
php www/app.php phlo_eval "user::recordCount()" # 38, no return keyword
php www/app.php phlo_eval "%app->title" # "App"
php www/app.php phlo_eval "echo %app->error('boom')" # raw HTML, not JSON单行自动返回就像 => 箭头主体，因此您只需编写表达式，无需 return（除非它以 return/apply/echo/unset/yield 开头）；只有多行块需要自己的 return。return 将值作为 JSON 打印（类型安全、非标量，错误格式为 {"error": ...}）；echo 原样打印到 stdout，方便查看渲染的标记。
phlo_eval 以完整的应用权限运行任意代码：它可以读取机密并修改数据库。它仅限于 CLI 和构建，永远不会出现在发布/生产环境中。将其输入视为仅由开发者编写，绝不要信任。
仅在 www/app.php 中使用 build: true 可用。请勿在实时生产环境中运行。
10.4: 调试助手
在 phlo_app(...) 中设置 debug: true 时，Phlo 会激活一组用于开发期间检查的助手。在生产环境中，它们是无效的。
| 助手 | 目的 | 行为 |
|---|---|---|
d(...$args) |
将值转储到响应中，继续运行 | 收集在 %res->dump 中；在请求结束时渲染到浏览器控制台。在没有 debug: true 的情况下无效 |
dx(...$args) |
转储 + 停止 | 同步：完整的调试页面，包含源映射的 .phlo 文件和行号。异步/CLI/流：转储通过 apply 负载到达浏览器控制台。安全的 Worker：抛出异常而不是调用 die() |
debug($msg) |
将一行附加到调试日志；不带参数的 debug() 返回所有收集到的内容 |
记录到浏览器控制台，包含请求统计信息 |
error($msg, $code = 500) |
Phlo 异常处理程序的运行时错误 | 抛出 PhloException，记录在 data/errors.json 中 |
trace($node, $args) |
手动跟踪事件（仅在 trace: true 时激活） |
向跟踪日志添加事件，详见 Trace 章节 |
生命周期：助手在请求期间收集（%res->dump，%res->debug）；在同步页面结束时，内联脚本将所有内容记录到浏览器控制台，并附带内存、持续时间和跟踪元数据，异步响应在其 apply 负载中携带相同的数据。对象通过 objInfo() 解包。运行时错误累积在 data/errors.json 中（消息、源映射文件和行号、计数、最后一次发生）；可以通过 reflect::errors 或在 Phlo Control Center 中读取它们。
method buildReport {
$data = $this->load
debug('loaded', count: count($data))
if (!$data) error('No data to report')
dx($data[0])
}dx() 是您在开发过程中主要的“停下来看看有什么”的工具。忘记在发布代码中添加 dx()？在 debug: false 模式下，它的行为就像 error() 一样，不会静默通过。
10.5: 工作流程
在开发环境中，Phlo Control Center（位于 /phlo）将整个循环放入浏览器中：源代码、构建、发布和错误，每个文件只需点击一下即可访问：
- 首先阅读源代码和反射输出。
- 仅修改
.phlo、data/app.json或入口点。 - 运行
build::run。 - 运行
build::lint。 - 测试相关的 HTTP routes。
- 当阶段/发布输出需要更新时，运行
build::release。
10.6: 开发、阶段和生产
开发人员通常具有：
auth: true,
build: true,
debug: true,在 build+debug 模式下，内置控制 UI 默认位于 /phlo；在 phlo_app(...) 中使用 control: 'path' 可以选择不同的路径。阶段/生产通常在没有构建和调试的情况下运行。Web 根目录指向 release/www/。
10.7: HEAD 和 async
当前运行时支持正常的 HTTP 方法，包括 HEAD。异步请求由前端资源处理，并使用与同步请求相同的 routes，除非您明确声明其他 route。