php-router

Lightweight PHP Router for REST APIs and SPAs. Standardized JSON responses, middleware, caching.

Why This Library?

What it does:

PSR-7/PSR-15 compliant routing with typed route parameters and auto-casting
Standardized JSON response format (pluggable via ResponderInterface)
Route caching with HMAC integrity verification
Middleware, route groups, named routes, URL generation

What it deliberately does not:

No optional route segments, no inline regex, no route priority system
No CORS, CSRF, authentication, or rate limiting (use middleware)
No async/Swoole runtime (use handle() + your own emitter)
Not optimized for >500 dynamic routes (O(n) matching)

Installation

composer require sodaho/php-router

Quick Start

use Sodaho\Router\Router;
use Sodaho\Router\Response;

$router = Router::create();
$router->loadRoutes(__DIR__ . '/routes.php');
$router->run();

routes.php:

use Sodaho\Router\RouteCollector;

return function (RouteCollector $r) {
    $r->get('/users', [UserController::class, 'index']);
    $r->get('/users/{id:int}', [UserController::class, 'show']);
    $r->post('/users', [UserController::class, 'store']);
};

Controller:

use Sodaho\Router\Response;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;

class UserController
{
    public function show(ServerRequestInterface $request, int $id): ResponseInterface
    {
        $user = ['id' => $id, 'name' => 'John'];
        return Response::success($user);
    }
}

HTTP Methods

$r->get('/users', $handler);
$r->post('/users', $handler);
$r->put('/users/{id}', $handler);
$r->patch('/users/{id}', $handler);
$r->delete('/users/{id}', $handler);
$r->options('/users', $handler);
$r->head('/users', $handler);

// Multiple methods
$r->match(['GET', 'POST'], '/search', $handler);

// All methods
$r->any('/webhook', $handler);

Route Parameters

// Basic parameter
$r->get('/users/{id}', $handler);

// With type constraint (validates + casts automatically)
$r->get('/users/{id:int}', $handler);        // Integer
$r->get('/price/{value:float}', $handler);   // Decimal
$r->get('/active/{flag:bool}', $handler);    // Boolean (true/false/1/0)

// Pattern constraints
$r->get('/posts/{slug:slug}', $handler);     // a-z, 0-9, hyphens
$r->get('/users/{uuid:uuid}', $handler);     // UUID format
$r->get('/files/{path:any}', $handler);      // Anything (including slashes)
$r->get('/codes/{code:alphanum}', $handler); // Alphanumeric

Available Patterns

Shorthand	Regex	Example
`int`	`-?\d+`	`{id:int}` → 123, -5
`float`	`-?\d+(?:\.\d+)?`	`{price:float}` → 19.99
`bool`	`true\|false\|0\|1` (case-insensitive)	`{active:bool}` → true, TRUE
`alpha`	`[a-zA-Z]+`	`{name:alpha}` → abc
`alphanum`	`[a-zA-Z0-9]+`	`{code:alphanum}` → abc123
`slug`	`[a-z0-9-]+`	`{slug:slug}` → my-post
`uuid`	`[0-9a-fA-F]{8}-...`	`{id:uuid}` → 550e8400-...
`ulid`	`[0-9A-Za-z]{26}`	`{id:ulid}` → 01ARZ3NDEKTSV4RRFFQ69G5FAV
`any`	`.*`	`{path:any}` → anything/here

Custom Patterns

$r->addPattern('date', '\d{4}-\d{2}-\d{2}');
$r->get('/events/{date:date}', $handler);  // 2024-12-06

Accessing Parameters

// Option A: Named arguments (recommended)
public function show(ServerRequestInterface $request, int $id): ResponseInterface
{
    // $id is already typed and validated
}

// Option B: From request attributes
public function show(ServerRequestInterface $request): ResponseInterface
{
    $id = $request->getAttribute('id');
}

Route Groups

$r->group('/api', function (RouteCollector $r) {
    $r->group('/v1', function (RouteCollector $r) {
        $r->get('/users', [UserController::class, 'index']);
    });
});
// → /api/v1/users

Middleware

use Psr\Http\Server\MiddlewareInterface;

// Per route
$r->get('/dashboard', [DashboardController::class, 'index'])
    ->middleware(AuthMiddleware::class);

// Multiple middleware
$r->get('/admin', [AdminController::class, 'index'])
    ->middleware([AuthMiddleware::class, AdminMiddleware::class]);

// Middleware group
$r->middlewareGroup([AuthMiddleware::class, LogMiddleware::class], function ($r) {
    $r->get('/profile', [ProfileController::class, 'show']);
    $r->put('/profile', [ProfileController::class, 'update']);
});

