5: Routeren

Routing in Phlo koppelt een spatie-gescheiden pad + HTTP-methode aan een doel (meestal een methode). Routes van alle .phlo-bestanden worden verzameld; de router wordt geactiveerd met app::route().

5.1: Basisformulier

route [async|both] [GET|POST|PUT|DELETE|PATCH|QUERY] pad [pad2 ...] => target

• Paden worden geschreven met spaties (geen / in de route-definitie).
• Doel: een directe aanroep of statementblok.

Voorbeeld:

route GET home => $this->main
method main => view($this->home)

QUERY (RFC 10008) is een veilige, idempotente leesbewerking die een aanvraaglichaam meedraagt, voor een opzoeking waarvan de parameters niet netjes in een URL passen. %payload decodeert het QUERY-lichaam op dezelfde manier als het POST decodeert (JSON, form-urlencoded, multipart), en HTTP() neemt een bijpassend QUERY: argument voor het aanroepen van een andere QUERY-eindpunt.

route QUERY search => $this->search
method search => dx(%payload->filters)

5.2: sync / async / beide

route both GET data => $this->loadData
route async POST items save => $this->saveItems

5.3: Variabelen

Phlo parseert elk padsegment. Segmenten die beginnen met $ zijn variabelen met extra mogelijkheden:

4.3.1 Vereist (doorgegeven aan de doelbestemming)

route GET user $id => $this->showUser($id)
method showUser($id) => view($this->profile)

4.3.2 Optionele aanwezigheid met ? → boolean

route GET search $full? => $this->search($full)

• Komt overeen met /search en /search/full.
• $full is waar wanneer het segment full aanwezig is, anders onwaar. (De implementatie controleert letterlijk of het aanvraagsegment gelijk is aan de naam zonder de ?.)

4.3.3 Rest (variabele lengte) met =*

route GET file $path=* => $this->serveFile($path)

• Matcht alle resterende segmenten als één string in $path.

4.3.4 Standaardwaarde met =

route GET page $slug=home => $this->page($slug)

• Zonder een segment → $slug = 'home'.
• Met een segment → $slug = '<value>'.

4.3.5 Lengte-eis met .N

route GET code $pin.6 => $this->enter($pin)

• Matcht alleen wanneer de lengte van $pin precies 6 is.

4.3.6 Waardenlijsten met :a,b,c

route GET report $range:daily,weekly,monthly => $this->report($range)

• Het segment moet een van de opgegeven waarden zijn.
• Wanneer het segment afwezig is (leeg) en er een standaard is ingesteld, wordt de standaard toegepast.
• Anders faalt de overeenkomst.

Je kunt deze vormen combineren. Voorbeelden:

Enum met een vereiste id:

route GET export $fmt:csv,json $id => $this->export($fmt, $id)

Enum met een standaard:

route GET theme $name:light,dark=light => $this->theme($name)

5.4: Payload controle met `@`

Je specificeert exacte body-sleutels met een enkele @ en een komma-gescheiden lijst. De router vergelijkt dit 1-op-1 met de sleutels van %payload (exacte set; volgorde zoals geleverd door de engine).

route POST user @name,email => $this->createUser

method createUser => dx(%payload->name, %payload->email)

Body-sleutels zijn niet gebonden als methodeparameters; je leest ze via %payload.

5.5: Doelen

Lokale method

route GET profile show => $this->show
method show => view($this->profile)

Externe klasse methode (static)

route GET api version $major => api::getVersion($major)

• Statische aanroepen: haakjes vereist, zelfs zonder argumenten.
• Geef padvariabelen expliciet door.

Wat een route kan retourneren

De dispatcher inspecteert de retourwaarde op precies één ding: false betekent "niet mijn route" en de matching gaat verder met de volgende kandidaat. Elke andere retourwaarde wordt genegeerd.

Les. De aanname "een route retourneert zijn responsbody" produceert route GET hello => 'Hello': de route matcht en levert een 200 met een lege pagina. Een route produceert output uitsluitend via view(), apply(), output(), location() of de %res API.

Het false contract is ook een hulpmiddel: een catch-all route GET guide $slug die false retourneert voor onbekende slugs laat een letterlijke route in een later bestand (GET guide index.json) nog steeds dezelfde URL matchen.

Principe: reageer zonder een redirect. Verzoek en respons zijn ontkoppeld, zodat een route het werk kan doorsturen naar een andere routine en zijn output kan retourneren, waardoor in één verzoek wordt geantwoord in plaats van te redirecten. Voor een async verzoek, retourneer apply()/view() direct met path: (de SPA wisselt ter plaatse, geen tweede verzoek); voor een sync POST die gewoon een pagina opnieuw toont, stuur door naar de routine van die pagina in plaats van location() aan te roepen. location() blijft het juiste hulpmiddel voor een sync verzoek dat de URL moet canonicaliseren (POST-redirect-GET, of een harde navigatie), wat de engine zelf doet wanneer een sync view() een andere string path: ontvangt. Het doel is om de onnodige roundtrip te vermijden, niet om redirects te verbieden.

5.6: De router activeren

Routes worden alleen gematcht na:

app::route()

Plaats deze aanroep bijvoorbeeld in app.phlo (of een andere centrale controller) na de initialisatie van je app en vóór een fallback voor 404-afhandeling.

5.7: Aanbevolen structuur

• Plaats routes bovenaan elk bestand.

• Houd pad en methodenaam logisch uitgelijnd:

  route GET users list  => $this->listUsers
  route POST users add  => $this->addUser

• Altijd variabelen doorgeven in de target.
• Gebruik both alleen wanneer een endpoint opzettelijk zowel sync als async moet zijn.
• Gebruik waardelijsten :… in plaats van aparte if takken voor vaste varianten.