VELOX API Docs

Router
in package

A class that serves as a router and an entry point for the application.

Example:

// register a middleware
Router::middleware('/pages/{pageId}', function ($path, $match, $previous) {
     return 'I am working as expected!';
}, 'POST');

// register a route handler
Router::handle('/pages/{pageId}', function ($path, $match, $previous) {
     return sprintf('Hi from "%s" handler, Page ID is: %s, also the middleware said: %s', $path, $match, $previous ?? 'Nothing!');
}, ['GET', 'POST']);

// register a route handler using an HTTP verb
Router::get('/another-page', function () {
     return View::render('another-page');
});

// start the application
Router::start();
Tags
since
1.0.0

Table of Contents

BEFORE_FORWARD  = 'router.before.forward'
This event will be dispatched when a forward is attempted.
BEFORE_REDIRECT  = 'router.before.redirect'
This event will be dispatched when a redirect is attempted.
DEFAULTS  = ['base' => '/', 'allowMultiMatch' => true, 'caseMatters' => false, 'slashMatters' => true, 'allowAutoStart' => true]
The default values of class parameters.
ON_REGISTER_HANDLER  = 'router.on.registerHandler'
This event will be dispatched when a handler is registered.
ON_REGISTER_MIDDLEWARE  = 'router.on.registerMiddleware'
This event will be dispatched when a middleware is registered.
ON_START  = 'router.on.start'
This event will be dispatched when the router is started.
SUPPORTED_METHODS  = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE']
Supported HTTP methods.
HANDLER_ROUTE  = 'HANDLER'
Route type handler.
MIDDLEWARE_ROUTE  = 'MIDDLEWARE'
Route type handler.
$base  : string|null
The current base URL of the application.
$path  : string|null
The currently requested path.
$routes  : array<string|int, mixed>
The currently registered routes.
$params  : array<string|int, mixed>|null
The parameters the application started with.
__call()  : mixed
Allows static methods handled by `self::__callStatic()` to be accessible via object operator `->`.
__callStatic()  : mixed
Aliases `self::handle()` method with common HTTP verbs.
__construct()  : mixed
Class constructor.
any()  :
connect()  :
delete()  :
forward()  : void
Forwards the request to another route.
get()  :
getParsedQuery()  : array<string|int, mixed>
Returns query parameters.
getParsedUrl()  : array<string|int, mixed>
Returns components of the current URL.
getRegisteredRoutes()  : array<string|int, mixed>
Returns all registered routes with their `expression`, `handler`, `arguments`, and `method`.
handle()  : static
Registers a handler for a route.
head()  :
middleware()  : static
Registers a middleware for a route. This method has no effect if `$allowMultiMatch` is set to `false`.
options()  :
patch()  :
post()  :
put()  :
redirect()  : void
Redirects the request to another route.
start()  : void
Starts the router.
trace()  :
getRequestMethod()  : string
Returns the current request method via `$_SERVER` or `$_POST['_method']`.
getRouteArguments()  : array<string|int, mixed>
Returns valid arguments for route handler in the order that the handler expect.
getRoutePath()  : string
Returns a valid decoded route path.
getRouteRegex()  : string
Returns a valid route regex.
getValidParameters()  : array<string|int, mixed>
Returns valid parameters for `self::start()` by validating the passed parameters and adding the deficiency from router config.
respond()  : void
Echos the response according to the passed parameters.
registerRoute()  : static
Registers a route.
sort()  : void
Sorts registered routes to make middlewares come before handlers.

Constants

BEFORE_FORWARD

This event will be dispatched when a forward is attempted.

public string BEFORE_FORWARD = 'router.before.forward'

This event will be passed the forward path.

BEFORE_REDIRECT

This event will be dispatched when a redirect is attempted.

public string BEFORE_REDIRECT = 'router.before.redirect'

This event will be passed the redirection path/URL and the status code.

DEFAULTS

The default values of class parameters.

public array<string|int, mixed> DEFAULTS = ['base' => '/', 'allowMultiMatch' => true, 'caseMatters' => false, 'slashMatters' => true, 'allowAutoStart' => true]

