Documentation

Cms
Classes

Router
in package

october

cms

The router parses page URL patterns and finds pages by URLs.

The page URL format is explained below.

/blog/post/:post_id

Name of parameters should be compatible with PHP variable names. To make a parameter optional add the question mark after its name:

/blog/post/:post_id?

By default parameters in the middle of the URL are required, for example:

/blog/:post_id?/comments - although the :post_id parameter is marked as optional,
it will be processed as required.

Optional parameters can have default values which are used as fallback values in case if the real parameter value is not presented in the URL. Default values cannot contain the pipe symbols and question marks. Specify the default value after the question mark:

/blog/category/:category_id?10 - The category_id parameter would be 10 for this URL: /blog/category

You can also add regular expression validation to parameters. To add a validation expression add the pipe symbol after the parameter name (or the question mark) and specify the expression. The forward slash symbol is not allowed in the expressions. Examples:

/blog/:post_id|^[0-9]+$/comments - this will match /blog/post/10/comments
/blog/:post_id|^[0-9]+$ - this will match /blog/post/3
/blog/:post_name?|^[a-z0-9\-]+$ - this will match /blog/my-blog-post

$parameters


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

A list of parameters names and values extracted from the URL pattern and URL string.

$routerObj

October\Rain\Router\Router Router object with routes preloaded.


    protected
        mixed
    $routerObj

$theme


    protected
        Theme
    $theme

A reference to the CMS theme containing the object.

$url


    protected
        string
    $url

The last URL to be looked up using findByUrl().

$urlMap


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

Contains the URL map - the list of page file names and corresponding URL patterns.

__construct()

Creates the router instance.


    public
                __construct(Theme $theme) : mixed

Parameters

$theme : Theme: Specifies the theme being processed.

Return values

mixed —

clearCache()

Clears the router cache.


    public
                clearCache() : mixed

Return values

mixed —

findByFile()

Finds a URL by it's page. Returns the URL route for linking to the page and uses the supplied parameters in it's address.


    public
                findByFile(string $fileName[, array<string|int, mixed> $parameters = [] ]) : string

Parameters

$fileName : string: Page file name.
$parameters : array<string|int, mixed> = []: Route parameters to consider in the URL.

Return values

string —

A built URL matching the page route.

findByUrl()

Finds a page by its URL. Returns the page object and sets the $parameters property.


    public
                findByUrl(string $url) : Page

Parameters

$url : string: The requested URL string.

Return values

Page —

Returns \Cms\Classes\Page object or null if the page cannot be found.

getParameter()

Returns a routing parameter.


    public
                getParameter(string $name[, string|null $default = null ]) : string|null

Parameters

$name : string
$default : string|null = null

Return values

string|null —

getParameters()

Returns the current routing parameters.


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

Return values

array<string|int, mixed> —

getUrl()

Returns the last URL to be looked up.


    public
                getUrl() : string

Return values

string —

setParameters()

Sets the current routing parameters.


    public
                setParameters(array<string|int, mixed> $parameters) : array<string|int, mixed>

Parameters

$parameters : array<string|int, mixed>

Return values

array<string|int, mixed> —

getCachedUrlFileName()

Tries to load a page file name corresponding to a specified URL from the cache.


    protected
                getCachedUrlFileName(string $url, array<string|int, mixed> &$urlList) : mixed

Parameters

$url : string: Specifies the requested URL.
$urlList : array<string|int, mixed>: The URL list loaded from the cache

Return values

mixed —

Returns the page file name if the URL exists in the cache. Otherwise returns null.

getCacheKey()

Returns the caching URL key depending on the theme.


    protected
                getCacheKey(string $keyName) : string

Parameters

$keyName : string: Specifies the base key name.

Return values

string —

Returns the theme-specific key name.

getRouterObject()

Autoloads the URL map only allowing a single execution.


    protected
                getRouterObject() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Returns the URL map.

getUrlListCacheKey()

Returns the cache key name for the URL list.


    protected
                getUrlListCacheKey() : string

Return values

string —

getUrlMap()

Autoloads the URL map only allowing a single execution.


    protected
                getUrlMap() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Returns the URL map.

loadUrlMap()

Loads the URL map - a list of page file names and corresponding URL patterns.


    protected
                loadUrlMap() : bool

The URL map can is cached. The clearUrlMap() method resets the cache. By default the map is updated every time when a page is saved in the back-end, or when the interval defined with the cms.urlCacheTtl expires.

Return values

bool —

Returns true if the URL map was loaded from the cache. Otherwise returns false.