Class yii\web\UrlManager
Inheritance | yii\web\UrlManager » yii\base\Component » yii\base\Object |
---|---|
Implements | yii\base\Configurable |
Available since version | 2.0 |
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/web/UrlManager.php |
UrlManager handles HTTP request parsing and creation of URLs based on a set of rules.
UrlManager is configured as an application component in yii\base\Application by default.
You can access that instance via Yii::$app->urlManager
.
You can modify its configuration by adding an array to your application config under components
as it is shown in the following example:
'urlManager' => [
'enablePrettyUrl' => true,
'rules' => [
// your rules go here
],
// ...
]
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
$baseUrl | string | The base URL that is used by createUrl() to prepend to created URLs. | yii\web\UrlManager |
$behaviors | yii\base\Behavior[] | List of behaviors attached to this component | yii\base\Component |
$cache | yii\caching\Cache|string | The cache object or the application component ID of the cache object. | yii\web\UrlManager |
$enablePrettyUrl | boolean | Whether to enable pretty URLs. | yii\web\UrlManager |
$enableStrictParsing | boolean | Whether to enable strict parsing. | yii\web\UrlManager |
$hostInfo | string | The host info (e.g. "http://www. | yii\web\UrlManager |
$routeParam | string | The GET parameter name for route. | yii\web\UrlManager |
$ruleConfig | array | The default configuration of URL rules. | yii\web\UrlManager |
$rules | array | The rules for creating and parsing URLs when $enablePrettyUrl is true. | yii\web\UrlManager |
$scriptUrl | string | The entry script URL that is used by createUrl() to prepend to created URLs. | yii\web\UrlManager |
$showScriptName | boolean | Whether to show entry script name in the constructed URL. | yii\web\UrlManager |
$suffix | string | The URL suffix used when in 'path' format. | yii\web\UrlManager |
Public Methods
Method | Description | Defined By |
---|---|---|
__call() | Calls the named method which is not a class method. | yii\base\Component |
__clone() | This method is called after the object is created by cloning an existing one. | yii\base\Component |
__construct() | Constructor. | yii\base\Object |
__get() | Returns the value of a component property. | yii\base\Component |
__isset() | Checks if a property is set, i.e. defined and not null. | yii\base\Component |
__set() | Sets the value of a component property. | yii\base\Component |
__unset() | Sets a component property to be null. | yii\base\Component |
addRules() | Adds additional URL rules. | yii\web\UrlManager |
attachBehavior() | Attaches a behavior to this component. | yii\base\Component |
attachBehaviors() | Attaches a list of behaviors to the component. | yii\base\Component |
behaviors() | Returns a list of behaviors that this component should behave as. | yii\base\Component |
canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\Component |
canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\Component |
className() | Returns the fully qualified name of this class. | yii\base\Object |
createAbsoluteUrl() | Creates an absolute URL using the given route and query parameters. | yii\web\UrlManager |
createUrl() | Creates a URL using the given route and query parameters. | yii\web\UrlManager |
detachBehavior() | Detaches a behavior from the component. | yii\base\Component |
detachBehaviors() | Detaches all behaviors from the component. | yii\base\Component |
ensureBehaviors() | Makes sure that the behaviors declared in behaviors() are attached to this component. | yii\base\Component |
getBaseUrl() | Returns the base URL that is used by createUrl() to prepend to created URLs. | yii\web\UrlManager |
getBehavior() | Returns the named behavior object. | yii\base\Component |
getBehaviors() | Returns all behaviors attached to this component. | yii\base\Component |
getHostInfo() | Returns the host info that is used by createAbsoluteUrl() to prepend to created URLs. | yii\web\UrlManager |
getScriptUrl() | Returns the entry script URL that is used by createUrl() to prepend to created URLs. | yii\web\UrlManager |
hasEventHandlers() | Returns a value indicating whether there is any handler attached to the named event. | yii\base\Component |
hasMethod() | Returns a value indicating whether a method is defined. | yii\base\Component |
hasProperty() | Returns a value indicating whether a property is defined for this component. | yii\base\Component |
init() | Initializes UrlManager. | yii\web\UrlManager |
off() | Detaches an existing event handler from this component. | yii\base\Component |
on() | Attaches an event handler to an event. | yii\base\Component |
parseRequest() | Parses the user request. | yii\web\UrlManager |
setBaseUrl() | Sets the base URL that is used by createUrl() to prepend to created URLs. | yii\web\UrlManager |
setHostInfo() | Sets the host info that is used by createAbsoluteUrl() to prepend to created URLs. | yii\web\UrlManager |
setScriptUrl() | Sets the entry script URL that is used by createUrl() to prepend to created URLs. | yii\web\UrlManager |
trigger() | Triggers an event. | yii\base\Component |
Protected Methods
Method | Description | Defined By |
---|---|---|
buildRules() | Builds URL rule objects from the given rule declarations. | yii\web\UrlManager |
Property Details
The base URL that is used by createUrl() to prepend to created URLs.
The cache object or the application component ID of the cache object. Compiled URL rules will be cached through this cache object, if it is available.
After the UrlManager object is created, if you want to change this property, you should only assign it with a cache object. Set this property to false if you do not want to cache the URL rules.
Whether to enable pretty URLs. Instead of putting all parameters in the query string part of a URL, pretty URLs allow using path info to represent some of the parameters and can thus produce more user-friendly URLs, such as "/news/Yii-is-released", instead of "/index.php?r=news/view&id=100".
Whether to enable strict parsing. If strict parsing is enabled, the incoming requested URL must match at least one of the $rules in order to be treated as a valid request. Otherwise, the path info part of the request will be treated as the requested route. This property is used only when $enablePrettyUrl is true.
The host info (e.g. "http://www.example.com") that is used by createAbsoluteUrl() to prepend to created URLs.
The GET parameter name for route. This property is used only if $enablePrettyUrl is false.
The default configuration of URL rules. Individual rule configurations specified via $rules will take precedence when the same property of the rule is configured.
The rules for creating and parsing URLs when $enablePrettyUrl is true. This property is used only if $enablePrettyUrl is true. Each element in the array is the configuration array for creating a single URL rule. The configuration will be merged with $ruleConfig first before it is used for creating the rule object.
A special shortcut format can be used if a rule only specifies pattern
and route: 'pattern' => 'route'
. That is, instead of using a configuration
array, one can use the key to represent the pattern and the value the corresponding route.
For example, 'post/<id:\d+>' => 'post/view'
.
For RESTful routing the mentioned shortcut format also allows you to specify the
HTTP verb that the rule should apply for.
You can do that by prepending it to the pattern, separated by space.
For example, 'PUT post/<id:\d+>' => 'post/update'
.
You may specify multiple verbs by separating them with comma
like this: 'POST,PUT post/index' => 'post/create'
.
The supported verbs in the shortcut format are: GET, HEAD, POST, PUT, PATCH and DELETE.
Note that mode will be set to PARSING_ONLY when specifying verb in this way
so you normally would not specify a verb for normal GET request.
Here is an example configuration for RESTful CRUD controller:
[
'dashboard' => 'site/index',
'POST <controller:\w+>s' => '<controller>/create',
'<controller:\w+>s' => '<controller>/index',
'PUT <controller:\w+>/<id:\d+>' => '<controller>/update',
'DELETE <controller:\w+>/<id:\d+>' => '<controller>/delete',
'<controller:\w+>/<id:\d+>' => '<controller>/view',
];
Note that if you modify this property after the UrlManager object is created, make sure you populate the array with rule objects instead of rule configurations.
The entry script URL that is used by createUrl() to prepend to created URLs.
Whether to show entry script name in the constructed URL. Defaults to true. This property is used only if $enablePrettyUrl is true.
The URL suffix used when in 'path' format. For example, ".html" can be used so that the URL looks like pointing to a static HTML page. This property is used only if $enablePrettyUrl is true.
Method Details
Adds additional URL rules.
This method will call buildRules() to parse the given rule declarations and then append or insert them to the existing $rules.
Note that if $enablePrettyUrl is false, this method will do nothing.
void addRules( $rules, $append = true ) | ||
$rules | array | The new rules to be added. Each array element represents a single rule declaration. Please refer to $rules for the acceptable rule format. |
$append | boolean | Whether to add the new rules by appending them to the end of the existing rules. |
Builds URL rule objects from the given rule declarations.
yii\web\UrlRuleInterface[] buildRules( $rules ) | ||
$rules | array | The rule declarations. Each array element represents a single rule declaration. Please refer to $rules for the acceptable rule formats. |
return | yii\web\UrlRuleInterface[] | The rule objects built from the given rule declarations |
---|---|---|
throws | yii\base\InvalidConfigException | if a rule declaration is invalid |
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.
See also createUrl().
string createAbsoluteUrl( $params, $scheme = null ) | ||
$params | string|array | Use a string to represent a route (e.g. |
$scheme | string | The scheme to use for the url (either |
return | string | The created URL |
---|
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/index¶m1=value1¶m2=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/index¶m1=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.
string createUrl( $params ) | ||
$params | string|array | Use a string to represent a route (e.g. |
return | string | The created URL |
---|
Returns the base URL that is used by createUrl() to prepend to created URLs.
It defaults to yii\web\Request::$baseUrl. This is mainly used when $enablePrettyUrl is true and $showScriptName is false.
string getBaseUrl( ) | ||
return | string | The base URL that is used by createUrl() to prepend to created URLs. |
---|---|---|
throws | yii\base\InvalidConfigException | if running in console application and $baseUrl is not configured. |
Returns the host info that is used by createAbsoluteUrl() to prepend to created URLs.
string getHostInfo( ) | ||
return | string | The host info (e.g. "http://www.example.com") that is used by createAbsoluteUrl() to prepend to created URLs. |
---|---|---|
throws | yii\base\InvalidConfigException | if running in console application and $hostInfo is not configured. |
Returns the entry script URL that is used by createUrl() to prepend to created URLs.
It defaults to yii\web\Request::$scriptUrl. This is mainly used when $enablePrettyUrl is false or $showScriptName is true.
string getScriptUrl( ) | ||
return | string | The entry script URL that is used by createUrl() to prepend to created URLs. |
---|---|---|
throws | yii\base\InvalidConfigException | if running in console application and $scriptUrl is not configured. |
Initializes UrlManager.
void init( ) |
Parses the user request.
array|boolean parseRequest( $request ) | ||
$request | yii\web\Request | The request component |
return | 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. |
---|
Sets the base URL that is used by createUrl() to prepend to created URLs.
This is mainly used when $enablePrettyUrl is true and $showScriptName is false.
void setBaseUrl( $value ) | ||
$value | string | The base URL that is used by createUrl() to prepend to created URLs. |
Sets the host info that is used by createAbsoluteUrl() to prepend to created URLs.
void setHostInfo( $value ) | ||
$value | string | The host info (e.g. "http://www.example.com") that is used by createAbsoluteUrl() to prepend to created URLs. |
Sets the entry script URL that is used by createUrl() to prepend to created URLs.
This is mainly used when $enablePrettyUrl is false or $showScriptName is true.
void setScriptUrl( $value ) | ||
$value | string | The entry script URL that is used by createUrl() to prepend to created URLs. |