2. 配置 - Phlo

2: 配置

data/app.json 描述了构建：加载了哪些资源，发布输出的位置，以及哪些资源仅属于发布或仅属于开发。

2.1: 最小配置

资源指的是 Phlo 运行时目录。这是框架代码，而不是应用特定文件的地方。您在应用路径中以 .phlo 编写应用代码；只有通用的运行时功能才故意属于目录。

2.2: 资源

常用资源：

资源	目的
`security/creds`	来自 env 和 ini 文件的凭据
`security/security`	安全头
`security/token`	令牌生成
`payload`	读取 POST、PUT、PATCH 和上传
`session`	会话对象
`cookies`	Cookie 对象
`DOM/form`	异步表单
`phlo.async`	异步前端请求
`visitors`	心跳/访客跟踪
`useragent`	用户代理解析
`DB/DB`、`DB/MySQL`、`DB/model`	数据库和 ORM

仅使用应用实际需要的资源。Phlo Control Center 可以显示可用的资源和依赖项。

2.3: 开发排除

在本地开发构建中，您通常希望排除某些跟踪和实时资源：

{
    "exclude": [
        "visitors",
        "useragent",
        "wsCast"
    ]
}

这适用于开发构建。发布构建不会自动使用此排除；因此，访客跟踪仍然可以在此处处于活动状态。

2.4: Release

简短的形式就足够了：

{
    "release": "%app/release/"
}

然后，Phlo 将发布的 PHP 写入 release/，并将网络资产写入 release/www/。

2.5: 路径

%app/ 指的是来自 phlo_app(...) 的应用路径。尽可能将路径配置保留在 www/app.php 和 release/www/app.php 中，以便 data/app.json 保持关于构建行为的信息。

2.6: 命名空间和捆绑包

每个 <style> 和 <script> 块都会编译成每个命名空间的捆绑包。ns=docs 会放在 www/docs.css 和 www/docs.js 中，ns=app,docs 会放在两个捆绑包中，而没有 ns= 的块则在默认命名空间中。页面通过 view(..., ns: 'docs') 选择其捆绑包。

data/app.json 中的三个键控制这一点：

{
    "defaultNS": "app,docs",
    "phloNS": ["app", "docs"],
    "iconNS": "app"
}

defaultNS（默认值为 "app"）：没有显式 ns= 的资源的命名空间（以逗号分隔）。资源资产（如 onExist、cookie墙样式等前端助手）不带 ns=，因此当您的页面使用多个命名空间时，扩大 defaultNS 以便每个捆绑包都能获取它们。
phloNS（默认值为 ["app"]）：嵌入 phlo.js 运行时的 JS 捆绑包的命名空间。每个独立加载页面的命名空间都需要运行时，因此在这里列出它们。phloJS: true 会反转列表：运行时将进入每个不在 phloNS 中的命名空间。
iconNS（默认值为 "app"）：当使用 icons 引擎时，接收生成的图标精灵 CSS 的命名空间。

有两个规则可以保持多命名空间应用程序的健康：

永远不要通过将 defer: '/app.js' 传递给 view() 来解决缺失的运行时。在异步导航中，这会将捆绑包重新注入到已经有一个的页面中，并因重复声明而崩溃。请改为配置 phloNS。
两个运行时绝不能在一个页面中相遇。跨命名空间的链接（一个 app 页面链接到一个 docs 页面）必须是普通链接，以便浏览器进行完整的页面加载。只有同一命名空间内的链接才会获得 class=async 以进行 SPA 导航。

2.7: 生成的输出

请勿手动编辑这些文件：

php/
www/app.js
www/app.css
release/

更改 .phlo 源代码，运行 build::run，使用 build::lint 进行检查，然后使用 build::release 创建一个发布版本。

2.8: 凭证

security/creds 资源解析秘密（API 密钥、数据库登录、Webhook 令牌）并将其暴露为 %creds->...。它从两个来源读取，因此相同的代码可以在笔记本电脑和生产环境中无须编辑地运行。

INI 文件 data/creds.ini 是最简单的来源。请将其排除在版本控制之外。简单的秘密是顶级键；结构化的秘密是带有子键的部分：

OpenAI = sk-...
Claude = sk-ant-...
Grok = xai-...

[mysql]
host = 127.0.0.1
database = app
user = app
password = secret

您可以将它们读取为 %creds->OpenAI（标量）和 %creds->mysql->host（嵌套）。

环境变量提供相同的值而无需文件，这适合 CI 和容器。前缀 PHLO__ 标记凭证，__ 用于分隔嵌套级别：

PHLO__OpenAI=sk-...
PHLO__mysql__host=127.0.0.1

主机作用域形式 PHLO_<HOST>__... 仅适用于匹配的主机。<HOST> 是请求主机的大写形式，所有非字母数字字符都转换为 _，因此 factuur.software 变为 FACTUUR_SOFTWARE：

PHLO_FACTUUR_SOFTWARE__OpenAI=sk-...

来源按顺序合并，每个来源覆盖前一个：首先是 data/creds.ini，然后是 PHLO__ 全局变量，最后是主机作用域的 PHLO_<HOST>__。因此，主机作用域变量优先于全局变量，全局变量优先于 ini 文件。

资源通过 @ requires: creds:<name> 声明其所需内容（例如 creds:OpenAI，creds:mysql）。该行是信息性的：它记录了键，但并不创建它。值被存储为敏感信息，因此 %creds 在调试输出中对其进行掩码处理。