Route parameters are available in middleware:

class OwnershipMiddleware implements MiddlewareInterface
{
    public function process($request, $handler): ResponseInterface
    {
        $orderId = $request->getAttribute('id');  // Available!
        // ... ownership check
        return $handler->handle($request);
    }
}

Named Routes & URL Generation

$r->get('/users/{id}', [UserController::class, 'show'])
    ->name('user.show');

// Generate URL
$url = $router->url('user.show', ['id' => 5]);
// → /users/5

// Absolute URL (requires APP_URL env variable)
$url = $router->absoluteUrl('user.show', ['id' => 5]);
// → https://example.com/users/5

Redirect Routes

$r->redirect('/old-url', '/new-url');           // 302 Temporary
$r->redirect('/old-url', '/new-url', 301);      // 301 Permanent
$r->redirect('/users/{id}/profile', '/profile/{id}');  // With parameters

Response Helpers

Success Responses

Response::success($data);                              // 200
Response::success($data, 'Created successfully');      // 200 with message
Response::created($data);                              // 201
Response::created($data, 'User created', '/users/5');  // 201 with Location header
Response::accepted($data);                             // 202
Response::noContent();                                 // 204
Response::paginated($items, $total, $page, $perPage);  // 200 with pagination meta

Error Responses

Response::error('Something went wrong', 400);              // Generic error
Response::error('Invalid input', 400, 'INVALID_INPUT');    // With error code
Response::notFound('User', 123);                           // 404 "User with identifier 123 not found"
Response::notFound();                                      // 404 "Resource not found"
Response::unauthorized();                                  // 401
Response::unauthorized('Token expired');                   // 401 with message
Response::forbidden();                                     // 403
Response::validationError(['email' => 'Invalid format']);  // 422
Response::methodNotAllowed(['GET', 'POST']);               // 405
Response::tooManyRequests(60);                             // 429 with Retry-After
Response::serverError();                                   // 500

Other Responses

Response::html($content);                                // text/html
Response::html($content, 404);                           // text/html with status
Response::text($content);                                // text/plain
Response::redirect('/new-url');                          // 302
Response::redirect('/new-url', 301);                     // 301
Response::download($content, 'file.pdf');                // Attachment
Response::download($content, 'file.pdf', 'application/pdf');

JSON Structure

Success:

{
    "success": true,
    "data": { ... },
    "message": "Optional message",
    "meta": { "pagination": { ... } }
}

Error:

{
    "success": false,
    "message": "User-friendly message",
    "error": {
        "message": "Technical message",
        "code": "ERROR_CODE",
        "details": { ... }
    }
}

Configuration

Via Config Array

$router = Router::create([
    'debug' => true,
    'basePath' => '/api',
    'baseUrl' => 'https://api.example.com',
    'trailingSlash' => 'ignore',
]);

Via Environment Variables

// .env
APP_DEBUG=true
APP_ENV=development
APP_URL=https://api.example.com
ROUTER_BASE_PATH=/api
ROUTER_TRAILING_SLASH=ignore
ROUTER_CACHE_FILE=/var/cache/routes.php
ROUTER_CACHE_KEY=your-secret-key

Via Fluent API

$router = Router::create()
    ->setDebug(true)
    ->setBasePath('/api')
    ->enableCache(__DIR__ . '/cache/routes.php');

Options

Config Key	ENV Variable	Default	Description
`debug`	`APP_DEBUG`	`false`	Enable debug mode (detailed errors)
-	`APP_ENV`	`production`	If `dev`/`local`/`development` → debug=true
`basePath`	`ROUTER_BASE_PATH`	`''`	URL prefix for all routes
`baseUrl`	`APP_URL`	`null`	Base URL for `absoluteUrl()`
`trailingSlash`	`ROUTER_TRAILING_SLASH`	`'strict'`	`'strict'` or `'ignore'`
`cacheFile`	`ROUTER_CACHE_FILE`	`null`	Path to cache file
`cacheSignature`	`ROUTER_CACHE_KEY`	`null`	HMAC key for cache integrity

Caching

// Enable cache with optional HMAC signature
$router = Router::create()
    ->enableCache(__DIR__ . '/cache/routes.php', 'your-secret-key')
    ->loadRoutes(__DIR__ . '/routes.php');

$router->run();

Note: Closures cannot be cached. Use [Controller::class, 'method'] syntax.

Hooks (Logging)

