1. Documentation
  2. API
  3. Cms
  4. Classes
  5. Router

Cms\Classes\Router

Source: ~/modules/cms/classes/Router.php

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

Protected properties

protected Cms\Classes\Theme $theme

A reference to the CMS theme containing the object.

protected string $url

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

protected array $parameters

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

protected array $urlMap

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

protected $routerObj

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

Public methods

public void __construct(Cms\Classes\Theme $theme)

Creates the router instance.

Parameters

public void clearCache()

Clears the router cache.

public string findByFile(string $fileName, array $parameters=array())

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.

Parameters
  • string $fileName - Page file name.
  • array $parameters - Route parameters to consider in the URL.

public Cms\Classes\Page findByUrl(string $url)

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

Parameters
  • string $url - The requested URL string.

public array getParameter($name, $default=NULL)

Returns a routing parameter.

Parameters
  • $name
  • $default

public array getParameters()

Returns the current routing parameters.

public string getUrl()

Returns the last URL to be looked up.

public array setParameters(array $parameters)

Sets the current routing parameters.

Parameters
  • array $parameters

Protected methods

protected string getCacheKey(string $keyName)

Returns the caching URL key depending on the theme.

Parameters
  • string $keyName - Specifies the base key name.

protected mixed getCachedUrlFileName(string $url, array &$urlList)

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

Parameters
  • string $url - Specifies the requested URL.
  • array &$urlList - &$urlList The URL list loaded from the cache

protected array getRouterObject()

Autoloads the URL map only allowing a single execution.

protected string getUrlListCacheKey()

Returns the cache key name for the URL list.

protected array getUrlMap()

Autoloads the URL map only allowing a single execution.

protected boolean loadUrlMap()

Loads the URL map - a list of page file names and corresponding URL patterns. 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.