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

Route

RouteMatch

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.