Download the PHP package componenta/router-app without Composer

Componenta Router App

Application integration for componenta/router. The package adds #[Route] discovery, connects route cache generation to application cache compilation, registers the route locator as a class-finder listener, and provides route handler resolution through HTTP interceptors.

Runtime code that only matches routes, generates URLs, or dispatches route handlers without HTTP interceptors should depend on componenta/router. componenta/router-app belongs in application assembly code: it connects the router with class discovery, application cache compilation, and the interceptor pipeline.

Dependencies

PHP:

Packages:

Install:

Register this provider after the runtime router provider. The order matters because router-app replaces the RouteLocatorInterface factory with the integration factory:

Registered Services

Componenta\Http\Router\App\ConfigProvider adds:

Route records, Router, Routes, MatchRouteMiddleware, DispatchRouteMiddleware, RouteHandlerResolver, CompilerInterface, MatcherInterface, and GeneratorInterface stay in componenta/router.

HTTP Pipeline

RoutingBootloader runs only for the HTTP application scope. During boot it adds routing middleware to the HTTP boot target with priority 50:

Applications that register this provider do not add these two middleware manually. Put middleware that must run before routing, such as error handling or body parsing, into config/pipeline.php with a higher priority, for example 100.

Route Discovery

AttributeRouteLocator implements RouteLocatorInterface, ClassListenerInterface, and FinalizableListenerInterface. In development mode, RouteLocatorFactory returns this locator.

Flow:

1. RouteLocatorFactory reads ConfigKey::ROUTES_FILE, resolves it through PathResolverInterface, and creates a base RouteLocator.
2. AttributeRouteLocator loads explicit routes from that route file.
3. During scanning, class-finder passes discovered classes to AttributeRouteLocator::handle().
4. The locator reads #[Route] metadata through Reflection::getDeepMetadata().
5. After scanning, finalize() sorts discovered attributes by priority from highest to lowest and adds them as RouteRecord instances.

Example:

The attribute only describes the route. Middleware and handler execution are owned by componenta/router and componenta/middleware-factory.

methods accepts a string ('GET'), a |-separated string ('GET|POST'), or an array (['GET', 'POST']). When multiple attribute routes can match the same URI, the route with the higher priority is added first.

Route File

ConfigKey::ROUTES_FILE remains the route entry file even when attributes are enabled. This package sets its default value to config/routes.php. Use that file for manual routes, groups, and shared route setup, or override the config key when the application keeps routes somewhere else.

In development, attribute routes are added to routes from this file. In production, the application should read the compiled route cache.

Development And Production

router-app RouteLocatorFactory selects the locator by environment:

The base RouteLocatorFactory uses cache only when ConfigKey::COMPILED_PIPELINE is enabled and the cache file exists.

Route Cache Compilation

RouteCacheCompiler is registered through CompileConfigKey::LISTENER_COMPILERS. It supports only AttributeRouteLocator.

compile():

• runs only in CLI;
• requires ConfigKey::ROUTES_FILE;
• uses ConfigKey::ROUTES_CACHE_FILE when it is configured;
• otherwise derives the cache path from the route file, for example routes.php -> routes.cache.php;
• compiles the current route collection through RouteCacheGenerator;
• returns CompileResult::filesOnly() so the cache builder can write the PHP cache file.

Configuration example:

Console Commands

When componenta/app-console is installed, this package contributes router:list through Componenta\App\Console\ConfigKey::COMMANDS.

The command resolves RouteLocatorInterface from the container and lists method, path, route name, group, and handler. It uses the same locator as the running application, so development mode includes routes from config/routes.php and discovered #[Route] attributes, while production mode uses the production locator and route cache behavior.

HTTP Interceptors

InterceptedRouteHandlerResolver lives in componenta/router-app because it integrates routing with the application HTTP interceptor pipeline. The base componenta/router package dispatches handlers directly through RouteHandlerResolver and does not depend on componenta/interceptor.

The provider registers it in the componenta/middleware-factory resolver list by default:

InterceptedRouteHandlerResolverFactory reads:

If Responder is not registered, route handlers must return ResponseInterface, MiddlewareInterface, or RequestHandlerInterface; other values fail during dispatch.

The HTTP interceptor pipeline is created by componenta/interceptor. Its factory always adds ParameterResolvingInterceptor, then appends interceptor service ids from Componenta\Interceptor\ConfigKey::HTTP_INTERCEPTORS. A typical HTTP application adds AttributeInterceptor::class to that list so route handlers can use #[Intercept].

Package Boundaries

Use componenta/router for:

• explicit route registration;
• URI and HTTP-method matching;
• URL generation;
• route groups;
• PSR-15 match and dispatch middleware;
• loading already compiled route cache files.

Use componenta/router-app for:

• discovering #[Route] in application source code;
• connecting route compilation to application cache compilation;
• dispatching route handlers through HTTP interceptors.