UrlManager

Type

Class

Namespace

craft\web

Inherits

craft\web\UrlManager » yii\web\UrlManager » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Since

3.0.0

View source

Public Properties

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

checkToken

Type

boolean

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

matchedElement

Type

craft\base\ElementInterface, false

Default value

null

View source

routeParams

Type

array, null

Default value

null

View source

Protected Properties

Property	Description
cacheKey	string – The cache key for cached rules

Public Methods

Method	Description
__call()	Calls the named method which is not a class method.
__clone()	This method is called after the object is created by cloning an existing one.
__construct()	Constructor.
__get()	Returns the value of a component property.
__isset()	Checks if a property is set, i.e. defined and not null.
__set()	Sets the value of a component property.
__unset()	Sets a component property to be null.
addRules()	Adds additional URL rules.
attachBehavior()	Attaches a behavior to this component.
attachBehaviors()	Attaches a list of behaviors to the component.
behaviors()	Returns a list of behaviors that this component should behave as.
canGetProperty()	Returns a value indicating whether a property can be read.
canSetProperty()	Returns a value indicating whether a property can be set.
className()	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()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
getBaseUrl()	Returns the base URL that is used by createUrl() to prepend to created URLs.
getBehavior()	Returns the named behavior object.
getBehaviors()	Returns all behaviors attached to this component.
getHostInfo()	Returns the host info that is used by createAbsoluteUrl() 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()	Returns the entry script URL that is used by createUrl() to prepend to created URLs.
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.
hasMethod()	Returns a value indicating whether a method is defined.
hasProperty()	Returns a value indicating whether a property is defined for this component.
init()	Initializes UrlManager.
off()	Detaches an existing event handler from this component.
on()	Attaches an event handler to an event.
parseRequest()	Parses the user request.
setBaseUrl()	Sets the base URL that is used by createUrl() to prepend to created URLs.
setHostInfo()	Sets the host info that is used by createAbsoluteUrl() 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()	Sets the entry script URL that is used by createUrl() to prepend to created URLs.
trigger()	Triggers an event.

__construct()

Constructor.

View source

Arguments

• $config (array)

createAbsoluteUrl()

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

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

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

View source

Arguments

• $params (string, array) – 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, null) – 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 – 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(), this method always treats the given route as an absolute route.

View source

Arguments

• $params (string, array) – 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 – 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

Returns

craft\base\ElementInterface, false

---

Example

::: code

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

Returns

array, null

parseRequest()

Parses the user request.

View source

Arguments

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

Returns

array, boolean – The route and the associated parameters. The latter is always empty if enablePrettyUrl 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

Arguments

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

setRouteParams()

Sets params to be passed to the routed controller action.

View source

Arguments

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

Protected Methods

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

buildRules()

Builds URL rule objects from the given rule declarations.

View source

Arguments

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

Returns

yii\web\UrlRuleInterface – The rule objects built from the given rule declarations

Throws

• yii\base\InvalidConfigException
  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

::: code

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

::: code

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';
});

:::