PHP Luminova: Routing for HTTP Controllers

The HTTP Routing documentation focuses exclusively on HTTP controllers routing, designed for handling API and Web requests. Each controller method is mapped to an HTTP verb (e.g., GET, POST, PUT, DELETE), making route definitions clean, predictable, and easy to maintain. This structure ensures every request type is clearly defined in your controller.

Response Content Caching

Luminova supports template content caching to speed up responses and reduce server load by serving pre-rendered pages instead of regenerating them for every request.

It also offers version-based caching, which is useful for applications like a documentation or multi-version sites. For example:

https://example.com/1.1.0/about

will load content from the cache for version 1.1.0, if available.

Learn how to enable and configure view caching in the View Caching Guide.

Usages

Controller Method Handlers

When defining route handlers, you can use either a Closure or a string reference pointing to a controller method. Luminova supports:

• Static-style references (ControllerName::method)
• Notation-style references (ControllerName@method)

You don’t need to type the full namespace — just the controller’s base name and method.The routing system automatically resolves the full namespace from the registered controller list.

Note:In your /routes/<context>.php file, the objectsLuminova\Routing\Router $router and App\Application $app are automatically available.This means you don’t need to import them using use unless required (for example, when using bind() ).

Examples

Static-style reference

// /routes/web.php

$router->get('/home', 'HomeController::index');

Notation-style reference

// /routes/web.php

$router->get('/home', 'HomeController@index');

Closure handler

// /routes/web.php

$router->get('/home', function () {
    // Handle request logic here
});

Rendering a template from a Closure

// /routes/web.php

$router->get('/', function (Application $app) {
    return $app->view('index')->render([
        'foo' => 'Bar' // Variables passed to the view
    ]);
});

Bind Group

If you need to register a URI group for routing, you can use bind method which accepts only 2 arguments group pattern and Closure.

// /routes/web.php

use Luminova\Routing\Router;
use Luminova\Foundation\CoreApplication;

$router->bind('/blog/(:root)', function(Router $router, CoreApplication $app) {
   $router->middleware('GET', '/(:root)', 'Authentication::isAllowed');
   $router->get('/', 'ExampleController::blogs');
   $router->get('/(:alphanumeric)', 'ExampleController::blog');
});

See for more information related to Dynamic URI Placeholders documentation.

Any HTTP Method

The any method lets you handle requests regardless of whether they’re GET, POST, PUT, or any other HTTP verb. This is useful for pages like Contact Us where you want one handler for all request types, or when debugging routes.

Example using any:

// /routes/web.php

$router->any('/contact', 'ExampleController::contact');

You can achieve the same result with the capture method using Router::ANY_METHODS or simply "ANY":

// /routes/web.php

$router->capture('ANY', '/contact', 'ExampleController::contact');

You can also use capture to handle only specific methods in a single route:

// /routes/web.php

$router->capture('POST|GET|PUT', '/contact', 'ExampleController::contact');

Dependency Injection

Luminova routing can automatically inject dependencies into controller methods or route callbacks. Just type-hint the class you need, and the framework will provide it for you.

Example using a controller method:

// /app/Controllers/Http/ExampleController.php

namespace App\Controllers\Http;

use Luminova\Base\BaseController;
use Luminova\Http\Request;

class ExampleController extends BaseController
{
    public function userInfo(Request $request): int 
    {
        $name = $request->getGet('name');
        // Your logic here
    }
}

Example using a closure callback:

// /routes/web.php

use Luminova\Http\Request;

$router->get('/users', function (Request $request) {
    $name = $request->getGet('name');
    // Your logic here
});

In both cases, the Request object is injected automatically, so you can access query parameters, POST data, and more without manually creating it.

Class Definition

• Class namespace: \Luminova\Routing\Router
• This class implements: Luminova\Interface\RouterInterface
• This class is marked as final and can't be subclassed

Methods

get

Get, a shorthand for route capture method to handle GET request method.

public get(string $pattern, Closure|string $callback): void

Parameters:

post

Post, a shorthand for route capture method to handle POST request method.

public post(string $pattern, Closure|string $callback): void

Parameters:

patch

Patch, a shorthand for route capture method to handle PATCH request method.

public patch(string $pattern, Closure|string $callback): void

Parameters:

delete

Delete, a shorthand for route capture method to handle DELETE request method.

public delete(string $pattern, Closure|string $callback): void

Parameters:

put

Put, a shorthand for route capture method to handle PUT request method.

public put(string $pattern, Closure|string $callback): void

Parameters:

options

Options, a shorthand for route capture method to handle OPTIONS request method.

public options(string $pattern, Closure|string $callback): void

Parameters:

middleware

Registers an HTTP before middleware to authenticate requests before handling controllers.

