2: 配置

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

2.1: 最小配置

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

2.2: Resources

Commonly used resources:

Resource	Purpose
`security/creds`	Credentials from env and ini files
`security/security`	Security headers
`security/token`	Token generation
`payload`	Read POST, PUT, PATCH and uploads
`session`	Session object
`cookies`	Cookie object
`DOM/form`	Async forms
`DOM/link`	Async link navigation (`<a.async>`)
`phlo.async`	Backendhelper `phlo_async()` voor CLI-calls via de daemonpool of een eenmalig subprocess
`visitors`	Heartbeat/visitor tracking
`useragent`	User-agent parsing
`DB/DB`, `DB/MySQL`, `DB/model`	Database and ORM

Only use resources the app actually needs. The Phlo Control Center can show available resources and dependencies.

Do not confuse the two async layers. SPA navigation and async forms run through the frontend runtime generated in www/app.js, with resources such as DOM/link and DOM/form. The separate phlo.async resource provides the backend function phlo_async() for dispatching a PHP/CLI call outside the current request.

To configure a resource for one app without forking it, inject a value onto its node from app.phlo (prop %AI.model = 'claude-opus-4-8', static %model.DB => %MySQL). See Advanced, "Modifying resources without forking".

2.3: 开发排除

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

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

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

2.4: Release

简写就足够了：

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

Phlo 然后将 release PHP 写入 release/，并将 web 资产写入 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"]）：JS包嵌入phlo.js运行时的命名空间。每个独立加载页面的命名空间都需要运行时，因此在此列出所有命名空间。phloJS: true会反转列表：运行时将进入所有不在phloNS中的命名空间。
iconNS（默认值为"app"）：当使用icons引擎时，接收生成的图标精灵CSS的命名空间。
resourceNS（默认值为{}）：按资源路径（如resources中列出的）键入的每个资源命名空间覆盖，例如{"DOM/markdown": "app", "themes/cobalt": "app"}。它强制该资源的<style>/<script>进入给定的命名空间，覆盖块的ns=。使用它将资源的资产拉入您选择的包中（例如将主题拉入app而不是其自己的theme.*包），而无需编辑资源。

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

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

2.7: 生成的输出

请勿手动编辑这些文件：

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

更改 .phlo 源代码（任何开发请求都会重建它；build::run 从 CLI 也会执行相同操作），使用 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 在调试输出中会对其进行掩码处理。

最近更新于 2026年8月23日