UrlManager

Type

Class

Namespace

craft\web

Inherits

craft\web\UrlManager » yii\web\UrlManager (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window)

Since

3.0.0

View source (opens new window)

Public Properties

Property	Description
baseUrl (opens new window)	string (opens new window) – The base URL that is used by createUrl() (opens new window) to prepend to created URLs.
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
cache (opens new window)	yii\caching\CacheInterface (opens new window), array (opens new window), string (opens new window), boolean (opens new window) – The cache object or the application component ID of the cache object.
checkToken	boolean (opens new window) – Whether parseRequest() should check for a token on the request and route the request based on that.
enablePrettyUrl (opens new window)	boolean (opens new window) – Whether to enable pretty URLs.
enableStrictParsing (opens new window)	boolean (opens new window) – Whether to enable strict parsing.
hostInfo (opens new window)	string (opens new window) – The host info (e.g. https://www.example.com) that is used by createAbsoluteUrl() (opens new window) to prepend to created URLs.
matchedElement	craft\base\ElementInterface, false (opens new window)
normalizer (opens new window)	yii\web\UrlNormalizer (opens new window), array (opens new window), string (opens new window), false (opens new window) – The configuration for yii\web\UrlNormalizer (opens new window) used by this UrlManager.
routeParam (opens new window)	string (opens new window) – The GET parameter name for route.
routeParams	array (opens new window), null (opens new window)
ruleConfig (opens new window)	array (opens new window) – The default configuration of URL rules.
rules (opens new window)	array (opens new window) – The rules for creating and parsing URLs when enablePrettyUrl (opens new window) is true.
scriptUrl (opens new window)	string (opens new window) – The entry script URL that is used by createUrl() (opens new window) to prepend to created URLs.
showScriptName (opens new window)	boolean (opens new window) – Whether to show entry script name in the constructed URL.
suffix (opens new window)	string (opens new window) – The URL suffix used when enablePrettyUrl (opens new window) is true.

checkToken

Type

boolean (opens new window)

Default value

true

Since

3.2.0

Whether parseRequest() should check for a token on the request and route the request based on that.

View source (opens new window)

matchedElement

Type

craft\base\ElementInterface, false (opens new window)

Default value

null

View source (opens new window)

routeParams

Type

array (opens new window), null (opens new window)

Default value

null

View source (opens new window)

Protected Properties

Property	Description
cacheKey (opens new window)	string (opens new window) – The cache key for cached rules

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	This method is called after the object is created by cloning an existing one.
__construct()	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
addRules() (opens new window)	Adds additional URL rules.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	Returns the fully qualified name of this class.
createAbsoluteUrl()	Creates an absolute URL using the given route and query parameters.
createUrl()	Creates a URL using the given route and query parameters.
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
getBaseUrl() (opens new window)	Returns the base URL that is used by createUrl() (opens new window) to prepend to created URLs.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
getHostInfo() (opens new window)	Returns the host info that is used by createAbsoluteUrl() (opens new window) to prepend to created URLs.
getMatchedElement()	Returns the element that was matched by the URI.
getRouteParams()	Returns the route params, or null if we haven't parsed the URL yet.
getScriptUrl() (opens new window)	Returns the entry script URL that is used by createUrl() (opens new window) to prepend to created URLs.
hasEventHandlers() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
init() (opens new window)	Initializes UrlManager.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	Attaches an event handler to an event.
parseRequest()	Parses the user request.
setBaseUrl() (opens new window)	Sets the base URL that is used by createUrl() (opens new window) to prepend to created URLs.
setHostInfo() (opens new window)	Sets the host info that is used by createAbsoluteUrl() (opens new window) to prepend to created URLs.
setMatchedElement()	Sets the matched element for the request.
setRouteParams()	Sets params to be passed to the routed controller action.
setScriptUrl() (opens new window)	Sets the entry script URL that is used by createUrl() (opens new window) to prepend to created URLs.
trigger() (opens new window)	Triggers an event.

__construct()

Constructor.

View source (opens new window)

Arguments

• $config (array (opens new window))

createAbsoluteUrl()

Creates an absolute URL using the given route and query parameters.

This method prepends the URL created by createUrl() with the hostInfo (opens new window).

Note that unlike yii\helpers\Url::toRoute() (opens new window), this method always treats the given route as an absolute route.

View source (opens new window)

Arguments

• $params (string (opens new window), array (opens new window)) – Use a string to represent a route (e.g. site/index), or an array to represent a route with query parameters (e.g. ['site/index', 'param1' => 'value1']).
• $scheme (string (opens new window), null (opens new window)) – The scheme to use for the URL (either http, https or empty string for protocol-relative URL). If not specified the scheme of the current request will be used.

Returns

string (opens new window) – The created URL

createUrl()

Creates a URL using the given route and query parameters.

You may specify the route as a string, e.g., site/index. You may also use an array if you want to specify additional query parameters for the URL being created. The array format must be:

// generates: /index.php?r=site%2Findex&param1=value1&param2=value2
['site/index', 'param1' => 'value1', 'param2' => 'value2']

If you want to create a URL with an anchor, you can use the array format with a # parameter. For example,

// generates: /index.php?r=site%2Findex&param1=value1#name
['site/index', 'param1' => 'value1', '#' => 'name']

The URL created is a relative one. Use createAbsoluteUrl() to create an absolute URL.

Note that unlike yii\helpers\Url::toRoute() (opens new window), this method always treats the given route as an absolute route.

View source (opens new window)

Arguments

• $params (string (opens new window), array (opens new window)) – Use a string to represent a route (e.g. site/index), or an array to represent a route with query parameters (e.g. ['site/index', 'param1' => 'value1']).

Returns

string (opens new window) – The created URL

getMatchedElement()

Returns the element that was matched by the URI.

WARNING

This should only be called once the application has been fully initialized. Otherwise some plugins may be unable to register EVENT_REGISTER_CP_URL_RULES and EVENT_REGISTER_SITE_URL_RULES event handlers successfully.

View source (opens new window)

Returns

craft\base\ElementInterface, false (opens new window)

Example

• PHP

use craft\web\Application;

Craft::$app->on(Application::EVENT_INIT, function() {
    $element = Craft::$app->urlManager->getMatchedElement();
}

getRouteParams()

Returns the route params, or null if we haven't parsed the URL yet.

View source (opens new window)

Returns

array (opens new window), null (opens new window)

parseRequest()

Parses the user request.

View source (opens new window)

Arguments

• $request (yii\web\Request (opens new window)) – The request component

Returns

array (opens new window), boolean (opens new window) – The route and the associated parameters. The latter is always empty if enablePrettyUrl (opens new window) is false. false is returned if the current request cannot be successfully parsed.

setMatchedElement()

Since

3.2.3

Sets the matched element for the request.

View source (opens new window)

Arguments

• $element (craft\base\ElementInterface, false (opens new window), null (opens new window))

setRouteParams()

Sets params to be passed to the routed controller action.

View source (opens new window)

Arguments

• $params (array (opens new window)) – The route params
• $merge (boolean (opens new window)) – Whether these params should be merged with existing params

Protected Methods

Method	Description
buildRules()	Builds URL rule objects from the given rule declarations.
canBeCached() (opens new window)	Returns the value indicating whether result of createUrl() (opens new window) of rule should be cached in internal cache.
getBuiltRulesFromCache() (opens new window)	Provides the built URL rules that are associated with the $ruleDeclarations from cache.
getUrlFromCache() (opens new window)	Get URL from internal cache if exists.
setBuiltRulesCache() (opens new window)	Stores $builtRules to cache, using $rulesDeclaration as a part of cache key.
setRuleToCache() (opens new window)	Store rule (e.g. yii\web\UrlRule (opens new window)) to internal cache.

buildRules()

Builds URL rule objects from the given rule declarations.

View source (opens new window)

Arguments

• $ruleDeclarations (array (opens new window)) – The rule declarations. Each array element represents a single rule declaration. Please refer to rules (opens new window) for the acceptable rule formats.

Returns

yii\web\UrlRuleInterface (opens new window) – The rule objects built from the given rule declarations

Throws

• yii\base\InvalidConfigException (opens new window)
  if a rule declaration is invalid

Events

EVENT_REGISTER_CP_URL_RULES

Type

craft\events\RegisterUrlRulesEvent

The event that is triggered when registering URL rules for the control panel.

WARNING

This event gets called during class initialization, so you should always use a class-level event handler.

Example

• PHP

use craft\events\RegisterUrlRulesEvent;
use craft\web\UrlManager;
use yii\base\Event;
Event::on(UrlManager::class, UrlManager::EVENT_REGISTER_CP_URL_RULES, function(RegisterUrlRulesEvent $e) {
    $e->rules['foo'] = 'bar/baz';
});

EVENT_REGISTER_SITE_URL_RULES

Type

craft\events\RegisterUrlRulesEvent

The event that is triggered when registering URL rules for the front-end site.

WARNING

This event gets called during class initialization, so you should always use a class-level event handler.

Example

• PHP

use craft\events\RegisterUrlRulesEvent;
use craft\web\UrlManager;
use yii\base\Event;
Event::on(UrlManager::class, UrlManager::EVENT_REGISTER_SITE_URL_RULES, function(RegisterUrlRulesEvent $e) {
    $e->rules['foo'] = 'bar/baz';
});