// Log successful dispatches
$router->on('dispatch', function (array $data) {
    // $data: method, path, route, handler, params, duration
    $logger->info("Route matched", $data);
});

// Log 404 errors
$router->on('notFound', function (array $data) {
    // $data: method, path
    $logger->warning("404", $data);
});

// Log 405 errors
$router->on('methodNotAllowed', function (array $data) {
    // $data: method, path, allowed_methods
    $logger->warning("405", $data);
});

// Log exceptions
$router->on('error', function (array $data) {
    // $data: method, path, exception
    $logger->error("Error", $data);
});

Note: Hook exceptions are caught and logged to stderr. They never affect the response.

PSR-15 Compatibility

// run() for simple apps
$router->run();

// handle() for PSR-15 integration
$request = $serverRequestFactory->fromGlobals();
$response = $router->handle($request);  // Returns ResponseInterface

// Emit response yourself
(new SapiEmitter())->emit($response);

Dependency Injection

use Psr\Container\ContainerInterface;

$router = Router::create()
    ->setContainer($container)  // Any PSR-11 container
    ->loadRoutes(__DIR__ . '/routes.php');

// Controllers are resolved via container if available
// Otherwise instantiated directly

Exceptions

All exceptions extend RouterException:

use Sodaho\Router\Exception\RouterException;
use Sodaho\Router\Exception\NotFoundException;
use Sodaho\Router\Exception\MethodNotAllowedException;
use Sodaho\Router\Exception\RouteNotFoundException;
use Sodaho\Router\Exception\DuplicateRouteException;
use Sodaho\Router\Exception\CacheException;

try {
    $router->run();
} catch (RouterException $e) {
    // Catches all router exceptions
    echo $e->getMessage();
    echo $e->getDebugMessage();  // Additional debug info
}

Exception	When
`NotFoundException`	Available for application use (router returns 404 response directly)
`MethodNotAllowedException`	Available for application use (router returns 405 response directly)
`RouteNotFoundException`	Named route doesn't exist (URL generation)
`DuplicateRouteException`	Same method+pattern registered twice
`CacheException`	Cache read/write/signature failure

Trailing Slash Handling

// Default: strict (exact match)
$r->get('/users', $handler);   // Only matches /users
$r->get('/users/', $handler);  // Only matches /users/

// Ignore mode: /users matches both /users and /users/
$router = Router::create(['trailingSlash' => 'ignore']);

SPA Catch-All (Vue/React)

// API routes first
$r->group('/api', function ($r) {
    $r->get('/users', [UserController::class, 'index']);
});

// Catch-all for Vue Router (history mode)
$r->get('/{any:any}', [PageController::class, 'index']);

class PageController
{
    public function index($request): ResponseInterface
    {
        return Response::html(file_get_contents('public/index.html'));
    }
}

Quick Boot

// One-liner for simple apps
Router::boot(['debug' => true], __DIR__ . '/routes.php');

Webserver Configuration

Apache (.htaccess)

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [L]

nginx

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Custom Response Formats

The router uses JsonResponder by default. You can swap it for RFC 7807 or custom formats:

use Sodaho\Router\Response;
use Sodaho\Router\Service\RfcResponder;

// RFC 7807 Problem Details format
Response::setResponder(new RfcResponder('https://api.example.com/errors'));

// Error responses now use RFC 7807:
// {
//   "type": "https://api.example.com/errors/not-found",
//   "title": "User not found",
//   "status": 404,
//   "detail": "User with ID 123 not found"
// }

Create your own responder:

use Sodaho\Router\Contract\ResponderInterface;

class XmlResponder implements ResponderInterface
{
    public function formatSuccess(mixed $data, ?string $message = null, ?array $meta = null): array
    {
        // Return array that will be converted to XML
    }

    public function formatError(string $message, ?string $code = null, ?array $details = null): array
    {
        // Return array for error responses
    }

    public function getContentType(): string
    {
        return 'application/xml';  // Used for 4xx/5xx responses
    }

    public function getSuccessContentType(): string
    {
        return 'application/xml';  // Used for 2xx responses
    }
}

Reset in tests:

protected function tearDown(): void
{
    Response::reset(); // Restores default JsonResponder
}

Limitations

What this router does NOT support:

Feature	Reason
Optional segments `[/suffix]`	Complexity vs. benefit. Define two routes instead.
Regex in route patterns	Use predefined patterns or `addPattern()`.
Route priority/ordering	Routes match in definition order. Define specific routes first.
Async/Swoole out-of-box	Use `handle()` method, not `run()`. Emit response yourself.
>500 dynamic routes efficiently	O(n) matching. Consider splitting into microservices.

