URI Routing

Luminova's framework routes serve as efficient handlers for capturing URI patterns upon requests. They simplify routing configurations by enabling the definition of URI matching patterns, methods, and closures for view rendering.

In your route context file /routes/*.php, the $router, $app variable is already set as a global variable. Therefore, there's no need to specify the use keyword or import the router instance anymore.

<?php
$router->get('/', function () use($app) {
    $app->view('index')->render();
});

Controller Class

When passing your controller class, you only need to provide the class name, without the full namespace (e.g., ExampleController) instead of App\Controllers\ExampleController. The namespace is automatically registered, allowing you to pass only a controller class that extends Luminova\Base\BaseController by default.

<?php
$router->get('/about', 'ExampleController::about');

Bind Group

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

<?php
use \Luminova\Routing\Router;
use \Luminova\Base\BaseApplication;

$router->bind('/blog', function(Router $router, BaseApplication $app) {
    $router->get('/', 'ExampleController::blogs');
    $router->get('/([a-zA-Z0-9]+)', 'ExampleController::blog');
});

Capture and HTTP method

The any method allows you to capture any HTTP method for contact us page as shown below.

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

If you want to use a selected methods you can do that using capture() method.

<?php
$router->capture('POST|GET|PUT', '/home', 'ExampleController::home');

Dependency injection.

<?php
use \Luminova\Http\Request;

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

Controller Command

Registering command controller routing.

<?php
use \Luminova\Routing\Router;
use \Luminova\Base\BaseApplication;
use \Luminova\Command\Terminal;

$router->group("group", function(Router $router, BaseApplication $app, Terminal $term) {
    $router->command("test", 'Command::test');
    $router->command('/foo/name/(:value)', 'Command::foo');
});

Routing Example see examples for more usages.

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

Methods

Middleware

HTTP middleware security allows you to define authentication to validate requests before allowing other routes to execute or terminate their executions based on the returned response code: STATUS_SUCCESS (0) or STATUS_ERROR (1).

To instruct the middleware to terminate or proceed with execution, your controller method or closure must return an integer as described above.

Middlewares can be registered within a bind method or in the global scope of the routing context. It also support defining regex patterns and methods to capture.

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

Parameters:

Before

The before method provides middleware security for CLI commands. It allows you to define and execute authentication before other commands are executed. If the response code returns STATUS_SUCCESS, the subsequent commands will be executed; otherwise, if STATUS_ERROR is returned, other commands will not be executed.

Unlike the middleware method, which handles HTTP middleware authentication and accepts regular regex patterns, the before method accepts only the command group name or any for global middleware security.

To register middleware with the group name, you must define your before method within the group method callback closure.

public before(|string $group, \Closure|string $callback = null): void

Parameters:

after

The after route method, allow you to define a middleware to executes after route controller was executed successfully.This method can only be used on HTTP request method, it not allowed in CLI mode.

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

Parameters:

capture

The capture method allows you to define set of methods the controller should handle based on HTTP request method, and URI patterns to look for the listed methods. Once the method and patterns match the callback controller will be executed accordingly.

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

Parameters:

Command

This method registers and captures command requests to execute callbacks. It is similar to the capture method but is intended for use only in CLI mode.

Unlike the capture method, this method does not support regular regex patterns. Instead, it uses a set of rules to capture command arguments.

For example, suppose you have a command group blogs, and in your blog command controller class, you have two methods: list and get. The list method accepts an int argument to determine the number of blogs to list, and the get method accepts a string as the blog ID. You will need to register commands with patterns like /list/limit/(:int) for the list method and /get/id/(:value) for the get method.

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

Parameters:

Rules

• mixed: Indicates that the expected parameter can be any value.
• optional: Indicates that the expected parameter can be blank (the parameter must be called).
• int: Indicates that the expected parameter must be a valid integer.
• float: Indicates that the expected parameter must be a valid float value.
• string: Indicates that the expected parameter must consist of alphanumeric characters, underscores, and hyphens.
• alphabet: Indicates that the expected parameter must consist of alphabetic characters only.
• path: Indicates that the expected parameter must be a valid file path (e.g., /path/to/foo).

Note:The first segment of the pattern indicates the command name, while subsequent segments like /foo/(:rule)/bar/(:rule) indicate the expected parameter. Ensure to enclose the rule in brackets with a colon before the rule name.For commands that don't expect any parameter, you don't need to add any rule; just pass the name like /foo.

Execution of the command controller must follow this pattern: php index.php <group> <command> <...argument value> <--flag>.

any

A shorthand for route capture method to handle any type of request method.

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

Parameters:

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:

bind

The Bind method allow you to group a collection nested URI together in a single base suffix.

For instance you have a URL like http://example.com/user, when you bind user, then all user related URLs will be in one group like http://example.com/user/account, http://example.com/user/dashboard etc.

public bind(string $group, \Closure $callback): void

Parameters:

Throws:

• \Luminova\Exceptions\RouterException - If invalid callback is provided

group

The group method works similar to bind method, except that group if used only in CLI group binding to bind a collection of command controllers that belong to same group.

public group(string $group, \Closure $callback): void

Parameters:

Throws:

• \Luminova\Exceptions\RouterException - If invalid callback is provided

Note: Your group name must match with the defined group name in controller class.

context

The context method enables you to define URI prefixes and error handlers for specific URI prefix names. By doing so, it ensures that only the necessary routes for handling requests are loaded based on the URL prefix, , like api, console and more.

The web is the default to handle any incoming request with no unique registered context/prefix.

The flexible array arguments approach is particularly useful for scenarios with complex routing requirements or a large number of contexts. Leveraging the array approach may offer better scalability and maintainability. Choose the method that aligns best with your specific use case and coding style preferences.

public context(\Luminova\Routing\Context|array<string,mixed> ...$contextes): \Luminova\Routing\Router

Parameters:

Return Value

Router - Return router instance.

Throws:

• \Luminova\Exceptions\RouterException - Throws if no context arguments was passed.

See Also:

• Routing Context - Read more on how routing prefix work and usages.
• Index Controller Handler - See example of front controller index file handler.

Note: The context name must be unique based on your URLs, in other to discover and load only the required file.Additionally, mixing context arguments with Array and Context instance may produce unintended error.

addNamespace

To register controller class namespace that router is allowed to lookup classed in.

public addNamespace(string $namespace): void

Parameters:

Throws:

• \Luminova\Exceptions\RouterException - If namespace string is empty or contains invalid namespace characters.

run

Run application routes, loop through registered routes and executed request methods if match is found.

public run(\Closure|null $callback = null): void

Parameters:

Throws:

• \Luminova\Exceptions\RouterException - Encounter error while executing controller callback

setErrorListener

Set the handler context error listener for 404 errors.

public setErrorListener(\Closure|string|array $match, \Closure|array|null $callback = null): void

Parameters:

If the $match parameter is passed a callback handler and $callback parameter is passed NULL, then the handler will trigger the error callback whenever any 404 error occurred within the routing context.

To define a custom error based on group or patterns, You must define your match patterns before callback method or closure.

triggerError

To manually trigger an error handler.This method can be used anywhere in controller class $this->app->router->triggerError() or routing context $router->triggerError();.

public triggerError(int $status = 404): void

Parameters:

getBase

To get application public controller base path.

public getBase(): string

Return Value:

string - Return base path.

getSegment

To access more information about the requested URI segments.

public getSegment(): \Luminova\Routing\Segments

Return Value:

Segments - Return URL segment instance

See Also

View Segment Instance - Helper class to retrieve view segments.