monkeyscloud / monkeyslegion-router
Attribute- and DSL-based HTTP router for MonkeysLegion
Requires
- php: ^8.4
- monkeyscloud/monkeyslegion-http: ^1.0
- psr/http-message: ^2.0
This package is auto-updated.
Last update: 2025-05-23 23:16:29 UTC
README
The MonkeysLegion Router provides an easy, attribute-based way to define and register HTTP routes in your application. It powers both request dispatching and live OpenAPI documentation.
✨ Key Features
- Attribute‑driven route definitions (
#[Route]
) on controller methods - Multi‑verb support: define one or more HTTP methods per route
- Auto‑scan controllers for routes at boot (no manual route lists)
- Imperative API for dynamic routes via
$router->add()
- Exposes a
RouteCollection
iterable for downstream consumers (dispatch, docs, CLI) - Seamlessly integrates with the OpenAPI generator and
route:list
CLI
📦 Installation
Require the router component (if separated), or ensure your skeleton has it installed:
composer require monkeyscloud/monkeyslegion-router:^1.0@dev
Make sure your composer.json
includes:
{ "autoload": { "psr-4": { "MonkeysLegion\\Router\\": "src/Router/" } } }
Then run:
composer dump-autoload
🚦 Defining Routes with Attributes
Use the #[Route]
attribute on public controller methods to declare routes:
namespace App\Controller; use MonkeysLegion\Router\Attributes\Route; use Psr\Http\Message\ResponseInterface; final class UserController { #[Route('GET', '/users', summary: 'List users', tags: ['User'])] public function index(): ResponseInterface { /* … */ } #[Route(['GET','POST'], '/users', name: 'user_create')] public function create(): ResponseInterface { /* … */ } #[Route('DELETE', '/users/{id}', summary: 'Remove a user')] public function delete(string $id): ResponseInterface { /* … */ } }
Parameter | Type | Description |
---|---|---|
methods |
string |string[] |
HTTP verb(s) to match ("GET" or [ "GET","POST"] ). |
path |
string |
URI template with {parameter} syntax. Leading slash added automatically. |
name |
string |
Optional route name / OpenAPI operationId . Auto-generated if omitted. |
summary |
string |
One-line description for docs. |
tags |
string[] |
Grouping tags for OpenAPI / Swagger UI. |
🧩 Imperative Routes
For dynamic or non-controller routes, call:
$router->add( methods: ['GET'], path: '/healthz', handler: [HealthController::class, 'probe'], name: 'health_check', summary: 'Kubernetes health endpoint', tags: ['Ops'] );
This merges seamlessly into the same RouteCollection
used for dispatch and docs.
⚙️ Container Integration
Register the router services in your DI config (config/app.php
):
use MonkeysLegion\Router\{RouteCollection, Router}; RouteCollection::class => fn() => new RouteCollection(), Router::class => fn($c) => new Router( $c->get(RouteCollection::class), $c ),
In your bootstrap (e.g. RouteLoader
), scan controllers:
$router = $container->get(Router::class); $router->registerController(App\Controller\UserController::class); // …repeat for each controller namespace…
Downstream, inject RouteCollection
or Router
into middleware, CLI, or OpenAPI generator.
📝 Available Classes
MonkeysLegion\Router\Attributes\Route
– the PHP attribute for routesMonkeysLegion\Router\Route
– value object representing one route (methods, path, handler, metadata)MonkeysLegion\Router\RouteCollection
– iterable collection ofRoute
objectsMonkeysLegion\Router\Router
– scanner & registrar of attribute routes; also supportsadd()
🔧 CLI Commands
Once registered with your CliKernel
, use:
php vendor/bin/ml route:list # Display a table of all routes php vendor/bin/ml openapi:export # Export OpenAPI spec from RouteCollection
🛠️ Extending
- Path parameters: future support for parameter-level metadata (e.g. regex constraints).
- Versioning: add
version
orprefix
options on the attribute or inRouter
. - Middleware per-route: store and apply route-specific middleware stacks.
Contributions welcome! Please submit issues or PRs on the GitHub repository.
📄 License
Released under the MIT License © 2025 MonkeysCloud