Download the PHP package componenta/router without Composer

Componenta Router

Runtime HTTP router for Componenta applications. The package provides immutable route records, fluent route building, route groups, route collections, path pattern compilation, optimized compiled routes, URL generation, PSR-15 route matching and dispatch middleware, handler resolution, and router exception handlers.

Attribute discovery, production route-cache generation, and HTTP-interceptor route handler resolution live in componenta/router-app.

Installation

Package Boundaries

componenta/router owns runtime routing behavior. It can work with explicitly registered routes and does not require class scanning.

Related Packages

Use componenta/router for:

• route records and route collections;
• route matching and URL generation;
• grouped routes and middleware groups;
• PSR-15 matching/dispatch middleware;
• compiled route collections loaded from cache;
• route exception handling.

Use componenta/router-app for:

• discovering #[Route] attributes;
• generating route cache files;
• integrating route compilation with the application cache pipeline;
• resolving route handlers through HTTP interceptors.

Route Records

RouteRecord is an immutable route definition.

Public fields:

Static constructors exist for get, post, put, patch, delete, head, options, and any.

RouteRecord validates early:

• method list must not be empty;
• every method must be a non-empty string;
• token patterns must be valid regular expressions;
• default values must be scalar or null.

Fluent Builder

RouteBuilder is useful when a route is assembled conditionally.

build() throws LogicException when no handler was set.

Path Syntax

The default compiler uses CompositeSyntax, so several parameter syntaxes are accepted:

Explicit tokens override inline tokens. Explicit defaults override inline defaults.

Groups

RouteGroup applies name prefix, path prefix, middleware, tokens, and defaults to child routes.

The route above is registered as:

• name: api.admin.dashboard
• path: /api/admin/dashboard
• middleware: api, auth, admin
• group: api.admin

Nested groups are registered in the parent collection, so later routes can reference the full group name explicitly.

Route Collection

Routes implements:

• RouteCollectorInterface
• MatcherInterface
• GeneratorInterface
• Countable
• IteratorAggregate

Routes compiles static and dynamic lookup tables lazily after registration. Static routes use hash lookup. Dynamic routes use compiled regex patterns.

Routes accepts an optional SyntaxParserInterface as the named syntax argument for URL generation. When omitted, it uses the built-in Compiler syntax, or CompositeSyntax for another CompilerInterface implementation. A custom compiler does not need to expose a syntax property.

Router Facade

Router combines a route collector, matcher, and generator.

match() throws:

• RouteNotFoundException when no route matches URI and method;
• MethodNotAllowedException when the URI matches but the method is not allowed.

generate() throws:

• RouteNotRegisteredException when the route name is missing;
• InvalidArgumentException when required parameters are missing or invalid.

Match Result

MatchResult contains data needed for dispatch:

Matched parameters are cast from numeric strings to integers or floats when possible.

PSR-15 Middleware

MatchRouteMiddleware matches the incoming request and stores the result in request attributes:

• MatchRouteMiddleware::ATTRIBUTE_MATCH_RESULT
• every matched route parameter under its parameter name

DispatchRouteMiddleware reads the match result and resolves route middleware through MiddlewareFactory.

DispatchRouteMiddleware resolves route middleware on every request through the configured factory. The container and middleware resolver determine object lifetimes; compiled route collections preserve the same resolution and execution behavior.

Router Exception Handlers

Compiled Routes

CompiledRoutes loads an explicitly compiled route collection from a generated cache file.

Performance model:

• static routes use O(1) hash lookup;
• dynamic routes can use one regex per HTTP method;
• large dynamic sets can be split into chunks;
• prefix index reduces the number of chunks checked;
• route handler definitions and middleware groups are initialized lazily.

The cache file is generated by RouteCacheGenerator, normally through componenta/router-app and app:build. Production service factories load the map when optimization is enabled. Rebuild it whenever route definitions, configuration or external inputs used by the route source change. Combined expressions are checked against PCRE limits and oversized groups are split further. If a combined expression exhausts a matching limit, matching continues through the original individual route patterns. CachedRouteLocator falls back to its supplied source when generated data is invalid, including when the application converts warnings into exceptions.

Replacing a compiled collection's public compiler before its first match uses the source matching path. URL generation uses the current compiler while retaining any explicitly configured generation syntax. Cache format 8 records whether that syntax was explicit; tryFromCache() rejects older formats so its caller can use the source.

Attribute Route Metadata

#[Route] is the runtime metadata class consumed by application discovery.

Constructor:

methods accepts a string ('GET'), a |-separated string ('GET|POST'), or an array (['GET', 'POST']). priority is used by componenta/router-app: when multiple attribute routes can match the same URI, the route with the higher priority is added first.

The base router package does not scan this attribute. Discovery belongs to componenta/router-app.

Configuration

ConfigProvider registers:

• RouteLocatorInterface
• Router
• MatchRouteMiddleware
• DispatchRouteMiddleware
• RouteHandlerResolver
• Compiler
• ThrowingRouterExceptionHandler
• aliases for CompilerInterface, RouterExceptionHandlerInterface, MatcherInterface, and GeneratorInterface

Config keys:

Failure Model