PHPackages                             nih/router - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. nih/router

ActiveLibrary[HTTP & Networking](/categories/http)

nih/router
==========

Tree-based PHP router for runtime-built route configuration, convention-based matching, URL generation, and PSR-15 middleware integration.

0.2.0(2mo ago)393MITPHPPHP 8.4 - 8.5

Since Mar 27Pushed 2mo agoCompare

[ Source](https://github.com/nih-soft/router)[ Packagist](https://packagist.org/packages/nih/router)[ RSS](/packages/nih-router/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (16)Versions (5)Used By (3)

NIH Router
==========

[](#nih-router)

Tree-based, site-aware router configuration for PHP with convention-based matching, optional PSR-15 dispatch, and URL generation.

Why Another Router
------------------

[](#why-another-router)

Routers like Symfony Router are excellent, but they are optimized around a compiled representation. If route configuration must be assembled dynamically at runtime and cannot be persisted, a classic short-lived PHP request pays that build cost again on every request.

There is another practical issue: in many popular routers every route is described explicitly, one by one. On large projects that gets repetitive fast. When whole branches follow predictable naming, a convention-based rule can be much easier to maintain than a long flat list of route declarations.

This package targets a different space:

- no separate compile step
- runtime-built configuration when needed
- tree/group-oriented configuration instead of route-by-route registration
- convention-based matching and generation for large route subtrees
- middleware scopes attached to any branch

What It Is
----------

[](#what-it-is)

- a tree-based configuration API centered around branches, not a flat explicit route registry
- a core runtime made of `RouteMatcher` and `UrlGenerator`
- an optional PSR-15 integration layer built on the same config tree

When To Use It
--------------

[](#when-to-use-it)

This package fits best when:

- different modules need to extend the same path subtree independently
- large route branches follow naming conventions
- you want the same configuration to drive matching, generation, and dispatch

Installation
------------

[](#installation)

```
composer require nih/router

```

Minimal Example
---------------

[](#minimal-example)

```
use NIH\Router\RouteMatcher;
use NIH\Router\RouterConfig;
use NIH\Router\Strategy\PathToClassStrategy;
use NIH\Router\UrlGenerator;

$config = new RouterConfig();

$config->site('https://example.com');

$config->path('/health')
    ->action('', App\Controller\HealthAction::class, '__invoke', ['GET']);

$config->path('/forums/')
    ->strategy(PathToClassStrategy::class, [
        'namespace' => 'App\\Controller\\Forums',
    ]);

$matcher = new RouteMatcher($config);
$generator = new UrlGenerator($config);

$health = $matcher->match('/health', 'GET');
$forum = $matcher->match('/forums/view', 'GET');

$path = $generator->generatePath('/forums/view');
$url = $generator->generateUrl('/forums/view', ['page' => 2]);

```

How to read this config:

- `path('/health')->action(...)` adds one exact terminal route
- `path('/forums/')->strategy(...)` attaches a rule to the whole `/forums/` subtree
- `PathToClassStrategy` resolves controller classes by path and HTTP method convention

Typical `PathToClassStrategy` mapping for namespace `App\\Controller\\Forums`:

- `GET /forums/` -> `App\\Controller\\Forums\\Get`
- `GET /forums/view` -> `App\\Controller\\Forums\\ViewGet`
- matched method is always `__invoke`

Core Runtime API
----------------

[](#core-runtime-api)

`RouteMatcher::match()` returns a `RouteMatchResult` object with:

- `status`
- `class`
- `method`
- `routeParams`
- `queryParams`
- `allowedMethods`
- `middlewares`

Status constants live on `RouteMatcher`:

- `RouteMatcher::FOUND`
- `RouteMatcher::NOT_FOUND`
- `RouteMatcher::METHOD_NOT_ALLOWED`

Important Notes
---------------

[](#important-notes)

- `generatePath()` and `generateUrl()` work with the logical configured path. Consumer strategies may fill real URL segments from params during generation.
- Consumer strategies may consume either the whole current remainder path, such as `PathTemplateConsumer`, or just one next segment, such as the segment consumers.
- Configured prefixes, runtime paths, and runtime sites are lowercased immediately.
- Runtime matching does not collapse repeated slashes or rewrite backslashes.
- The core router works with strings and arrays. PSR-7 and PSR-15 live in the middleware layer.

Documentation
-------------

[](#documentation)

- [docs/configuration.md](docs/configuration.md) - configuration model, `path()`, `action()`, strategies, middlewares, sites, aliases
- [docs/router.md](docs/router.md) - `RouteMatcher`, `UrlGenerator`, runtime rules, `RouteMatchResult`
- [docs/psr15-integration.md](docs/psr15-integration.md) - `RouteMatchMiddleware`, `RouteDispatchMiddleware`, dispatch attributes

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance85

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

4

Last Release

76d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/64707?v=4)[nih](/maintainers/nih)[@nih](https://github.com/nih)

---

Top Contributors

[![nih-soft](https://avatars.githubusercontent.com/u/264681698?v=4)](https://github.com/nih-soft "nih-soft (4 commits)")

---

Tags

psr-7middlewarerouterroutingpsr-15php-routerurl-generatortree-basedconvention-basedsite-aware

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/nih-router/health.svg)

```
[![Health](https://phpackages.com/badges/nih-router/health.svg)](https://phpackages.com/packages/nih-router)
```

###  Alternatives

[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B3.8k](/packages/guzzlehttp-psr7)[mezzio/mezzio

PSR-15 Middleware Microframework

3903.8M120](/packages/mezzio-mezzio)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[sunrise/http-router

A powerful solution as the foundation of your project.

17450.9k10](/packages/sunrise-http-router)[mezzio/mezzio-authentication-oauth2

OAuth2 (server) authentication middleware for Mezzio and PSR-7 applications.

28545.4k3](/packages/mezzio-mezzio-authentication-oauth2)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)