fatjon-lleshi/antares-router

Lightweight attribute-based router for PHP 8.2+

v0.1.4 2026-04-24 23:32 UTC

Requires

• php: >=8.2
• nikic/fast-route: ^1.3

Requires (Dev)

• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0

Suggests

• symfony/yaml: Required for YAML route configuration (^6.0)

MIT

• Fatjon-Lleshi

• routing
• php
• http
• rest
• router
• attributes

README

Lightweight attribute-based router for PHP 8.2+. Built on top of nikic/fast-route. Can be used standalone or as part of the Antares framework.

Installation

composer require fatjon-lleshi/antares-router

Standalone Usage

Example Project Structure

project/
├── public/
│   └── index.php
├── app/
│   └── Controllers/
│       ├── UserController.php
│       └── ProductController.php
├── routes.php
└── composer.json

Defining Routes

Define routes directly on controller methods using PHP attributes:

use Antares\Router\Attributes\Get;
use Antares\Router\Attributes\Post;
use Antares\Router\Attributes\Put;
use Antares\Router\Attributes\Patch;
use Antares\Router\Attributes\Delete;

class UserController
{
    #[Get('/users')]
    public function index(): void {}

    #[Get('/users/{id}')]
    public function show(): void {}

    #[Post('/users', 201)]
    public function store(): void {}

    #[Put('/users/{id}')]
    public function update(): void {}

    #[Patch('/users/{id}')]
    public function edit(): void {}

    #[Delete('/users/{id}', 204)]
    public function destroy(): void {}
}

Registering Routes

Create a routes.php file that registers all your controllers:

use Antares\Router\Router;

return function(Router $router): void {
    $router->register(UserController::class);
    $router->register(ProductController::class);
    $router->register(OrderController::class);
};

Bootstrapping

In public/index.php, create the router, load the routes file, and dispatch the request:

use Antares\Router\Router;

$router = new Router();
$register = require __DIR__ . '/../routes.php';
$register($router);

try {
    [$controllerClass, $method, $routeParams, $statusCode] = $router->match(
        $_SERVER['REQUEST_METHOD'],
        parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH)
    );

    $controller = new $controllerClass();
    $controller->$method();
} catch (\RuntimeException $e) {
    http_response_code($e->getCode());
    echo json_encode(['error' => $e->getMessage()]);
}

Route Parameters

Parameters in the path are extracted and returned as an array:

[$controller, $method, $params, $status] = $router->match('GET', '/users/42');

echo $params['id']; // "42"

Custom Status Codes

Pass a status code as the second argument to any route attribute. Defaults to 200:

#[Post('/users', 201)]
public function store(): void {}

#[Delete('/users/{id}', 204)]
public function destroy(): void {}

Array Config

Register routes from a plain array if you prefer config-based routing instead of attributes:

$router->registerFromConfig([
    ['GET',    '/users',      UserController::class, 'index',   200],
    ['POST',   '/users',      UserController::class, 'store',   201],
    ['GET',    '/users/{id}', UserController::class, 'show',    200],
    ['PUT',    '/users/{id}', UserController::class, 'update',  200],
    ['DELETE', '/users/{id}', UserController::class, 'destroy', 204],
]);

YAML Config

Register routes from a YAML file. Requires symfony/yaml:

composer require symfony/yaml

routes:
  - method: GET
    path: /users
    controller: App\Controllers\UserController
    action: index
    status: 200
  - method: POST
    path: /users
    controller: App\Controllers\UserController
    action: store
    status: 201

$router->registerFromYaml(__DIR__ . '/../routes.yaml');

Route Caching

Cache compiled routes for production to avoid reflection overhead on every request:

$cachePath = __DIR__ . '/../storage/cache/routes.php';

if (file_exists($cachePath)) {
    $router->loadFromCache($cachePath);
} else {
    $register = require __DIR__ . '/../routes.php';
    $register($router);
    $router->saveToCache($cachePath);
}

Error Handling

match() throws a RuntimeException when a route is not found or the method is not allowed:

try {
    [$controller, $method, $params, $status] = $router->match('GET', '/not-found');
} catch (\RuntimeException $e) {
    $e->getCode(); // 404 = not found, 405 = method not allowed
}

Available Attributes

Attribute	HTTP Method
#[Get]	GET
#[Post]	POST
#[Put]	PUT
#[Patch]	PATCH
#[Delete]	DELETE

Requirements

• PHP 8.2+
• nikic/fast-route ^1.3

License

MIT