README

Application integration for componenta/router. The package adds #[Route] discovery, connects route cache generation to application cache compilation, registers the HTTP routing bootloader, 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:

Requirement	Version
PHP	^8.4

Packages:

Package	Purpose
componenta/app	Application bootloader registration.
componenta/app-http	HTTP boot target that receives routing middleware during boot.
componenta/router	Route records, matching, URL generation, dispatch middleware, and route cache loading.
componenta/class-finder	Class scanning and listener notification.
componenta/config	Shared configuration object and router config keys.
componenta/di	Factory and autowire registration through ConfigProvider.
componenta/http-responder	Optional Responder for non-PSR-7 handler results.
componenta/interceptor	HTTP interceptor pipeline for InterceptedRouteHandlerResolver.
componenta/middleware-factory	Middleware resolver registration for route handlers.
componenta/path-resolver	Resolving route file paths relative to the application root.
componenta/reflection	Reading #[Route] metadata from classes and inherited declarations.
componenta/tokenizer	Class information passed by the scanner.
componenta/var-export	Exporting compiled route arrays into PHP cache files.
psr/container	Retrieving dependencies from the container.
psr/http-message	Response contracts used by route handlers.
psr/http-server-middleware	Middleware contracts used by route dispatch.

Install:

composer require componenta/router-app

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

return [
    new Componenta\Http\Router\ConfigProvider(),
    new Componenta\Http\Router\App\ConfigProvider(),
];

Registered Services

Componenta\Http\Router\App\ConfigProvider adds:

Service or key	Registration
RouteLocatorInterface	router-app RouteLocatorFactory, which selects the development or production locator.
InterceptedRouteHandlerResolver	Factory for HTTP-interceptor route handler resolution.
InterceptorConfigKey::HTTP_PIPELINE	Default HTTP interceptor pipeline factory.
RouteCacheCompiler	Autowired route cache compiler.
CompileConfigKey::LISTENER_COMPILERS	Adds RouteCacheCompiler to the class-finder listener compiler list.
AppConfigKey::BOOTLOADERS	Adds RoutingBootloader for HTTP applications.
MiddlewareConfigKey::RESOLVERS	Adds InterceptedRouteHandlerResolver to the middleware resolver list.
RouterConfigKey::ROUTES_FILE	Sets the default route file to config/routes.php.

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

HTTP Boot

RoutingBootloader runs only in the HTTP scope. During boot it pipes MatchRouteMiddleware and DispatchRouteMiddleware into the HTTP boot target:

$app->pipe(Componenta\Http\Router\Middleware\MatchRouteMiddleware::class);
$app->pipe(Componenta\Http\Router\Middleware\DispatchRouteMiddleware::class);

Applications that use componenta/app-http and register this package provider do not need to add those two middleware manually.

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:

use Componenta\Http\Router\Attribute\Route;
use Psr\Http\Message\ResponseInterface;

#[Route(
    name: 'posts.show',
    path: '/posts/[id:\d+]',
    methods: 'GET',
    middlewares: ['web'],
)]
final readonly class ShowPostController
{
    public function __invoke(int $id): ResponseInterface
    {
        // ...
    }
}

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.

use Componenta\Http\Router\Routes;

/** @var Routes $routes */

$api = $routes->group('api', '/api', middleware: ['api']);
$api->get('health', '/health', HealthController::class);

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:

Condition	Factory result
APP_ENV=production	Base componenta/router RouteLocatorFactory. It reads cache when cache use is enabled and the cache file exists.
Any other environment	AttributeRouteLocator, which loads the route file and appends discovered attribute routes.

The base RouteLocatorFactory uses cache only when ConfigKey::COMPILED_PIPELINE or HTTP_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:

use Componenta\Http\Router\ConfigKey;

return [
    ConfigKey::ROUTES_FILE => 'config/routes.php',
    ConfigKey::ROUTES_CACHE_FILE => 'var/cache/router/routes.cache.php',
    ConfigKey::COMPILED_PIPELINE => true,
];

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:

use Componenta\Http\Middleware\ConfigKey as MiddlewareConfigKey;
use Componenta\Http\Router\App\Resolver\InterceptedRouteHandlerResolver;

return [
    MiddlewareConfigKey::RESOLVERS => [
        InterceptedRouteHandlerResolver::class,
    ],
];

InterceptedRouteHandlerResolverFactory reads:

Dependency	Source
CallableExecutorInterface	Container.
HTTP interceptor pipeline	Componenta\Interceptor\ConfigKey::HTTP_PIPELINE.
Responder	Container, when registered.

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

The default HTTP interceptor pipeline contains parameter resolution and attribute interceptors. Applications can replace Componenta\Interceptor\ConfigKey::HTTP_PIPELINE when they need a custom interceptor chain.

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;
• piping router middleware into the HTTP application during boot;
• dispatching route handlers through HTTP interceptors.