Router
The router parses page URL patterns and finds pages by URLs.
class Cms\Classes\RouterThe 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
Properties
protected
$parameters
:
array
= []
A list of parameters names and values extracted from the URL pattern and URL string.
protected $routerObj : mixed
Winter\Storm\Router\Router Router object with routes preloaded.
protected $theme : Cms\Classes\Theme
A reference to the CMS theme containing the object.
protected $url : string
The last URL to be looked up using findByUrl().
protected
$urlMap
:
array
= []
Contains the URL map - the list of page file names and corresponding URL patterns.
Methods
public __construct (Cms\Classes\Theme $theme)
Creates the router instance.
| Property | Type | Description |
|---|---|---|
| $theme | Cms\Classes\Theme |
Cms\Classes\Theme
Specifies the theme being processed. |
public clearCache ()
Clears the router cache.
public
findByFile (string $fileName, array $parameters = [])
: string
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.
| Property | Type | Description |
|---|---|---|
| $fileName | string |
string
Page file name. |
| $parameters | array |
array
Route parameters to consider in the URL. |
A built URL matching the page route.
public findByUrl (string $url) : Cms\Classes\Page
Finds a page by its URL. Returns the page object and sets the $parameters property.
| Property | Type | Description |
|---|---|---|
| $url | string |
string
The requested URL string. |
Returns \Cms\Classes\Page object or null if the page cannot be found.
public
getParameter (string $name, string | null $default = null)
: string | null
Returns a routing parameter.
| Property | Type | Description |
|---|---|---|
| $name | string |
string
|
| $default | string | null |
string | null
|
public getParameters () : array
Returns the current routing parameters.
public getUrl () : string
Returns the last URL to be looked up.
public setParameters (array $parameters) : array
Sets the current routing parameters.
| Property | Type | Description |
|---|---|---|
| $parameters | array |
array
|
protected getCacheKey (string $keyName) : string
Returns the caching URL key depending on the theme.
| Property | Type | Description |
|---|---|---|
| $keyName | string |
string
Specifies the base key name. |
Returns the theme-specific key name.
protected getCachedUrlFileName (string $url, array $urlList) : mixed
Tries to load a page file name corresponding to a specified URL from the cache.
| Property | Type | Description |
|---|---|---|
| $url | string |
string
Specifies the requested URL. |
| $urlList | array |
array
The URL list loaded from the cache |
Returns the page file name if the URL exists in the cache. Otherwise returns null.
protected getRouterObject () : array
Autoloads the URL map only allowing a single execution.
Returns the URL map.
protected getUrlListCacheKey () : string
Returns the cache key name for the URL list.
protected getUrlMap () : array
Autoloads the URL map only allowing a single execution.
Returns the URL map.
protected loadUrlMap () : bool
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.
Returns true if the URL map was loaded from the cache. Otherwise returns false.