routex-php

Un enrutador HTTP ligero para PHP 8.3+ con una API inspirada en Express.js.

Instalación • Inicio rápido • Rutas • Middleware • Request & Response • Errores • Ejemplos

Características

API estilo Express.js — get(), post(), put(), patch(), delete(), options()
Rutas dinámicas — parámetros :id, :slug, múltiples params por ruta
Grupos de rutas — prefijos compartidos con group()
Middleware — pipeline Chain of Responsibility con use() (global) y ->middleware() (por ruta)
Respuestas fluent — status(), json(), send(), html(), redirect(), header()
Manejo de errores — handlers personalizados para 404, 405 y excepciones globales
Sin dependencias — solo PHP puro, sin frameworks externos

Instalación

composer require chrispo/routex-php

Requisitos: PHP 8.3+

Inicio rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use Chrispo\RouterPhp\Request;
use Chrispo\RouterPhp\Response;
use Chrispo\RouterPhp\Router;

$router = new Router();

$router->get('/', function (Request $req, Response $res): void {
    $res->json(['message' => 'Hello World']);
});

$router->get('/users/:id', function (Request $req, Response $res): void {
    $res->json(['id' => $req->param('id')]);
});

$router->run();

Levantar el servidor:

php -S localhost:8000

Estructura de carpetas recomendada

mi-proyecto/
├── public/
│   └── index.php          # Punto de entrada
├── src/
│   ├── Controllers/       # Lógica de cada recurso
│   │   └── UserController.php
│   ├── Middleware/        # Clases de middleware propias
│   │   ├── AuthMiddleware.php
│   │   └── CorsMiddleware.php
│   └── routes.php         # Definición de todas las rutas
├── vendor/
├── composer.json
└── .env

public/index.php queda limpio:

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use Chrispo\RouterPhp\Router;

$router = new Router();

require_once __DIR__ . '/../src/routes.php';

$router->run();

src/routes.php concentra todas las rutas:

<?php

use Chrispo\RouterPhp\Request;
use Chrispo\RouterPhp\Response;
use App\Controllers\UserController;
use App\Middleware\AuthMiddleware;

$router->use(new CorsMiddleware());

$router->get('/users', [UserController::class, 'index']);
$router->post('/users', [UserController::class, 'store']);

$router->group('/admin', function (Router $r): void {
    $r->use(new AuthMiddleware());
    $r->get('/dashboard', [AdminController::class, 'index']);
});

Rutas

Métodos HTTP

$router->get('/users',       $handler);   // GET
$router->post('/users',      $handler);   // POST
$router->put('/users/:id',   $handler);   // PUT
$router->patch('/users/:id', $handler);   // PATCH
$router->delete('/users/:id',$handler);   // DELETE
$router->options('/users',   $handler);   // OPTIONS

// Registra el mismo handler para todos los métodos
$router->any('/ping', $handler);

Parámetros dinámicos

Usa :nombre para capturar segmentos de la URL:

$router->get('/users/:id', function (Request $req, Response $res): void {
    $id = $req->param('id');           // '42'
    $res->json(['id' => $id]);
});

// Múltiples parámetros
$router->get('/posts/:year/:month/:slug', function (Request $req, Response $res): void {
    $year  = $req->param('year');
    $month = $req->param('month');
    $slug  = $req->param('slug');
});

Query string

// GET /users?page=2&limit=5
$router->get('/users', function (Request $req, Response $res): void {
    $page  = (int) $req->query('page', '1');
    $limit = (int) $req->query('limit', '10');
});

Grupos de rutas

Agrupa rutas bajo un prefijo común. Todos los sub-handlers heredan el prefijo:

$router->group('/api/v1', function (Router $r): void {
    $r->get('/products',     $listHandler);    // GET  /api/v1/products
    $r->post('/products',    $createHandler);  // POST /api/v1/products
    $r->get('/products/:id', $showHandler);    // GET  /api/v1/products/:id
});

Middleware

