Download the PHP package laikait/laika-route without Composer

laika-route

The router of the Laika PHP MVC Framework: routes, named URLs, groups, pipelines (middleware before the controller), filters (middleware after it), fallbacks and static-file serving.

Install

laika-core requires it, so a Laika app already has it. Registering routes needs only PHP 8.1+.

Url::dispatch() and Asset::serve() additionally call the Laika\Service\* relays (Response, CORS, Config, Infra, MimeType), which this package deliberately does not require: laika-core requires laika-route, so depending on it here would be a cycle. They are resolved at runtime inside a booted Laika app, and the test suite stands in its own doubles for them. Outside an app, route registration and the path helpers work on their own; dispatching does not.

In an app, routes live in lf-routes/*.php. Every file there, subdirectories included, is loaded when a request is dispatched.

Routes

Every verb has the same signature: Url::get(string $uri, mixed $controller, string|array $pipelines = []): Url. There's no any(), match(), head() or redirect().

• Registering the same method and URI twice replaces the first handler.
• /users/ and /users are the same route.
• Routes are tried in registration order; the first match wins. Register /users/new before /users/{id}.

Handlers

A string handler always gets App\Controller\ prepended unless it starts with \, so 'App\Controller\HomeController@index' fails.

A handler returns a string, which is sent, or null, which sends nothing. Arrays and objects are a TypeError. The response is rendered according to the content type set on laika-core's Response (HTML by default).

Controllers, pipelines and filters are built through a resolver. laika-core sets it to the service container, which gives them constructor injection. Without a resolver, the router uses a plain new:

Controller method arguments are filled by name from route parameters and pipeline values, then by type from the resolver, then from defaults.

Parameters

• {name} matches one path segment. {name:regex} uses your pattern, matched with the u flag.
• A constraint can't contain }, so {year:[0-9]{4}} breaks. Write [0-9][0-9][0-9][0-9].
• There are no optional parameters. Register two routes.
• Values reach the controller as strings. int $id is a TypeError under strict_types.
• Routes may contain any UTF-8 character. Request paths are percent-decoded per segment before matching.

A path with a file extension is a static file only when a real file is there. Otherwise it routes like any other URL, so /sitemap.xml, /feed.json and /users/john.doe all work. A file that exists always wins over a route for the same path — and if lf-config/assets.php refuses that file, the request is refused rather than routed. See Static Files.

Named Routes

Names are unique across the app; registering one twice throws RuntimeException. A placeholder you don't pass stays in the URL, and extra params are ignored. In a Laika app, the named() helper returns the absolute URL, including any sub-directory.

Groups

To put middleware on a group, pass it to Handler::registerGroup(). It applies to every route inside, including nested groups:

Signature: Handler::registerGroup(string $prefix, callable $callback, string|array $pipelines = [], string|array $filters = []): void.

Url::group(...)->pipeline([...])->filter([...]) also works, for a top-level group only. It runs after the callback and appends to every route registered so far whose URI starts with /prefix. On a nested group it matches nothing, because it only knows its own prefix.

Pipelines

Middleware that runs before the controller.

• Short names resolve to App\Pipeline\; a fully qualified name is used as written.
• $params holds route parameters plus pipeline args, passed by reference through pipelines, controller and filters.
• Args ('Name|key=value,flag') are strings (a bare key is true), aren't trimmed, and override a route parameter of the same name.
• Order: global → registerGroup() → third argument → ->pipeline() → group-chained ->pipeline().

Filters

Middleware that runs after the controller, on its response string.

Short names resolve to App\Filter\. Filter args are visible to later filters only, never to the controller. Filters don't run on fallbacks, 404s or static files.

Fallback

Url::fallback(?string $group, callable $callback, string|array $pipelines = []): void

• The longest matching prefix wins. With no route and no fallback, the built-in _404 page is sent with status 404.
• The prefix is absolute, even when fallback() is called inside a group.
• The callback takes no arguments and returns a string, sent as HTML. The status stays 200 unless you set it.
• Global pipelines and filters don't run; pass pipelines as the third argument.

Dispatch

index.php calls it once per request. In order, it:

1. sends the CORS headers (once per request);
2. normalises the path;
3. serves a static file if one is on disk (see Static Files) — usually already done, see below;
4. loads the route files;
5. matches a route or a fallback;
6. runs the pipelines and the controller;
7. runs the filters;
8. renders the result by content type (HTML responses get a hidden _csrf field added to every <form>).

Static Files

Laika has no public/ directory and the shipped rewrite rules send every request to index.php, so Laika\Route\Asset is the only thing deciding what may leave the disk. Asset::serve() returns true when it answered the request and false when no file was there, which is what lets the dispatcher fall through to the router.

Dispatcher::dispatchAsset() is the same check as a standalone entry point, so an application can answer a static file early in its boot and skip loading everything a static file does not need. Laika's own lf-boot/app.php calls it right after the autoloader. The only caveat is that anything set up later — a hook registering a mime type, say — has not run yet.

Two independent questions decide servability — where the path resolved to (realpath(), never the request string) and what its extension is — and both are covered by the test suite. A refusal renders the same 404 an unrouted URL renders, so a forbidden path cannot be told apart from a missing one.

What it sends:

In an app this is configured by lf-config/assets.php (extensions, blocked, untrusted, cache, sendfile). With no container to read it from, built-in defaults apply: the php family and every markup type are refused.

API Reference

Documentation

The framework docs cover this package in depth: Routing, Controllers, Pipelines, Filters and Request Lifecycle.

License

MIT. See LICENSE.