Class CUrlManager

CUrlManager manages the URLs of Yii Web applications.

It provides URL construction (CUrlManager::createUrl()) as well as parsing (CUrlManager::parseUrl()) functionality.

URLs managed via CUrlManager can be in one of the following two formats, by setting 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 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 setRules rules property as an array of rules (pattern=>route). For example,

array(
    'articles'=>'article/list',
    'article/<id:\d+>/*'=>'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)>/<id:\d+>/<_a:(create|update|delete)>'=>'<_c>/<_a>',
     '<_c:(post|comment)>/<id:\d+>'=>'<_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:<span class="php-comment">//admin.example.com/en/profile</span> 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://<user:\w+>.example.com/<lang:\w+>/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
  '<action:(login|logout)>' => 'site/<action>',
  // 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 CBaseUrlRule and implement the following two methods,

• CBaseUrlRule::createUrl()
• CBaseUrlRule::parseUrl()

CUrlManager is a default application component that may be accessed via CApplication::getUrlManager().