10. Gereedschap & CLI

10: Gereedschap & CLI

Phlo-apps hebben een CLI-laag voor build, lint, release en reflection. Gebruik het altijd via de dev entrypoint van de app.

10.1: Bouwopdrachten

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::changed

build::lint zou een lege array moeten retourneren:

[]

Als lint fouten rapporteert, corrigeer dan de .phlo bron en bouw opnieuw. Patch nooit de gegenereerde PHP.

Commando	Retourneert
`build::run`	Triggers een build; retourneert gewijzigde bestands paden
`build::lint`	PHP parse fouten in getranspileerde bestanden; lege array = schoon
`build::release`	Transpiles een release build met release hooks
`build::config`	Volledige buildconfiguratie van `data/app.json`
`build::changed`	Bronnen bestanden die zijn gewijzigd sinds de laatste build
`build::buildFiles`	Alle getranspileerde uitvoer paden (`php/` + `www/`)
`build::releaseFiles`	Getranspileerde uitvoer paden voor de release build
`build::flush`	Verwijdert alle getranspileerde bestanden
`build::traceShadow`	Regenerates `functions.trace.php` van `functions.php`
`build::help`	Alle methoden met handtekeningen en beschrijvingen

10.2: Reflect commando's

Reflectie helpt je een app te begrijpen voordat je deze wijzigt:

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

Deze commando's retourneren JSON en zijn bedoeld voor ontwikkelomgevingen met build: true.

Dezelfde introspectie stuurt de Graph view van het Phlo Control Center: elke klasse, resource en afhankelijkheidsrand van je app, live weergegeven vanuit reflect::graph:

De Control Center Graph view: de klassen, resources en afhankelijkheidsranden van je app, live weergegeven vanuit reflect::graph

Volledige referentie:

Commando	Retourneert
`reflect::context`	Snapshot van een enkele oproep: identiteit, route/view tellingen, pakketten, recente fouten. Beste eerste oproep.
`reflect::appInfo`	Inhoud van `data/app.md`, of null
`reflect::runtime`	Runtime constanten: host, paden, functie-vlaggen, aangepaste parameters
`reflect::errors [limit]`	Recente runtime-fouten (standaard 10; 0 = alles)
`reflect::compactRoutes`	Routekaart met bestand, regel, methode, afhankelijkheidsgebruik
`reflect::compactViews`	Lijst van views met naam, bestand, regel
`reflect::routes`	Alle routeknopen met volledige details en opmerkingen
`reflect::views [withBody]`	Alle viewknopen; geef `true` door voor lichamen
`reflect::sourceFiles`	Alle `.phlo` bronbestands paden
`reflect::sourceNodes [withBody]`	Volledige geparseerde AST van alle bronbestanden
`reflect::fileContent <relPath>`	Inhoud van het bronbestand op basis van het weergavepad
`reflect::find <type> [name] [withBody] [scope]`	Knopen van een type; scope `app`/`resources`/`all`
`reflect::nodeBody <name> [type]`	Lichaam van een benoemde knoop (standaard type `method`)
`reflect::search <query> [scope] [maxHits] [contextLines]`	Tekstzoekopdracht in `.phlo` bestanden
`reflect::graph`	Typed backend grafiek: knopen en semantische randen
`reflect::selectorGraph`	Typed frontend grafiek: stijl/script/selector randen
`reflect::resourceDependencies <name> [transitive] [full]`	Vereiste resources van `@ requires`
`reflect::fileDependencies`	Afhankelijkheidskaart per bestand van `phlo()` en `Class::` oproepen
`reflect::functionIndex`	Alle functies met handtekeningen, bron, groep, laadstatus
`reflect::objectIndex`	Alle resource-objecten met methoden, props, constructor, metadata
`reflect::resourceSummary`	Pakket tellingen, functie/object totalen, externe vereisten
`reflect::resourceFiles`	Alle resource-bestandspaden
`reflect::availableResources`	Alle ontdekbare resources met type, soort, laadstatus
`reflect::editorIndex`	Gecombineerde index van functies, objecten, routes, views
`reflect::findFunction <name>`	Resource-invoer voor een functie op naam, of null
`reflect::findClass <name>`	Resource klasse-invoer op naam of alias, of null
`reflect::help`	Alle methoden met handtekeningen en beschrijvingen

10.3: Algemene CLI-dispatch

build:: en reflect:: zijn slechts twee voorbeelden van een algemener mechanisme. De CLI van Phlo kan elke static, method of functie in je app aanroepen:

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

Drie patronen:

Patroon	Dispatch	Voorbeeld
`Class::method args`	Statische methode op de klasse	`tasks::run`, `backup::nightly`
`object.method args`	Instantiemethode via `phlo(object)`	`app.heartbeat`, `cms.reindex`
`function args`	Globale functie	`answer "question"`

