20: Voor AI Agents
Phlo is gebouwd om aangedreven te worden door AI-agenten, niet alleen door hen gelezen te worden. Elke app biedt drie CLI-lagen die een agent in staat stellen om te werken zonder voorafgaande kennis van de codebase: reflect:: om deze te begrijpen, phlo_eval om deze uit te voeren, en build:: om te transpilen en te verifiëren. Alle drie vereisen build: true en mogen nooit tegen productie draaien.
Als je een agent bent die een Phlo-app oppakt, begin hier.
20.1: De triade: begrijpen, uitvoeren, bouwen
Drie lagen, drie vlakken. Bereik ze in deze volgorde.
| Laag | Vlak | Gebruik het om |
|---|---|---|
reflect:: | Statisch | Begrijp de structuur zonder iets uit te voeren: routes, views, de geparsed AST, zoeken, afhankelijkheidsgrafieken. Veilig, alleen-lezen, werkt zelfs wanneer de runtime kapot is. |
phlo_eval | Runtime | Voer een string van Phlo uit tegen de live app: lees records, roep een method aan, render een view, reproduceer een bug. Krachtig en met bijeffecten. |
build:: | Transpile | Bouw .phlo bronnen naar PHP en lint het resultaat voor en na bewerking. |
reflect:: en build:: draaien buiten de app (alleen bron, geen opstart), wat de reden is dat ze snel en zonder bijeffecten zijn. phlo_eval draait binnen de opgestarte app, wat de reden is dat het live data kan aanraken, en waarom het echte risico met zich meebrengt.
20.2: Aanbevolen workflow
- Oriënteer.
reflect::contextvoor een eenmalige snapshot: identiteit, route/view tellingen, geladen pakketten, recente fouten. Vervolgensreflect::compactRoutes. - Verken.
reflect::find <type>,reflect::search <query>,reflect::nodeBody <name>,reflect::fileContent <relPath>. - Voer uit.
phlo_eval '<phlo>'om live data en gedrag te controleren: een telling, een record, de werkelijke output van een methode, een gerenderde view. - Lees. Lees de daadwerkelijke
.phlobron voordat je gaat bewerken. - Bewerk. Alleen
.phlo,data/app.jsonen entrypoints. Nooit de gegenereerde PHP. - Bouw en lint.
build::run, en danbuild::lint(lege array = schoon; zo niet, herstel de bron en herhaal). - Registreer. Werk
data/app.mdbij met structurele wijzigingen, nieuwe routes, opgeloste TODO's en resterend werk.
20.3: reflect:: in de praktijk
php www/app.php reflect::context # orient
php www/app.php reflect::compactRoutes # route map
php www/app.php reflect::search "createRecord" all # find usage
php www/app.php reflect::nodeBody home # one method's body
php www/app.php reflect::objectIndex # resources, methods, props
De uitvoer is JSON. reflect::context leest data/app.md, het door mensen en agents geschreven scratchpad dat je oriënteert op intentie en status. Zie het hoofdstuk Tooling voor de volledige commando-referentie.
20.4: phlo_eval in practice
phlo_eval '<phlo source>' transpiles a string of Phlo statements and runs them in the live app. It is the runtime complement to reflection: where reflect:: reads the static source, phlo_eval executes against real data, resources and views.
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 '<strong>boom</strong>'" # <strong>boom</strong>
A single expression needs no return: it auto-returns like a => arrow body. Reach for return only inside a multiline block, where it is required:
php www/app.php phlo_eval '$pro = array_filter(user::records(), fn($u) => $u->tier === "pro")
return array_values(array_column($pro, "email"))'
Rules:
- Auto-return. A single line auto-returns, exactly like a
=>arrow body, unless it starts withreturn/apply/echo/unset/yield. A multiline block needs its ownreturn. - Output.
return <expr>prints the value as JSON: type-safe, non-scalar-capable, and errors come back as{"error": ...}.echo <expr>prints raw to stdout, for viewing rendered HTML/markup as-is. - Scope.
%resourcerefs resolve as normal. The app is constructed but its app-controller (router/init) is skipped, like any CLI callback; resource controllers do run, so the database and resources are live. - Errors are readable. A failing call returns a structured
{"error": ...}with type, message and source, so you can iterate: one run teaches you thatuser::records()returns objects, the next uses->tierinstead of["tier"].
20.5: Kracht en gevaar
phlo_eval voert willekeurige code uit met volledige app-rechten tegen de live app. In één oproep kan het wachtwoord-hashes, API-sleutels en persoonlijke gegevens lezen, en in een andere kan het gegevens muteren of verwijderen (%db->exec(...)). Er is geen sandbox.
Dat is precies waarom het beperkt is:
- CLI-only. Het weigert te draaien tijdens een HTTP-verzoek, zelfs als het in een route is geïntegreerd. Het kan nooit een netwerk-bereikbare eval-eindpunt worden.
- Build-only. Het bestaat alleen wanneer
build: true. Het wordt nooit ingebouwd in een release of productie-app; het aanroepen daarvan is simpelweg een niet-gedefinieerde functie. - Developer-authored only. Behandel de invoer zoals
eval()zelf: schrijf het zelf, geef nooit onbetrouwbare of door gebruikers aangeleverde invoer door.
Binnen die grenzen is het een nauwkeurig, eerlijk hulpmiddel: het laat je zien wat de app daadwerkelijk doet, niet wat de bron suggereert dat het zou kunnen doen.
20.6: build:: in de praktijk
php www/app.php build::run # transpile changed .phlo to PHP
php www/app.php build::lint # [] means clean; otherwise fix the .phlo source
php www/app.php build::release # build the release when stage/prod output changes
Lint-rapporten geven parse-fouten aan in de getranspileerde PHP. Los altijd de .phlo bron op en bouw opnieuw; patch nooit de gegenereerde PHP. Zie het hoofdstuk Tooling voor de volledige commando-referentie.
20.7: Your app as a tool for agents
Enable the mcp resource and name what an agent may reach:
prop %mcp.models = ['order' => 'Orders of the shop']
POST /mcp then speaks the Model Context Protocol. Each model gets list, get, create, change and delete tools with schemas from its fields, and every call goes through the same rules as a form: the scope, canChange, objRefusal, field rules and hooks. mcp: false on a field keeps it out; a password has that by itself. A client signs in with a bearer token from the [mcp] section of creds, and prop %mcp.canUse takes over for a token per user. With CSRF enabled, add mcp to %CSRF.except.
Laatst bijgewerkt op 04-11-2026