Documentation

Router
in package

Handles the routing

Every web application needs a router for handling routes. A route is a HTTP method and path for a specific action.

Example routes:

  • GET /books - returns a list of books
  • GET /books/123 - returns the details of a book with ID 123
  • POST /books/123/save - saves the details of a book with ID 123

Table of Contents

CONFIG_INDEX_FILE  = 'router.index_file'
CONFIG_ROUTE_PARAMETER  = 'router.route_parameter'
CONFIG_USE_REWRITE  = 'router.use_rewrite'
DEFAULT_INDEX_FILE  = 'index.php'
DEFAULT_ROUTE_PARAMETER  = 'route'
DEFAULT_USE_REWRITE  = false
ROUTE_NOT_FOUND  = [null, null]
Constant used for the case when no route found
$config  : Config
$prefixVariables  : array<string|int, mixed>
Stores callables for the start segments of all of the routes. For example the locale is a prefix variable, because it is always in every route and the value depends on the incoming request.
$request  : Request
$routes  : array<string|int, mixed>
Stores all of the routes in ['HTTP method' => ['/route' => callable]] format
$segments  : array<string|int, mixed>
All segments of the current route
__construct()  : mixed
It will fill up the `$segments` array
add()  : void
Stores a route with a callable
addPrefixVariable()  : int
Adds a prefix variable callable for all of the routes
currentRoute()  : string
Returns with the current route
currentSegment()  : mixed|null
Returns with a segment value of the current route by index
matchCurrentRoute()  : array<string|int, mixed>
Matches the current route and returns with the associated callable and parameters
routes()  : array<string|int, mixed>
Returns with all of the stored routes
url()  : string
Returns with a URL for the given route
match()  : array<string|int, mixed>
Matches a route and returns with the given callable

Constants

CONFIG_INDEX_FILE

public mixed CONFIG_INDEX_FILE = 'router.index_file'

CONFIG_ROUTE_PARAMETER

public mixed CONFIG_ROUTE_PARAMETER = 'router.route_parameter'

CONFIG_USE_REWRITE

public mixed CONFIG_USE_REWRITE = 'router.use_rewrite'

DEFAULT_INDEX_FILE

public mixed DEFAULT_INDEX_FILE = 'index.php'

DEFAULT_ROUTE_PARAMETER

public mixed DEFAULT_ROUTE_PARAMETER = 'route'

DEFAULT_USE_REWRITE

public mixed DEFAULT_USE_REWRITE = false

ROUTE_NOT_FOUND

Constant used for the case when no route found

public mixed ROUTE_NOT_FOUND = [null, null]

Properties

$prefixVariables

Stores callables for the start segments of all of the routes. For example the locale is a prefix variable, because it is always in every route and the value depends on the incoming request.

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

In the route '/en/books' the '/en' is a prefix variable and the '/books' is the stored route

$routes

Stores all of the routes in ['HTTP method' => ['/route' => callable]] format

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

Callables: https://www.php.net/manual/en/language.types.callable.php But you can use the [ExampleClass::class, 'exampleMethod'] format too.

$segments

All segments of the current route

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

For example if the route is '/en/book/123/save' this will has the following value: ['en', 'book', '123', 'save']

Methods

__construct()

It will fill up the `$segments` array

public __construct(Config $config, Request $request) : mixed
Parameters
$config : Config
$request : Request
Return values
mixed —

add()

Stores a route with a callable

public add(string $route, callable $callable[, string $method = 'GET' ]) : void

The $callable can use the [ExampleClass::class, 'exampleMethod'] format too.

The route can have variables with question mark: '/route/?' then the callable method in this case must have one parameter!

The $method can be any of the HTTP methods or BOTH. BOTH will add the route to the GET and to the POST as well.

For example, the route is GET /books/?:

$router->add('/books/?', [BooksController::class, 'view']);

then the callable should look like

class BooksController {
  function view($id) {
  }
}
Parameters
$route : string

The route, for example: '/route'

$callable : callable

The callable for the route

$method : string = 'GET'

Any of HTTP methods or 'BOTH'

Return values
void —

addPrefixVariable()

Adds a prefix variable callable for all of the routes

public addPrefixVariable( $callable) : int

For example, if you have a prefix variable that calls the Translation::locale() method and then you call the url method with '/something' and you configured the app.base_url to 'https://example.com' it will return with

https://example.com/en/something
Parameters
$callable :
Tags
link
https://www.php.net/manual/en/language.types.callable.php
Return values
int —

The segment index of the newly added prefix variable

currentRoute()

Returns with the current route

public currentRoute() : string

The route HTTP query parameter name can be configured with the router.route_parameter. If no parameter exists the default will be the home route '/'

Tags
see
Config
Return values
string —

currentSegment()

Returns with a segment value of the current route by index

public currentSegment(int $index[, mixed|null $default = null ]) : mixed|null
Parameters
$index : int

The index of the segment

$default : mixed|null = null

The default value if the segment doesn't exist

Return values
mixed|null —

The value of the segment by index

matchCurrentRoute()

Matches the current route and returns with the associated callable and parameters

public matchCurrentRoute() : array<string|int, mixed>

For example, the current route is '/books/123/comments/45', the stored route is '/books/?/comments/?' and it matches then the result will be:

[the stored callable for the route, ['123', '45']]

If no match for the current route it will return with ROUTE_NOT_FOUND alias [null, null]

Return values
array<string|int, mixed> —

The associated callable and parameters with the current route in [callable, [parameters]] format

routes()

Returns with all of the stored routes

public routes() : array<string|int, mixed>

The result format will be ['HTTP method' => ['/route' => callable]]

Return values
array<string|int, mixed> —

The routes

url()

Returns with a URL for the given route

public url(string $route[, array<string|int, mixed> $params = [] ][, string $amp = '&' ]) : string

Heavily depends on the configuration of the application.

For example the parameters are the following:

  • $route = '/books/123'
  • $params = ['name' => 'joe']
  • $amp = '&'

and the application config is the following:

app.base_url = "http://example.com"
router.use_rewrite = false
router.index_file = "index.php"
router.route_parameter = "route"

then the result will be:

http://example.com/index.php?route=/books/123&name=joe

If the router.use_rewrite set to true, the router.index_file and the router.route_parameter will not be in the result, but for this you have to configure your webserver to redirect non existing file & directory HTTP queries to your /index.php?route={URI}

http://example.com/books/123?name=joe

If you have a prefix variable added (usually locale) and that has the value 'en', the result will be:

http://example.com/en/books/123?name=joe
Parameters
$route : string

The route

$params : array<string|int, mixed> = []

The HTTP query parameters for the route

$amp : string = '&'

The ampersand symbol. The default is '&amp;' but you can change it to '&' if needed.

Return values
string —

The full URL for the route

match()

Matches a route and returns with the given callable

protected match(string $route, callable $callable, array<string|int, mixed> $currentParts, int $currentPartsCount) : array<string|int, mixed>

The $callable can be in a [Example::class, 'exampleMethod'] format as well, so you don't have to create an instance only when this callable is used.

Parameters
$route : string

The route we want to match

$callable : callable

The callable we want to return if the route matches

$currentParts : array<string|int, mixed>

An array of the current route segments WITHOUT the prefix variables

$currentPartsCount : int

The count of the $currentParts array

Return values
array<string|int, mixed> —

The callable and the fetched parameters in [callable, [parameters]] format

Search results