marrios / mareaturborouter
Route manager
Requires
- php: >=8.0
Requires (Dev)
- mockery/mockery: ^1.6
- pestphp/pest: ^2.23
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-12 14:40:36 UTC
README
A tiny, zero-dependency HTTP router for PHP 8.1+. Routes are declared with PHP attributes right on your controller methods: no route files, no config.
#[Route("/users/{id}", "GET")] public function show($request) { ... }
Created by @marriosdev.
Contents
- Installation
- Quick start
- Web server setup
- Defining routes
- Reading parameters
- Dependency injection
- Middleware
- CLI mode
- How matching works
- Running the tests
Installation
composer require marrios/mareaturborouter
Requires PHP 8.1 or newer.
Quick start
Create index.php:
<?php require_once "vendor/autoload.php"; use MareaTurbo\Router; use MareaTurbo\Route; class PostController { #[Route("/posts/{id}", "GET")] public function show($request) { echo "Post " . $request->only(["id"])["id"]; } } (new Router())->controllers([ PostController::class, ]);
Run it with PHP's built-in server:
php -S localhost:8000 index.php
Open http://localhost:8000/posts/123 and you'll see Post 123.
Web server setup
Every request has to reach index.php. The built-in server above already does that. In production:
Apache (.htaccess next to index.php):
RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^ index.php [QSA,L]
Nginx:
location / { try_files $uri $uri/ /index.php?$query_string; }
Defining routes
#[Route(string $path, string $method, string $name = '')]
| Argument | Description |
|---|---|
$path |
URL path. Segments wrapped in {} are dynamic parameters. |
$method |
GET, POST, PUT, PATCH, DELETE, OPTIONS or HEAD (case-insensitive). Anything else throws MareaTurboException. |
$name |
Optional label for the route (informational for now). |
A method can carry several routes:
class UserController { #[Route("/users", "GET")] public function index($request) { ... } #[Route("/users", "POST")] public function store($request) { ... } #[Route("/users/{id}", "PUT")] #[Route("/users/{id}", "PATCH")] public function update($request) { ... } #[Route("/categories/{category}/posts/{post}", "GET")] public function postInCategory($request) { ... } }
Register every controller with the router:
(new Router())->controllers([ UserController::class, PostController::class, ]);
Reading parameters
Every route method gets a MareaTurbo\Request argument:
#[Route("/categories/{category}/posts/{post}", "GET")] public function show($request) { $request->all(); // ["category" => "10", "post" => "5"] $request->only(["post"]); // ["post" => "5"] }
- Values are URL-decoded (
/users/jo%C3%A3ogivesjoão). - Values are escaped with
htmlspecialcharsandaddslashes, so treat them as strings. Requestonly holds path parameters. Read the query string and body the usual way ($_GET,$_POST,file_get_contents('php://input')).
Dependency injection
Controller constructors get their dependencies automatically, recursively:
class UserRepository { public function __construct(private Database $db) {} } class UserController { public function __construct(private UserRepository $users, private int $perPage = 20) {} #[Route("/users", "GET")] public function index($request) { ... } }
How each constructor parameter gets its value:
- A class type → built recursively.
- Otherwise, its default value.
- Otherwise,
nullif it's nullable or has no type. - Otherwise →
MareaTurboException("Cannot resolve dependency $param of Class").
Interfaces can't be resolved. Type-hint concrete classes.
Middleware
A middleware is any class with a handle(): bool method. Return false to stop the request with the given HTTP status code:
class AuthMiddleware { public function handle(): bool { return isset($_SERVER['HTTP_AUTHORIZATION']); } } (new Router()) ->middleware(AuthMiddleware::class, 401) ->controllers([UserController::class]);
Call
middleware()beforecontrollers().controllers()dispatches the request and ends the script, so nothing chained after it runs. Middleware applies to every controller registered on that router.
CLI mode
Routes can be called from the terminal, which is handy for scripts and debugging:
php index.php GET /posts/123
How matching works
- Controllers are checked in the order you register them, then their public methods in order. The first match wins, its method runs, and the script ends.
- Leading and trailing slashes are ignored:
/posts/1,posts/1and/posts/1/are the same. - The query string is ignored when matching:
/posts/1?page=2matches/posts/{id}. - Without a match, the response status is
404and nothing is printed. Print your own "not found" page aftercontrollers():
(new Router())->controllers([...]); echo "Page not found"; // only reached when no route matched
Running the tests
composer install vendor/bin/pest