El middleware sigue el patrón Chain of Responsibility: cada pieza puede modificar la petición/respuesta, llamar a $next para continuar la cadena, o cortarla devolviendo una respuesta directa.

Crear un middleware

Implementa MiddlewareInterface:

<?php

declare(strict_types=1);

use Chrispo\RouterPhp\Middleware\MiddlewareInterface;
use Chrispo\RouterPhp\Request;
use Chrispo\RouterPhp\Response;

final class AuthMiddleware implements MiddlewareInterface
{
    public function handle(Request $request, Response $response, callable $next): void
    {
        $token = $request->header('Authorization');

        if (!str_starts_with($token, 'Bearer ')) {
            // Corta la cadena — el handler de la ruta no se ejecuta
            $response->status(401)->json(['error' => 'Unauthorized']);
            return;
        }

        $next($request, $response); // Continúa hacia el handler
    }
}

Middleware global

Se aplica a todas las rutas del router:

$router->use(new CorsMiddleware(), new LogMiddleware());

Middleware por ruta

Solo se aplica a la ruta específica. Se encadena con ->middleware():

$router->get('/reports', function (Request $req, Response $res): void {
    $res->json(['reports' => []]);
})->middleware(new AuthMiddleware());

Middleware de grupo

Dentro de group(), use() aplica solo a las rutas del grupo:

$router->group('/admin', function (Router $r): void {
    $r->use(new AuthMiddleware()); // Solo rutas /admin/*

    $r->get('/dashboard', $dashboardHandler);
    $r->get('/settings',  $settingsHandler);
});

Orden de ejecución

El pipeline respeta el orden de registro: el primer middleware registrado es el primero en ejecutarse y el último en terminar (outer → inner):

CorsMiddleware::before → AuthMiddleware::before → handler → AuthMiddleware::after → CorsMiddleware::after

Request & Response

Request — métodos disponibles

Método	Descripción	Ejemplo
`param('key')`	Parámetro dinámico de ruta	`$req->param('id')` → `'42'`
`query('key', $default)`	Valor de query string	`$req->query('page', '1')`
`body('key', $default)`	Campo del body JSON o POST	`$req->body('email')`
`body()`	Todo el body como array	`$req->body()`
`header('Name')`	Cabecera HTTP	`$req->header('Authorization')`
`all()`	Body + query + params fusionados	`$req->all()`
`rawBody()`	Body sin parsear (webhooks)	`$req->rawBody()`
`ip()`	IP del cliente	`$req->ip()`
`isJson()`	Content-Type es application/json	`$req->isJson()`
`isXhr()`	Petición AJAX	`$req->isXhr()`
`getMethod()`	Método HTTP	`$req->getMethod()` → `'GET'`
`getPath()`	Path sin query string	`$req->getPath()` → `'/users/42'`

Response — métodos disponibles

Método	Descripción	Ejemplo
`json($data)`	Serializa a JSON y envía	`$res->json(['id' => 1])`
`send($body)`	Envía texto plano	`$res->send('pong')`
`html($content)`	Envía HTML	`$res->html('<h1>Hello</h1>')`
`redirect($url, $code)`	Redirige (302 por defecto)	`$res->redirect('/login')`
`status($code)`	Establece el código HTTP	`$res->status(201)->json(...)`
`header($name, $value)`	Añade cabecera HTTP	`$res->header('X-Token', 'abc')`
`withHeaders($array)`	Añade múltiples cabeceras	`$res->withHeaders([...])`

Los métodos status() y header() son fluent (retornan $this) y pueden encadenarse:

$res->status(201)
    ->header('X-Request-Id', uniqid())
    ->json(['created' => true]);

Manejo de errores

404 — ruta no encontrada

$router->notFound(function (Request $req, Response $res): void {
    $res->status(404)->json([
        'error'   => 'Not Found',
        'message' => sprintf('"%s %s" no existe', $req->getMethod(), $req->getPath()),
    ]);
});

405 — método no permitido

La excepción incluye los métodos permitidos para esa ruta:

use Chrispo\RouterPhp\Exceptions\MethodNotAllowedException;

