CUrlManager

NameurlManager
ClassCUrlManager
Location/home/vhosts/app-manager.eu5.org/framework/web/CUrlManager.php
CUrlManager manages the URLs of Yii Web applications.

It provides URL construction ({@link createUrl()}) as well as parsing ({@link parseUrl()}) functionality. URLs managed via CUrlManager can be in one of the following two formats, by setting {@link setUrlFormat urlFormat} property:
  • 'path' format: /path/to/EntryScript.php/name1/value1/name2/value2...
  • 'get' format: /path/to/EntryScript.php?name1=value1&name2=value2...
When using 'path' format, CUrlManager uses a set of {@link setRules rules} to:
  • parse the requested URL into a route ('ControllerID/ActionID') and GET parameters;
  • create URLs based on the given route and GET parameters.
A rule consists of a route and a pattern. The latter is used by CUrlManager to determine which rule is used for parsing/creating URLs. A pattern is meant to match the path info part of a URL. It may contain named parameters using the syntax '<ParamName:RegExp>'. When parsing a URL, a matching rule will extract the named parameters from the path info and put them into the $_GET variable; when creating a URL, a matching rule will extract the named parameters from $_GET and put them into the path info part of the created URL. If a pattern ends with '/*', it means additional GET parameters may be appended to the path info part of the URL; otherwise, the GET parameters can only appear in the query string part. To specify URL rules, set the {@link setRules rules} property as an array of rules (pattern=>route). For example,
array(
    'articles'=>'article/list',
    'article//*'=>'article/read',
)
Two rules are specified in the above:
  • The first rule says that if the user requests the URL '/path/to/index.php/articles', it should be treated as '/path/to/index.php/article/list'; and vice versa applies when constructing such a URL.
  • The second rule contains a named parameter 'id' which is specified using the <ParamName:RegExp> syntax. It says that if the user requests the URL '/path/to/index.php/article/13', it should be treated as '/path/to/index.php/article/read?id=13'; and vice versa applies when constructing such a URL.
The route part may contain references to named parameters defined in the pattern part. This allows a rule to be applied to different routes based on matching criteria. For example,
array(
     '<_c:(post|comment)>//<_a:(create|update|delete)>'=>'<_c>/<_a>',
     '<_c:(post|comment)>/'=>'<_c>/view',
     '<_c:(post|comment)>s/*'=>'<_c>/list',
)
In the above, we use two named parameters '<_c>' and '<_a>' in the route part. The '<_c>' parameter matches either 'post' or 'comment', while the '<_a>' parameter matches an action ID. Like normal rules, these rules can be used for both parsing and creating URLs. For example, using the rules above, the URL '/index.php/post/123/create' would be parsed as the route 'post/create' with GET parameter 'id' being 123. And given the route 'post/list' and GET parameter 'page' being 2, we should get a URL '/index.php/posts/page/2'. It is also possible to include hostname into the rules for parsing and creating URLs. One may extract part of the hostname to be a GET parameter. For example, the URL http://admin.example.com/en/profile may be parsed into GET parameters user=admin and lang=en. On the other hand, rules with hostname may also be used to create URLs with parameterized hostnames. In order to use parameterized hostnames, simply declare URL rules with host info, e.g.:
array(
    'http://.example.com//profile' => 'user/profile',
)
Starting from version 1.1.8, one can write custom URL rule classes and use them for one or several URL rules. For example,
array(
  // a standard rule
  '' => 'site/',
  // a custom rule using data in DB
  array(
    'class' => 'application.components.MyUrlRule',
    'connectionID' => 'db',
  ),
)
Please note that the custom URL rule class should extend from {@link CBaseUrlRule} and implement the following two methods,
  • {@link CBaseUrlRule::createUrl()}
  • {@link CBaseUrlRule::parseUrl()}
CUrlManager is a default application component that may be accessed via {@link CWebApplication::getUrlManager()}.

Options

Displaying 1-10 of 13 results.
NameValueDescriptionType
rulesarray()The URL rules (pattern=>route).array
urlSuffix''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. Defaults to empty.string
showScriptNametrueWhether to show entry script name in the constructed URL. Defaults to true.boolean
appendParamstrueWhether to append GET parameters to the path info part. Defaults to true. This property is only effective when {@link urlFormat} is 'path' and is mainly used when creating URLs. When it is true, GET parameters will be appended to the path info and separate from each other using slashes. If this is false, GET parameters will be in query part.boolean
routeVar'r'The GET variable name for route. Defaults to 'r'.string
caseSensitivetrueWhether routes are case-sensitive. Defaults to true. By setting this to false, the route in the incoming request will be turned to lower case first before further processing. As a result, you should follow the convention that you use lower case when specifying controller mapping ({@link CWebApplication::controllerMap}) and action mapping ({@link CController::actions}). Also, the directory names for organizing controllers should be in lower case.boolean
matchValuefalseWhether the GET parameter values should match the corresponding sub-patterns in a rule before using it to create a URL. Defaults to false, meaning a rule will be used for creating a URL only if its route and parameter names match the given ones. If this property is set true, then the given parameter values must also match the corresponding parameter sub-patterns. Note that setting this property to true will degrade performance. @since 1.1.0boolean
cacheID'cache'The ID of the cache application component that is used to cache the parsed URL rules. Defaults to 'cache' which refers to the primary cache application component. Set this property to false if you want to disable caching URL rules.string
useStrictParsingfalseWhether to enable strict URL parsing. This property is only effective when {@link urlFormat} is 'path'. If it is set true, then an incoming URL must match one of the {@link rules URL rules}. Otherwise, it will be treated as an invalid request and trigger a 404 HTTP exception. Defaults to false.boolean
urlRuleClass'CUrlRule'The class name or path alias for the URL rule instances. Defaults to 'CUrlRule'. If you change this to something else, please make sure that the new class must extend from {@link CBaseUrlRule} and have the same constructor signature as {@link CUrlRule}. It must also be serializable and autoloadable. @since 1.1.8string