De uitvoer gaat naar stdout als JSON, fouten gaan naar stderr met een niet-nul exitcode. Dit maakt elke routine in je app direct bruikbaar vanuit cron, deployscripts, monitoring of een terminal, zonder dat je een aparte CLI-laag hoeft te bouwen.

phlo_eval: voer Phlo uit tegen de live app

De krachtigste functie-dispatch is phlo_eval, die een string van Phlo transpileert en deze uitvoert in de live app. Het is de runtime aanvulling op reflect::: reflectie leest de statische bron, phlo_eval voert uit tegen echte gegevens, bronnen en 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 %app->error('boom')"     # raw HTML, not JSON

Een enkele regel auto-retourneert zoals een => pijllichaam, dus je schrijft alleen de expressie, geen return (tenzij het begint met return/apply/echo/unset/yield); alleen een meerregelige blok heeft zijn eigen return nodig. return print de waarde als JSON (type-veilig, niet-schaalbaar, fouten als {"error": ...}); echo print rauw naar stdout, handig voor het bekijken van gerenderde markup zoals deze is.

phlo_eval voert willekeurige code uit met volledige app-rechten: het kan geheimen lezen en de database muteren. Het is alleen CLI en alleen voor build, nooit aanwezig in release/productie. Behandel de invoer als alleen door ontwikkelaars geschreven, nooit onbetrouwbaar.

Alleen beschikbaar met build: true in www/app.php. Voer het niet uit tegen een live productieomgeving.

10.4: Debug helpers

Met debug: true in phlo_app(...) activeert Phlo een set helpers voor inspectie tijdens de ontwikkeling. In productie zijn ze inactief.

Helper	Doel	Gedrag
`d(...$args)`	Waarden dumpen in de respons, doorgaan met uitvoeren	Verzameld in `%res->dump`; weergegeven in de browserconsole aan het einde van het verzoek. Inactief zonder `debug: true`
`dx(...$args)`	Dump + STOP	Sync: volledige debugpagina met het source-mapped `.phlo` bestand en regel. Async/CLI/streaming: de dump komt in de browserconsole via de apply payload. Worker-veilig: gooit in plaats van `die()` aan te roepen
`debug($msg)`	Voeg een regel toe aan het debuglog; `debug()` zonder argumenten retourneert alles wat is verzameld	Gelogd in de browserconsole met de verzoekstatistieken
`error($msg, $code = 500)`	Runtimefout voor de Phlo-exceptiehandler	Gooit een `PhloException`, gelogd in `data/errors.json`
`trace($node, $args)`	Handmatige traceer gebeurtenis (alleen actief met `trace: true`)	Voegt een gebeurtenis toe aan het traceerlog, zie het Trace-hoofdstuk

De levenscyclus: helpers verzamelen tijdens het verzoek (%res->dump, %res->debug); aan het einde van een sync-pagina logt een inline script alles naar de browserconsole samen met geheugen-, duur- en trace-metadata, en async-responsen dragen dezelfde gegevens in hun apply payload. Objecten worden uitgepakt via objInfo(). Runtimefouten worden verzameld in data/errors.json (bericht, source-mapped bestand en regel, aantal, laatste optreden); lees ze met reflect::errors of in het Phlo Control Center.

method buildReport {
	$data = $this->load
	debug('loaded', count: count($data))
	if (!$data) error('No data to report')
	dx($data[0])
}

dx() is je primaire "stop en kijk naar wat er is" tool tijdens de ontwikkeling. Vergeet je een dx() in de code die naar release gaat? In debug: false modus gedraagt het zich net als error(), zonder stille doorgang.

10.5: Workflow

In een ontwikkelomgeving plaatst het Phlo Control Center (op /phlo) deze hele lus in de browser: source, build, release en fouten, met elk bestand één klik verwijderd:

De Phlo Control Center source view: elk .phlo-bestand gemarkeerd en doorzoekbaar, één klik van build, release en fouten

Lees eerst de source en de reflection output.
Wijzig alleen .phlo, data/app.json of entrypoints.
Voer build::run uit.
Voer build::lint uit.
Test de relevante HTTP routes.
Voer build::release uit wanneer de stage/release output moet worden bijgewerkt.

10.6: Ontwikkeling, staging en productie

Dev heeft doorgaans:

auth: true,
build: true,
debug: true,

In build+debug-modus bevindt de ingebouwde controle-UI zich standaard op /phlo; gebruik control: 'path' in phlo_app(...) om een ander pad te kiezen. Staging/productie draait doorgaans zonder build en zonder debug. De webroot wijst naar release/www/.

10.7: KOP en async

De huidige runtime ondersteunt de normale HTTP-methoden, inclusief HEAD. Async verzoeken worden afgehandeld door de frontend resource en gebruiken dezelfde routes als sync verzoeken, tenzij je expliciet een andere route declareert.