Workarounds:

// Instead of optional segments:
$r->get('/users', $handler);
$r->get('/users/{id}', $handler);

// Instead of inline regex:
$r->addPattern('date', '\d{4}-\d{2}-\d{2}');
$r->get('/events/{date:date}', $handler);

Performance

Route Caching

Always enable caching in production:

$router = Router::create()
    ->enableCache(__DIR__ . '/../var/cache/routes.php', $_ENV['APP_KEY'])
    ->loadRoutes(__DIR__ . '/routes.php');

Mode	50 Routes	200 Routes
No cache	~2-5ms	~5-15ms
With cache	~0.1ms	~0.2ms

Route Matching Complexity

Route Type	Complexity	Example
Static	O(1)	`/users`, `/api/health`
Dynamic	O(n)	`/users/{id}`, `/posts/{slug}`

Tips:

Static routes are instant (hash lookup)
Dynamic routes loop through candidates
Define most-used routes first
Keep dynamic routes under 500 for best performance

Memory

Route cache uses OPcache (no memory parsing)
~1KB per route in memory
100 routes ≈ 100KB memory footprint

Security Best Practices

Open Redirect Prevention

Never redirect to user input without validation:

// DANGEROUS - Open Redirect vulnerability!
$r->get('/goto', function ($request) {
    $url = $request->getQueryParams()['url'];
    return Response::redirect($url);  // Attacker: ?url=https://evil.com
});

// SAFE - Whitelist or validate
$r->get('/goto', function ($request) {
    $url = $request->getQueryParams()['url'] ?? '/';
    $allowed = ['/', '/dashboard', '/profile'];

    if (!in_array($url, $allowed, true)) {
        return Response::error('Invalid redirect', 400);
    }

    return Response::redirect($url);
});

CSRF Protection

This router does not include CSRF protection. For state-changing operations:

// Option 1: Use a CSRF middleware
$r->middlewareGroup([CsrfMiddleware::class], function ($r) {
    $r->post('/users', [UserController::class, 'store']);
    $r->delete('/users/{id}', [UserController::class, 'destroy']);
});

// Option 2: For SPAs - use SameSite cookies + custom header
// Frontend sends: X-Requested-With: XMLHttpRequest
// Backend validates header presence

Input Validation

Route parameter types ({id:int}) validate format, not business logic:

// {id:int} ensures $id is an integer, but NOT that:
// - The user exists
// - The current user can access it
// - The ID is within valid range

public function show(ServerRequestInterface $request, int $id): ResponseInterface
{
    // Always validate business logic!
    $user = $this->userRepository->find($id);

    if ($user === null) {
        return Response::notFound('User', $id);
    }

    if (!$this->canAccess($request, $user)) {
        return Response::forbidden();
    }

    return Response::success($user);
}

Debug Mode

Never enable debug mode in production:

// Debug mode exposes:
// - Full exception messages
// - Stack traces
// - File paths
// - Internal error details

// .env.production
APP_DEBUG=false
APP_ENV=production

Testing

composer install
vendor/bin/phpunit

Requirements

PHP ^8.2
PSR-7 HTTP Message (nyholm/psr7)
PSR-15 HTTP Handler/Middleware

Acknowledgments

Parts of this project (refactoring, documentation, code review) were developed with AI assistance (Claude).

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.php-cs-fixer.dist.php		.php-cs-fixer.dist.php
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
phpstan.neon		phpstan.neon
phpunit.xml.dist		phpunit.xml.dist

Folders and files

Latest commit

History

Repository files navigation

php-router

Why This Library?

Installation

Quick Start

HTTP Methods

Route Parameters

Available Patterns

Custom Patterns

Accessing Parameters

Route Groups

Middleware

Named Routes & URL Generation

Redirect Routes

Response Helpers

Success Responses

Error Responses

Other Responses

JSON Structure

Configuration

Via Config Array

Via Environment Variables

Via Fluent API

Options

Caching

Hooks (Logging)

PSR-15 Compatibility

Dependency Injection

Exceptions

Trailing Slash Handling

SPA Catch-All (Vue/React)

Quick Boot

Webserver Configuration

Apache (.htaccess)

nginx

Custom Response Formats

Limitations

Performance

Route Caching

Route Matching Complexity

Memory

Security Best Practices

Open Redirect Prevention

CSRF Protection

Input Validation

Debug Mode

Testing

Requirements

Acknowledgments

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Contributors

Uh oh!

Languages