ON_REGISTER_HANDLER

This event will be dispatched when a handler is registered.

public string ON_REGISTER_HANDLER = 'router.on.registerHandler'

This event will be passed a reference to the route config array.

ON_REGISTER_MIDDLEWARE

This event will be dispatched when a middleware is registered.

public string ON_REGISTER_MIDDLEWARE = 'router.on.registerMiddleware'

This event will be passed a reference to the route config array.

ON_START

This event will be dispatched when the router is started.

public string ON_START = 'router.on.start'

This event will be passed a reference to the router parameters.

SUPPORTED_METHODS

Supported HTTP methods.

public array<string|int, mixed> SUPPORTED_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE']

HANDLER_ROUTE

Route type handler.

protected string HANDLER_ROUTE = 'HANDLER'
Tags
since
1.5.2

MIDDLEWARE_ROUTE

Route type handler.

protected string MIDDLEWARE_ROUTE = 'MIDDLEWARE'
Tags
since
1.5.2

Properties

$base

The current base URL of the application.

protected static string|null $base = null

$path

The currently requested path.

protected static string|null $path = null

$routes

The currently registered routes.

protected static array<string|int, mixed> $routes = []

$params

The parameters the application started with.

private static array<string|int, mixed>|null $params = null

Methods

__call()

Allows static methods handled by `self::__callStatic()` to be accessible via object operator `->`.

public __call(string $method, array<string|int, mixed> $arguments) : mixed
Parameters
$method : string
$arguments : array<string|int, mixed>
Return values
mixed —

__callStatic()

Aliases `self::handle()` method with common HTTP verbs.

public static __callStatic(string $method, array<string|int, mixed> $arguments) : mixed
Parameters
$method : string
$arguments : array<string|int, mixed>
Return values
mixed —

__construct()

Class constructor.

public final __construct() : mixed
Return values
mixed —

any()

public static any(string $expression, callable $handler) :

Handles any request method.

Parameters
$expression : string
$handler : callable
Return values
—

connect()

public static connect(string $expression, callable $handler) :

Handles a CONNECT request method.

Parameters
$expression : string
$handler : callable
Return values
—

delete()

public static delete(string $expression, callable $handler) :

Handles a DELETE request method.

Parameters
$expression : string
$handler : callable
Return values
—

forward()

Forwards the request to another route.

public static forward(string $to) : void

Note that this function will exit the script (code that comes after it will not be executed).

Parameters
$to : string

A route like /page.

Return values
void —

get()

public static get(string $expression, callable $handler) :

Handles a GET request method.

Parameters
$expression : string
$handler : callable
Return values
—

getParsedQuery()

Returns query parameters.

public static getParsedQuery() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getParsedUrl()

Returns components of the current URL.

public static getParsedUrl() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getRegisteredRoutes()

Returns all registered routes with their `expression`, `handler`, `arguments`, and `method`.

public static getRegisteredRoutes() : array<string|int, mixed>
Return values
array<string|int, mixed> —

handle()

Registers a handler for a route.

public static handle(string $expression, callable $handler[, string|array<string|int, string> $method = 'GET' ]) : static
Parameters
$expression : string

A route like /page, /page/{id} (id is required), or /page/{id?} (id is optional), or page* (* is a wildcard for anything). For more flexibility, pass an expression like /page/([\d]+|[0-9]*) (regex capture group).

$handler : callable

A function to call if route has matched. It will be passed the current $path, the $match or ...$match from the expression if there was any, and lastly the $previous result (the return of the last middleware or route with a matching expression) if $allowMultiMatch is set to true.

$method : string|array<string|int, string> = 'GET'

[optional] Either a string or an array of the allowed method.

Return values
static —

head()

public static head(string $expression, callable $handler) :

Handles a HEAD request method.

Parameters
$expression : string
$handler : callable
Return values
—

middleware()

Registers a middleware for a route. This method has no effect if `$allowMultiMatch` is set to `false`.

public static middleware(string $expression, callable $handler[, string|array<string|int, string> $method = 'GET' ]) : static
Parameters
$expression : string

