README

A fast, simple HTTP router for the Lighthouse framework.

Installation

composer require lighthouse/router

Requirements

PHP 8.2 or higher

Features

Simple, expressive API
Route parameters with {param} syntax
Route groups with prefixes
Named routes for URL generation
Method-specific routing (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)
PSR-7 request support

Quick Start

Basic Routing

use Lighthouse\Router\Router;

$router = new Router();

// Register routes
$router->get('/users', 'UsersController@index');
$router->post('/users', 'UsersController@store');
$router->get('/users/{id}', 'UsersController@show');
$router->put('/users/{id}', 'UsersController@update');
$router->delete('/users/{id}', 'UsersController@destroy');

Route Parameters

Parameters are defined with curly braces and automatically extracted:

$router->get('/users/{id}', function ($id) {
    return "User: {$id}";
});

$router->get('/posts/{postId}/comments/{commentId}', function ($postId, $commentId) {
    return "Post {$postId}, Comment {$commentId}";
});

// Match the route
$match = $router->matchRoute('GET', '/users/123');
$match->getParameter('id'); // "123"
$match->getParameters();    // ['id' => '123']

Route Groups

Group routes with a common prefix:

$router->group('/api', function (Router $router) {
    $router->get('/users', 'ApiUsersController@index');
    $router->get('/posts', 'ApiPostsController@index');
});

// Creates:
// GET /api/users
// GET /api/posts

Nested groups:

$router->group('/api', function (Router $router) {
    $router->group('/v1', function (Router $router) {
        $router->get('/users', 'handler');
    });
    
    $router->group('/v2', function (Router $router) {
        $router->get('/users', 'handler');
    });
});

// Creates:
// GET /api/v1/users
// GET /api/v2/users

Named Routes

Name routes for URL generation:

$router->get('/users', 'handler')->name('users.index');
$router->get('/users/{id}', 'handler')->name('users.show');
$router->get('/users/{id}/posts/{postId}', 'handler')->name('users.posts.show');

// Generate URLs
$router->url('users.index');                           // /users
$router->url('users.show', ['id' => 123]);             // /users/123
$router->url('users.posts.show', ['id' => 1, 'postId' => 42]); // /users/1/posts/42

Multiple Methods

// Match specific methods
$router->match(['GET', 'POST'], '/form', 'FormController@handle');

// Match all methods
$router->any('/api', 'ApiController@handle');

Dispatching Requests

With PSR-7 request:

use Lighthouse\Router\Exception\RouteNotFoundException;
use Lighthouse\Router\Exception\MethodNotAllowedException;

try {
    $match = $router->dispatch($request);
    
    $handler = $match->getHandler();
    $params = $match->getParameters();
    
    // Call your handler with parameters
} catch (RouteNotFoundException $e) {
    // 404 - Route not found
} catch (MethodNotAllowedException $e) {
    // 405 - Method not allowed
    $allowedMethods = $e->getAllowedMethods();
}

Or directly with method and path:

$match = $router->matchRoute('GET', '/users/123');

Exception Handling

RouteNotFoundException

Thrown when no route matches the request path:

catch (RouteNotFoundException $e) {
    $e->getMethod(); // "GET"
    $e->getPath();   // "/unknown"
}

MethodNotAllowedException

Thrown when the path matches but the HTTP method doesn't:

catch (MethodNotAllowedException $e) {
    $e->getMethod();         // "DELETE"
    $e->getAllowedMethods(); // ["GET", "POST"]
}

API Reference

Router

Method	Description
`get(string $path, mixed $handler)`	Register GET route
`post(string $path, mixed $handler)`	Register POST route
`put(string $path, mixed $handler)`	Register PUT route
`patch(string $path, mixed $handler)`	Register PATCH route
`delete(string $path, mixed $handler)`	Register DELETE route
`options(string $path, mixed $handler)`	Register OPTIONS route
`head(string $path, mixed $handler)`	Register HEAD route
`any(string $path, mixed $handler)`	Register route for all methods
`match(array $methods, string $path, mixed $handler)`	Register route for specific methods
`group(string $prefix, callable $callback)`	Create route group
`dispatch(ServerRequestInterface $request)`	Match PSR-7 request
`matchRoute(string $method, string $path)`	Match method and path
`url(string $name, array $params)`	Generate URL for named route
`getRoutes()`	Get all registered routes
`clear()`	Remove all routes

Route

Method	Description
`getMethod()`	Get HTTP method
`getPath()`	Get route path
`getHandler()`	Get route handler
`getName()`	Get route name
`name(string $name)`	Set route name
`getParameters()`	Get extracted parameters
`matches(string $method, string $path)`	Check if route matches
`generateUrl(array $params)`	Generate URL with parameters

RouteMatch

Method	Description
`getRoute()`	Get matched route
`getHandler()`	Get route handler
`getParameters()`	Get all parameters
`getParameter(string $name, ?string $default)`	Get single parameter

Testing

composer test

License

MIT License. See LICENSE for details.

Part of the Lighthouse Framework

This package is part of the Lighthouse Framework, an educational PHP framework designed to teach how modern frameworks work internally.

lighthouse / router

Maintainers

Details