$router->methodNotAllowed(function (MethodNotAllowedException $e, Request $req, Response $res): void {
    $res->status(405)
        ->header('Allow', implode(', ', $e->getAllowedMethods()))
        ->json([
            'error'   => 'Method Not Allowed',
            'allowed' => $e->getAllowedMethods(),
        ]);
});

Errores globales

Captura cualquier excepción no controlada lanzada dentro de un handler:

$router->onError(function (\Throwable $e, Request $req, Response $res): void {
    $res->status(500)->json([
        'error'   => 'Internal Server Error',
        'message' => $e->getMessage(),
    ]);
});

Ejemplos completos

El archivo index.php en la raíz del repositorio contiene ejemplos listos para ejecutar de todo lo anterior:

Sección	Qué demuestra
`GET /`	Respuesta JSON básica
`GET /ping`	Healthcheck con texto plano
`GET /users`	Lista con paginación via query string
`POST /users`	Creación con validación de body JSON
`GET /users/:id`	Parámetro dinámico
`PUT /users/:id`	Reemplazar recurso
`PATCH /users/:id`	Actualización parcial
`DELETE /users/:id`	Eliminar recurso (204 sin body)
`GET /api/v1/products`	Grupo con prefijo `/api/v1`
`GET /posts/:year/:month/:slug`	Tres parámetros en una sola ruta
`GET /admin/dashboard`	Grupo protegido con `AuthMiddleware`
`GET /reports`	Middleware por ruta individual
`GET /go`	Redirección 301
Custom 404 / 405 / error	Handlers personalizados de error

Para ejecutarlo:

php -S localhost:8000

# Rutas básicas
curl http://localhost:8000/
curl http://localhost:8000/ping
curl "http://localhost:8000/users?page=2&limit=5"
curl http://localhost:8000/users/42

# Crear usuario
curl -X POST http://localhost:8000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}'

# Ruta protegida — sin token retorna 401
curl http://localhost:8000/admin/dashboard

# Ruta protegida — con token retorna 200
curl -H "Authorization: Bearer secret" http://localhost:8000/admin/dashboard

Tests

El proyecto incluye 91 tests con Pest:

php vendor/bin/pest

Benchmarks

Mediciones de rendimiento con PHPBench:

php vendor/bin/phpbench run benchmarks/ --report=aggregate

Resultados de referencia (PHP 8.5, sin opcache):

Benchmark	Tiempo	Descripción
Ruta estática	~2 µs	Caso base
Ruta dinámica	~2.5 µs	+25% por regex
50 rutas registradas	~17 µs	O(n) lineal
Con 3 middlewares	~3 µs	+45% overhead pipeline
Sin middlewares	~2 µs	Baseline
Ruta no encontrada	~1.5 µs	Loop + excepción

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
benchmarks		benchmarks
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
composer.json		composer.json
composer.lock		composer.lock
index.php		index.php
phpbench.json		phpbench.json
phpunit.xml		phpunit.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

routex-php

Características

Instalación

Inicio rápido

Estructura de carpetas recomendada

Rutas

Métodos HTTP

Parámetros dinámicos

Query string

Grupos de rutas

Middleware

Crear un middleware

Middleware global

Middleware por ruta

Middleware de grupo

Orden de ejecución

Request & Response

Request — métodos disponibles

Response — métodos disponibles

Manejo de errores

404 — ruta no encontrada

405 — método no permitido

Errores globales

Ejemplos completos

Tests

Benchmarks

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

routex-php

Características

Instalación

Inicio rápido

Estructura de carpetas recomendada

Rutas

Métodos HTTP

Parámetros dinámicos

Query string

Grupos de rutas

Middleware

Crear un middleware

Middleware global

Middleware por ruta

Middleware de grupo

Orden de ejecución

Request & Response

Request — métodos disponibles

Response — métodos disponibles

Manejo de errores

404 — ruta no encontrada

405 — método no permitido

Errores globales

Ejemplos completos

Tests

Benchmarks

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages