CUrlManager

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()}.