2: Configuratie

data/app.json beschrijft de build: welke resources worden geladen, waar de release-uitvoer naartoe gaat, en welke resources alleen in release of alleen in dev horen.

2.1: Minimale configuratie

Resources verwijzen naar de Phlo runtime catalogus. Dat is frameworkcode, geen plek voor app-specifieke bestanden. Je schrijft appcode als .phlo in het app-pad; alleen generieke runtime-functionaliteit behoort opzettelijk in de catalogus.

2.2: Resources

Commonly used resources:

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: Dev uitsluiten

In een lokale dev-build wil je vaak bepaalde tracking- en realtimebronnen uitsluiten:

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

Dit geldt voor de dev build. De release build gebruikt deze uitsluiting niet automatisch; bezoekerstracking kan daar dus nog steeds actief zijn.

2.4: Release

De korte vorm is voldoende:

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

Phlo schrijft vervolgens release PHP naar release/ en webassets naar release/www/.

2.5: Paden

%app/ verwijst naar het app-pad van phlo_app(...). Houd de padconfiguratie in www/app.php en release/www/app.php zoveel mogelijk hetzelfde, zodat data/app.json betrekking heeft op het buildgedrag.

2.6: Namespaces en bundels

Elke <style> en <script> blok transpileert naar een bundel per namespace. ns=docs komt terecht in www/docs.css en www/docs.js, ns=app,docs in beide bundels, en blokken zonder ns= in de standaard namespace. Een pagina selecteert zijn bundel met view(..., ns: 'docs').

Drie sleutels in data/app.json regelen dit:

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

• defaultNS (standaard "app"): de namespace(s), door komma's gescheiden, voor middelen zonder een expliciete ns=. Resource-assets (frontend helpers zoals onExist, de cookiewall-stijlen) hebben geen ns=, dus wanneer je pagina's meerdere namespaces gebruiken, breid defaultNS uit zodat elke bundel ze krijgt.
• phloNS (standaard ["app"]): de namespaces waarvan de JS-bundel de phlo.js-runtime embed. Elke namespace waarvan de pagina's zelfstandig laden heeft de runtime nodig, dus noem ze hier allemaal. phloJS: true keert de lijst om: de runtime gaat dan naar elke namespace die NIET in phloNS staat.
• iconNS (standaard "app"): de namespace die de gegenereerde icon-sprite CSS ontvangt wanneer de icons engine wordt gebruikt.
• resourceNS (standaard {}): een per-resource namespace override, gekeyed op resourcepad (zoals vermeld in resources), bijv. {"DOM/markdown": "app", "themes/cobalt": "app"}. Het dwingt de <style>/<script> van die resource in de gegeven namespace, waarbij de eigen ns= van het blok wordt overschreven. Gebruik het om de assets van een resource in een bundel van jouw keuze te trekken (bijvoorbeeld een thema in app in plaats van zijn eigen theme.* bundel) zonder de resource te bewerken.

Twee regels houden een multi-namespace app gezond:

1. Werk nooit om een ontbrekende runtime heen door defer: '/app.js' naar view() te sturen. Bij asynchrone navigatie die de bundel opnieuw in een pagina injecteert die er al een heeft en crasht met dubbele declaraties. Configureer in plaats daarvan phloNS.
2. Twee runtimes mogen nooit in één pagina samenkomen. Links die namespaces kruisen (een app pagina die naar een docs pagina linkt) moeten gewone links zijn, zodat de browser een volledige paginalading uitvoert. Alleen links binnen dezelfde namespace krijgen class=async voor SPA-navigatie.

2.7: Gegenereerde output

Bewerk deze bestanden niet met de hand:

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

Wijzig de .phlo bron (elke ontwikkelaarsverzoek bouwt het opnieuw; build::run doet hetzelfde vanuit de CLI), controleer met build::lint, en maak vervolgens een release met build::release.

2.8: Inloggegevens

De security/creds resource lost geheimen (API-sleutels, database-inloggegevens, webhook-tokens) en stelt ze bloot als %creds->.... Het leest uit twee bronnen, zodat dezelfde code op een laptop en in productie zonder aanpassingen draait.

Het INI-bestand data/creds.ini is de eenvoudigste bron. Houd het buiten versiebeheer. Een eenvoudig geheim is een top-level sleutel; een gestructureerd geheim is een sectie met sub-sleutels:

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

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

Je leest ze als %creds->OpenAI (een scalair) en %creds->mysql->host (genest).

Omgevingsvariabelen bieden dezelfde waarden zonder een bestand, wat geschikt is voor CI en containers. De prefix PHLO__ markeert een credential, en __ scheidt geneste niveaus:

PHLO__OpenAI=sk-...
PHLO__mysql__host=127.0.0.1

Een host-gescopeerde vorm, PHLO_<HOST>__..., is alleen van toepassing op een overeenkomende host. <HOST> is de aanvraaghost in hoofdletters waarbij elke niet-alfanumerieke teken is omgezet in _, dus factuur.software wordt FACTUUR_SOFTWARE:

PHLO_FACTUUR_SOFTWARE__OpenAI=sk-...

Bronnen worden in volgorde samengevoegd, waarbij elke de vorige overschrijft: data/creds.ini eerst, dan de PHLO__ globals, en vervolgens de host-scope PHLO_<HOST>__ erbovenop. Dus een host-scope variabele wint van een globale, die weer wint van het ini-bestand.

Een resource verklaart wat het nodig heeft met @ requires: creds:<name> (bijvoorbeeld creds:OpenAI, creds:mysql). Die regel is informatief: het documenteert de sleutel, het creëert deze niet. Waarden worden als gevoelig opgeslagen, dus %creds maskeert ze in debug-uitvoer.

Laatst bijgewerkt op 23-08-2026