This method allows you to apply middleware security logic that executes prior to any associated HTTP controllers. If the middleware callback returns STATUS_ERROR, the routing process will terminate, preventing further execution.

Middlewares can be registered within a bind method for a specific URI prefix or in the global scope of the routing context. It also support defining regular expression patterns and methods to match before executing.

public middleware(string $methods, string $pattern, Closure|string $callback): void

Parameters:

Throws:

• Luminova\Exceptions\RouterException - Thrown if the method is called in non-HTTP context or the $methods parameter is empty.

after

Registers an HTTP after middleware to execute logic after a controller has been handled.

This method applies middleware logic that runs after a controller processes a request. It is typically used for tasks such as cleanup or additional post-processing.

public after(string $methods, string $pattern, Closure|string $callback): void

Parameters:

Throws:

• Luminova\Exceptions\RouterException - Thrown if the $methods parameter is empty.

Note: This method can only be used on HTTP request routing, it not allowed in CLI mode.

capture

Registers HTTP request methods, URI patterns, and corresponding callback or controller methods.

This method allows you to define routes by specifying supported HTTP methods, a URL pattern, and the callback or controller method to execute when the pattern matches a client request. Multiple HTTP methods can be specified using the pipe (|) symbol.

public capture(string $methods, string $pattern, Closure|string $callback): void

Parameters:

Throws:

• Luminova\Exceptions\RouterException - Thrown if an empty method string is provided.

any

Capture and handle requests for any HTTP method.

This method leverages Router::ANY_METHODS to match and handle requests for any HTTP method. It is a convenient way to define routes that respond to all HTTP methods without explicitly specifying them.

public any(string $pattern, Closure|string $callback): void

Parameters:

bind

Groups related routes under a specified URI prefix.

The bind method simplifies route organization by associating a group of routes with a common base path or pattern. It allows you to define and manage multiple nested URI patterns under a shared prefix, enhancing the clarity and maintainability of your routing structure. Additionally, middleware can be applied within the scope of the defined closure, enabling advanced route-specific logic.

public bind(string $prefix, Closure $callback): void

Parameters:

Example:

Using bind to group routes under a /blog prefix:

$router->bind('/blog/', static function (Router $router) {
   $router->get('/', 'BlogController::listBlogs');                   // Matches '/blog/'
   $router->get('/([a-zA-Z0-9-]+)', 'BlogController::readBlog');     // Matches '/blog/{slug}'
   $router->get('/edit/([a-zA-Z0-9-]+)', 'BlogController::editBlog'); // Matches '/blog/edit/{slug}'
});

Explanation:

When you group routes using bind, the specified prefix (e.g., /blog) is prepended to all routes defined within the closure. For example:

• http://example.com/blog/ maps to listBlogs.
• http://example.com/blog/{slug} maps to readBlog.
• http://example.com/blog/edit/{slug} maps to editBlog.

This approach keeps route definitions organized and manageable, especially for applications with multiple related endpoints. Additionally, middleware can be applied selectively within the closure to handle group-specific logic.

onError

Set a custom error handler for a specific route or globally.

You can assign either a callable array handler, controller handler or a closure as the error handler.

public onError(Closure|string|array $pattern, Closure|array|null $handler = null): void

Parameters:

Throws:

• Luminova\Exceptions\RouterException - if $handler is provided but $pattern is not a valid segment pattern.

Using Pattern as Global

• If specifying a URI, provide a string pattern or a controller callback [ControllerClass::class, 'method'].
• If no URI is needed (global), provide only a closure or controller callback.

Examples:

// Global error handler
$router->onError([ErrorController::class, 'onWeError']);

// Specific URI error handler
$router->onError('/users/', [ErrorController::class, 'onWeError']);

// Using a closure
$router->onError('/admin', function() {
    // handle error
});

trigger

Trigger an HTTP error response and immediately halt route processing.

This method is called when no matching route is found, or when a requestmust return a specific HTTP status code (e.g., 404, 500). It attempts todelegate error handling in the following order:

1. If ErrorController::onTrigger() exists, it is called directly.
2. If a matching route-specific error handler is registered, that handler is executed.
3. If a global ('/') error handler is registered, that handler is executed.
4. If no handler is found, a default error page is displayed.

public static trigger(int $status = 404): void

Parameters:

This method can be used anywhere in controller class $this->app->router->trigger() or routing context $router->trigger();.

This method clears output buffers to ensure no partial output is sent before the error response is generated. Once an error response is sent, execution stops immediately.

getUriSegments

Get the current segment URI.

public getUriSegments(): string

Return Value:

string - Return relative paths.

getSegment

To access more information about the requested URI segments.

public getSegment(): Luminova\Routing\Segments

Return Value:

Segments - Return URL segment instance

See Also

Request URI Segment Object - Helper class to retrieve request URI segments.