README

Router

The Router is passive, multi-lingual regex router. It supports route names, route parameters, route controllers and route middleware. Passive means that it doesn't set HTTP headers and it doesn't invoke route controllers and middleware. It just tests a request URI against the defined routes and returns all necessary data to build a route.

Installation

composer require webiik/router

Example

$router = new \Webiik\Router\Router();

// Set base URI
$router->setBaseURI(dirname($_SERVER['SCRIPT_NAME']));

// Add route(s)
$router->addRoute(['get'], '/', 'Home:run', 'home-page');

// Check if current URI matches some route
$route = $router->match();

if ($router->getHttpCode() == 200) {
    // 200 - OK
    $route->getLang(); // en
    $route->getName(); // home-page
    $route->getController(); // ['Home', 'run']   
} elseif ($router->getHttpCode() == 405) {
    // 405 - Method Not Allowed
} elseif ($router->getHttpCode() == 404) {
    // 404 - Not Found
}

Configuration

setBaseURI

setBaseURI(string $baseURI): void

setBaseURI() sets the base directory of your index.php file relatively to web-server root.

$router->setBaseURI(dirname($_SERVER['SCRIPT_NAME']));

Every time your index.php file isn't in the web-server root directory, you have to set dir in which is located.

setDefaultLang

setDefaultLang(string $defaultLang): void

setDefaultLang() sets the default language of routes without defined $lang parameter. $defaultLang must be two characters long. The default value is en.

$router->setDefaultLang('en');

setDefaultLangInURI

setDefaultLangInURI(bool $defaultLangInURI): void

setDefaultLangInURI() determines if default language is part of URI e.g. /en/. The default value is FALSE.

$router->setDefaultLangInURI(true);

Adding

addRoute

addRoute(array $methods, string $route, string $controller, string $name = '', string $lang = ''): NewRoute

addRoute() adds NewRoute to the Router and returns NewRoute.

Parameters:

methods array of route http methods
route route URI regex (without delimiters)
controller string representation of controller e.g. controllerName:methodName
name route name
lang two letter route lang prefix, if it's not set, the default lang is used instead

// Add route
$router->addRoute(['get'], '/', 'Home:run');

// Add route with more http methods
$router->addRoute(['get', 'post'], '/contact', 'Contact:run');

// Add named route
$router->addRoute(['get'], '/', 'Home:run', 'home-page');

// Add named route in specific language 
$router->addRoute(['get'], '/', 'Home:run', 'home-page', 'en');

// Add route with route middleware
$router->addRoute(['get'], '/', 'Home:run')->mw('Class:method');

// Add case sensitive route
$router->addRoute(['get'], '/CaMeL', 'Camel:run')->sensitive();

// To add routes with route parameters use regex groups.
// Every regex group represents one route parameter.

// Add route with required parameter
$router->addRoute(['get'], '/portfolio/(?<client>[a-z0-9]+)', 'Portfolio:run');

// Add route with optional parameter
$router->addRoute(['get'], '/portfolio/(?<client>[a-z0-9]+)?', 'Portfolio:run');

Check

match

match(): Route

match() checks if current request URI matches some of defined route and returns Route.

$route = $router->match();

getHttpCode

getHttpCode(): int

getHttpCode() returns http code of the result of last match().

$route = $router->match();
$httpCode = $router->getHttpCode();
if ($httpCode == 200) {
    // 200 OK
} elseif ($httpCode == 405) {
    // 405 Method Not Allowed
} elseif ($httpCode == 404) {
    // 404 Not Found
}

Getting

getBaseURL

getBaseURL(): string

getBaseURL() returns base URL of your app e.g. https://www.webiik.com

$baseUrl = $router->getBaseURL();

getURI

getURI(string $routeName, array $parameters = [], string $lang = ''): string

getURI() returns route's URI. If it can't find the route or some of the required route parameters is missing, then it returns the empty string. After calling getURI(), you can get missing parameters by calling getMissingParameters()

$route->getURI();

getURL

getURL(string $routeName, array $parameters = [], string $lang = ''): string

getURL() same as getURI(), but returns full URL.

$route->getURL();

getMissingParameters

getMissingParameters(): array

getMissingParameters() returns missing parameters after calling getURI() or getURL().

$route->getMissingParameters();

getRegexParameters

getRegexParameters(string $routeName, string $lang = '')

getRegexParameters() returns array with route regex parameters e.g. ['0' => '(?<name>[a-z])?', '1' => '([a-z])']. If the route doesn't exist, it returns false.

$route->getRegexParameters();

Route

The Route is the result of match(). It contains handy information about the current route.

getController

getController(): array

getController() returns array with route controller and controller method to run.

$route->getController();

getName

getName(): string

getName() returns route name.

$route->getName();

getLang

getLang(): string

getLang() returns route language.

$route->getLang();

getMw

getMw(): array

getMw() returns array with route middleware.

$route->getMw();

getParameters

getParameters(): array

getParameters() returns parameters injected during Route construction e.g. ['name' => 'dolly', '1' => 'dolly', '2' => 'hello'].

$route->getParameters();

webiik / router

Maintainers

Details