Waypoint

Lightweight PSR-15 PHP Router with Attribute Routing, Prefix-Trie Matching & Middleware Pipeline.

Get Started Русский View on GitHub

---

What is Waypoint?

Waypoint is a modern, lightweight PSR-15 compatible PHP router for PHP 8.4+. It combines attribute-based routing, a fast prefix-trie matching engine, and a PSR-15 middleware pipeline into a single, elegant package.

Key Highlights

• Zero required dependencies — the core matching engine (route registration, compilation, trie matching, URL generation, diagnostics) works as pure PHP; PSR packages are optional
• PSR-15 compliant — implements RequestHandlerInterface, works with any PSR-7 / PSR-15 stack
• Attribute-based routing — declare routes with PHP 8 #[Route] attributes directly on controllers
• Fast prefix-trie matching — static segments resolved via O(1) hash-map lookups; dynamic segments tested only when necessary
• Middleware pipeline — global and per-route PSR-15 middleware with FIFO execution
• Route groups — shared path prefixes and middleware for related routes
• Route caching — compile routes to a PHP file for OPcache-friendly production loading
• Automatic dependency injection — route parameters, ServerRequestInterface, and container services injected into controller methods
• URL generation — reverse routing from named routes and parameters
• Route diagnostics — detect duplicate paths, duplicate names, and shadowed routes
• Priority-based matching — control which route wins when patterns overlap
• Clean architecture — separate RouteRegistrar for route building and Router for PSR-15 dispatching

---

Quick Example

use AsceticSoft\Waypoint\RouteRegistrar;
use AsceticSoft\Waypoint\Router;
use Nyholm\Psr7\ServerRequest;

// 1. Register routes
$registrar = new RouteRegistrar();
$registrar->get('/hello/{name}', function (string $name) use ($responseFactory) {
    $response = $responseFactory->createResponse();
    $response->getBody()->write("Hello, {$name}!");
    return $response;
});

// 2. Create the router and handle requests
$router  = new Router($container, $registrar->getRouteCollection());
$request = new ServerRequest('GET', '/hello/world');
$response = $router->handle($request);

A few lines to get a fully working router with parameter injection. No XML, no YAML, no boilerplate.

---

Why Waypoint?

Feature	Waypoint	Other routers
PSR-15 RequestHandlerInterface	Yes	Not always
PHP 8 #[Route] attributes	Yes	Some
Prefix-trie O(1) matching	Yes	Linear scan
Per-route middleware	Yes	Some
Route caching (OPcache)	Yes	Some
Auto dependency injection	Yes	Rare
Route diagnostics	Yes	No
Zero required dependencies	Pure PHP core, PSR optional	Often many
PHPStan Level 9	Yes	Varies

---

Requirements

• PHP >= 8.4
• ext-mbstring

Installation

composer require ascetic-soft/waypoint

For PSR-15 request handling, also install the PSR packages:

composer require psr/http-message psr/http-server-handler psr/http-server-middleware psr/container

---

Documentation

Getting Started

Installation, quick start, and basic usage in 5 minutes.

Routing

Route registration, parameters, groups, and attribute-based routing.

Middleware

Global and per-route PSR-15 middleware pipeline.

Advanced

Dependency injection, URL generation, route caching, and diagnostics.

API Reference

Complete reference for all public classes and methods.

Internals

Algorithms, data structures, and diagrams of the internal architecture.