A route like /page, /page/{id} (id is required), or /page/{id?} (id is optional), or page* (* is a wildcard for anything). For more flexibility, pass an expression like /page/([\d]+|[0-9]*) (regex capture group).

$handler : callable

A function to call if route has matched. It will be passed the current $path, the $match or ...$match from the expression if there was any, and lastly the $previous result (the return of the last middleware or route with a matching expression) if $allowMultiMatch is set to true.

$method : string|array<string|int, string> = 'GET'

[optional] Either a string or an array of the allowed method.

Return values
static —

options()

public static options(string $expression, callable $handler) :

Handles a OPTIONS request method.

Parameters
$expression : string
$handler : callable
Return values
—

patch()

public static patch(string $expression, callable $handler) :

Handles a PATCH request method.

Parameters
$expression : string
$handler : callable
Return values
—

post()

public static post(string $expression, callable $handler) :

Handles a POST request method.

Parameters
$expression : string
$handler : callable
Return values
—

put()

public static put(string $expression, callable $handler) :

Handles a PUT request method.

Parameters
$expression : string
$handler : callable
Return values
—

redirect()

Redirects the request to another route.

public static redirect(string $to[, int $status = 302 ]) : void

Note that this function will exit the script (code that comes after it will not be executed).

Parameters
$to : string

A route like /page or a URL like http://domain.tld.

$status : int = 302

[optional] The HTTP status code to send.

Return values
void —

start()

Starts the router.

public static start([string|null $base = null ][, bool|null $allowMultiMatch = null ][, bool|null $caseMatters = null ][, bool|null $slashMatters = null ]) : void
Parameters
$base : string|null = null
$allowMultiMatch : bool|null = null
$caseMatters : bool|null = null
$slashMatters : bool|null = null
Tags
throws
LogicException

If route handler failed or returned false.

Return values
void —

trace()

public static trace(string $expression, callable $handler) :

Handles a TRACE request method.

Parameters
$expression : string
$handler : callable
Return values
—

getRequestMethod()

Returns the current request method via `$_SERVER` or `$_POST['_method']`.

protected static getRequestMethod() : string
Return values
string —

getRouteArguments()

Returns valid arguments for route handler in the order that the handler expect.

protected static getRouteArguments(array<string|int, mixed> $current, array<string|int, mixed> $matches, mixed $result) : array<string|int, mixed>
Parameters
$current : array<string|int, mixed>
$matches : array<string|int, mixed>
$result : mixed
Return values
array<string|int, mixed> —

getRoutePath()

Returns a valid decoded route path.

protected static getRoutePath(bool $slashMatters) : string
Parameters
$slashMatters : bool
Return values
string —

getRouteRegex()

Returns a valid route regex.

protected static getRouteRegex(string $expression, bool $slashMatters, bool $caseMatters) : string
Parameters
$expression : string
$slashMatters : bool
$caseMatters : bool
Return values
string —

getValidParameters()

Returns valid parameters for `self::start()` by validating the passed parameters and adding the deficiency from router config.

protected static getValidParameters(string|null $base, bool|null $allowMultiMatch, bool|null $caseMatters, bool|null $slashMatters) : array<string|int, mixed>
Parameters
$base : string|null
$allowMultiMatch : bool|null
$caseMatters : bool|null
$slashMatters : bool|null
Return values
array<string|int, mixed> —

respond()

Echos the response according to the passed parameters.

protected static respond(mixed $result, bool $routeMatchFound, bool $pathMatchFound) : void
Parameters
$result : mixed
$routeMatchFound : bool
$pathMatchFound : bool
Return values
void —

registerRoute()

Registers a route.

private static registerRoute(string $type, string $expression, callable $handler, array<string|int, mixed> $arguments, string|array<string|int, mixed> $method) : static
Parameters
$type : string
$expression : string
$handler : callable
$arguments : array<string|int, mixed>
$method : string|array<string|int, mixed>
Return values
static —

sort()

Sorts registered routes to make middlewares come before handlers.

private static sort() : void
Return values
void —

Search results