Router Class Documentation

Namespace: TrishulApi\Core\Http
Author: Shyam Dubey
Since: v1.0.0
Version: v1.0.0

The Router class is the core of the Trishul API framework's routing system. It allows you to define HTTP routes, group them, apply middlewares, and control the request/response lifecycle in a structured and extensible way.

Key Features

Method Reference

static get($url, $callback, $middlewares = [], ...)

Registers a GET route.
Usage: Handles HTTP GET requests at the specified URL, calling the provided controller or service method.
Parameters:
Returns: array (route definition)

static post($url, $callback, $middlewares = [], ...)

Registers a POST route.
Usage: Handles HTTP POST requests.
Parameters: Same as get().
Returns: array

static put($url, $callback, $middlewares = [], ...)

Registers a PUT route.
Usage: Handles HTTP PUT requests.
Parameters: Same as get().
Returns: array

static delete($url, $callback, $middlewares = [], ...)

Registers a DELETE route.
Usage: Handles HTTP DELETE requests.
Parameters: Same as get().
Returns: array

static merge($url, $callback, $middlewares = [], ...)

Registers a MERGE route.
Usage: Handles HTTP MERGE requests (custom method).
Parameters: Same as get().
Returns: array

static parent($url, array $childrens, $middlewares = [], $except=[]): void

Groups multiple routes under a parent URL and applies middlewares to all or selected children.
Usage: Useful for organizing related endpoints (e.g., all user-related routes under /users).

static children($method, $url, $callback, ...)

Helper to define a child route for use with parent().
Returns: array

static include($routes)

Includes routes from another file or array.

static set_global_middlewares($middlewares, $except = [])

Sets global middlewares for all routes, with optional exceptions.
Usage: Ensures certain middlewares (e.g., authentication, logging) run on every request unless explicitly exempted.

static init()

Initializes the router, matches the incoming request to a route, and dispatches it.
Call this once in your entrypoint (e.g., index.php) after defining all routes.

static get_routes()

Returns all registered routes as an array.
Returns: array

Detailed Example

Basic Usage: 
use TrishulApi\Core\Http\Router;
use App\Controller\UserController;
use App\Middleware\AuthMiddleware;

// Register a GET route
Router::get("/user/{id}", UserController::class . "@getUser", [AuthMiddleware::class], "Get user", "Returns user by ID");

// Register a POST route
Router::post("/user", UserController::class . "@createUser", [AuthMiddleware::class], "Create user", "Creates a new user");

// Register a DELETE route
Router::delete("/user/{id}", UserController::class . "@deleteUser", [AuthMiddleware::class]);

// Register a PUT route
Router::put("/user/{id}", UserController::class . "@updateUser", [AuthMiddleware::class]);

// Set global middlewares (applies to all routes except login/register)
Router::set_global_middlewares(
    [AuthMiddleware::class, 'LoggingMiddleware'],
    ["/login" => "POST", "/register" => "POST"]
);

// Grouping routes under a parent
Router::parent("/users", [
    Router::children("GET", "/all", UserController::class . "@getAllUsers"),
    Router::children("POST", "/add", UserController::class . "@addUser")
], [AuthMiddleware::class], ["/users/all" => "GET"]);

// Initialize the router (should be called once, after all routes are defined)
Router::init();

Route Parameters

You can define dynamic segments in your route URLs using curly braces, e.g. /user/{id}. These will be passed as parameters to your controller method.

Middlewares

Swagger/OpenAPI Support

Each route registration method accepts parameters for summary, description, response codes, tags, and more, which are used to generate Swagger documentation automatically.

Error Handling

Best Practices