README

Optional performance diagnostics for WilyCode Router.

Measure how much time is spent preparing routes, matching requests, running middleware, and invoking controllers. The router works normally without this package.

WilyCode PHP Ecosystem

Part of WilyCode — independent PHP components, each with its own repository, releases, and Composer package.

Explore the WilyCode ecosystem →

How it works

wilycode/router-profiler provides ProfilingRoutingObserver, an adapter between two libraries:

wilycode/router exposes optional observation hooks without depending on a profiler.
wilycode/profiler defines the shared profiling interface.

The adapter passes each routing phase to your profiler implementation. It does not collect or store measurements itself.

Requirements

PHP 8.4 or newer.
wilycode/router ^0.1.
wilycode/profiler ^0.1.

To use the concrete Profiler shown below, install wilycode/profiler-php separately.

Installation

composer require wilycode/router-profiler wilycode/profiler-php

The first package provides the integration. The second provides the PHP implementation used in the examples. You can use another implementation of ProfilerInterface instead.

Quick start

<?php

declare(strict_types=1);

use WilyCode\ProfilerPhp\Profiler;
use WilyCode\Router\Router;
use WilyCode\RouterProfiler\ProfilingRoutingObserver;

// Your application provides a PSR-11 $container and PSR-7 $request.
$profiler = new Profiler();
$observer = new ProfilingRoutingObserver($profiler);
$router = new Router($container, $observer);

// Register your route collections as usual.
$router->addCollection($routes);

$response = $router->dispatch($request);

// Read timings after the request has been handled.
foreach ($profiler->getMetrics() as $metric) {
    printf(
        "%s: %d call(s), %.2f ms\n",
        $metric->name(),
        $metric->count(),
        $metric->durationMilliseconds(),
    );
}

$routes is an ordinary RouteCollection from wilycode/router. See its documentation for registering routes and handling responses.

Nothing is enabled automatically. The integration runs only when you pass the observer as the Router constructor's second argument.

Router without profiling

No extra configuration is required:

$router = new Router($container);

You can omit this package entirely in applications that do not need routing diagnostics.

Recorded phases

Metric	What it measures
`router.prepare`	Preparing routing indexes; minimal work when using compiled routes
`router.collection.load`	Loading route collections when preparing routes
`router.match`	Matching the request to a route
`router.middleware`	Running the middleware pipeline
`router.middleware.resolve`	Resolving middleware implementations
`controller.resolve`	Resolving the route handler
`controller`	Resolving arguments and executing the controller
`controller.arguments`	Resolving controller arguments
`controller.action`	Executing the controller action

These metrics can be nested, so their durations can overlap. Do not add every duration together to calculate total request time.

For compiled routes, router.collection.load is not recorded because the collections do not need to be loaded during dispatch.

Metrics and traces

The adapter uses ProfilerInterface::measure() for each phase. With wilycode/profiler-php, this produces aggregated metrics: operation names, durations, and call counts.

It does not automatically create individual trace entries. For operation-specific traces with context, your application can call the profiler's trace() method separately.

Profiling measures elapsed time and adds a small runtime cost. Enable it where diagnostic information is useful.

Related packages

Package	Purpose
`wilycode/router`	HTTP routing and middleware
`wilycode/router-attribute`	Attribute-based route discovery
`wilycode/profiler`	Shared profiling contracts
`wilycode/profiler-php`	PHP profiling implementation

Install only the packages your application needs.

Development

composer install
composer validate --strict
composer test

The tests cover normal and compiled routes, as well as observer behavior. GitHub Actions runs the PHPUnit suite for pushes and pull requests. Tests stay in the source repository and are excluded from distribution archives.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md and GitHub Issues.

wilycode / router-profiler

Package info

Security

Statistics