When a user request comes in terms of a URL, the application needs to parse
it into understandable parameters.

The application needs to provide a way of creating URLs so that the
created URLs can be understood by the application.

For a Yii application, these are accomplished with the help of CUrlManager.

Note: You can specify URLs without using Yii but it is not recommended
since you will not be able to easily change URLs via configuration without
touching application code or to achieve application portability.

Although URLs can be hardcoded in controller views, it is often more
flexible to create them dynamically:

$url=$this->createUrl($route,$params);

where $this refers to the controller instance; $route specifies the
route of the request; and $params
is a list of GET parameters to be appended to the URL.

By default, URLs created by createUrl is in the
so-called get format. For example, given $route='post/read' and
$params=array('id'=>100), we would obtain the following URL:

/index.php?r=post/read&id=100

where parameters appear in the query string as a list of Name=Value
concatenated with the ampersand characters, and the r parameter specifies
the request route. This URL format
is not very user-friendly because it requires several non-word characters.

Tip: In order to generate URL with a hashtag, for example
/index.php?r=post/read&id=100#title, you need to specify parameter named #
using $this->createUrl('post/read',array('id'=>100,'#'=>'title')).

We could make the above URL look cleaner and more self-explanatory by
using the so-called path format which eliminates the query string and
puts the GET parameters into the path info part of URL:

/index.php/post/read/id/100

To change the URL format, we should configure the
urlManager application component so that
createUrl can automatically switch to the new
format and the application can properly understand the new URLs:

When path is used as the URL format, we can specify some URL rules to
make our URLs even more user-friendly. For example, we can generate a URL
as short as /post/100, instead of the lengthy
/index.php/post/read/id/100. URL rules are used by CUrlManager for both
URL creation and parsing purposes.

To specify URL rules, we need to configure the rules
property of the urlManager application
component:

The rules are specified as an array of pattern-route pairs, each
corresponding to a single rule. The pattern of a rule is a string
used to match the path info part of URLs. And the route of a rule
should refer to a valid controller route.

Besides the above pattern-route format, a rule may also be specified
with customized options, like the following:

defaultParams: the default GET parameters (name=>value) that this rule provides.
When this rule is used to parse the incoming request, the values declared in this property
will be injected into $_GET.

matchValue: whether the GET parameter values should match the corresponding
sub-patterns in the rule when creating a URL. Defaults to null,
meaning using the value of CUrlManager::matchValue. If this property is false, it means
a rule will be used for creating a URL 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.

verb: the HTTP verb (e.g. GET, POST, DELETE) that this rule must match
in order to be used for parsing the current request. Defaults to null, meaning the rule can match any HTTP verb.
If a rule can match multiple verbs, they must be separated by commas. When a rule does not match
the specified verb(s), it will be skipped during the request parsing process. This option is only
used for request parsing. This option is provided mainly for RESTful URL support.
This option has been available since version 1.1.7.

parsingOnly: whether the rule is used for parsing request only.
Defaults to false, meaning a rule is used for both URL parsing and creation.
This option has been available since version 1.1.7.

A rule can be associated with a few GET parameters. These GET parameters
appear in the rule's pattern as special tokens in the following format:

<ParamName:ParamPattern>

where ParamName specifies the name of a GET parameter, and the optional
ParamPattern specifies the regular expression that should be used to
match the value of the GET parameter. In case when ParamPattern is omitted,
it means the parameter should match any characters except the slash /.
When creating a URL, these parameter
tokens will be replaced with the corresponding parameter values; when
parsing a URL, the corresponding GET parameters will be populated with the
parsed results.

Let's use some examples to explain how URL rules work. We assume that our
rule set consists of three rules:

Calling $this->createUrl('post/read') generates
/index.php/post/read. None of the rules is applied.

In summary, when using createUrl to generate a
URL, the route and the GET parameters passed to the method are used to
decide which URL rule to be applied. If every parameter associated with a
rule can be found in the GET parameters passed to
createUrl, and if the route of the rule also
matches the route parameter, the rule will be used to generate the URL.

If the GET parameters passed to createUrl are
more than those required by a rule, the additional parameters will appear
in the query string. For example, if we call
$this->createUrl('post/read',array('id'=>100,'year'=>2008)), we would
obtain /index.php/post/100?year=2008. In order to make these additional
parameters appear in the path info part, we should append /* to the rule.
Therefore, with the rule post/<id:\d+>/*, we can obtain the URL as
/index.php/post/100/year/2008.

As we mentioned, the other purpose of URL rules is to parse the requesting
URLs. Naturally, this is an inverse process of URL creation. For example,
when a user requests for /index.php/post/100, the second rule in the
above example will apply, which resolves in the route post/read and the
GET parameter array('id'=>100) (accessible via $_GET).

Note: Using URL rules will degrade application performance. This is
because when parsing the request URL, CUrlManager will attempt to match
it with each rule until one can be applied. The more the number of rules,
the more the performance impact. Therefore, a high-traffic Web
application should minimize its use of URL rules.

We may reference named parameters in the route part
of a rule. This allows a rule to be applied to multiple routes based on matching
criteria. It may also help reduce the number of rules needed for an application,
and thus improve the overall performance.

We use the following example rules to illustrate how to parameterize routes
with named parameters:

In the above, we use two named parameters in the route part of the rules:
_c and _a. The former matches a controller ID to be either post or comment,
while the latter matches an action ID to be create, update or delete.
You may name the parameters differently as long as they do not conflict with
GET parameters that may appear in URLs.

Using the above rules, the URL /index.php/post/123/create
would be parsed as the route post/create with GET parameter id=123.
And given the route comment/list and GET parameter page=2, we can create a URL
/index.php/comments?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.:

The above example says that the first segment in the hostname should be treated as user
parameter while the first segment in the path info should be lang parameter. The rule
corresponds to the user/profile route.

Also note that the rule with parameterized hostname should NOT contain the sub-folder
if the application is under a sub-folder of the Web root. For example, if the application
is under http://www.example.com/sandbox/blog, then we should still use the same URL rule
as described above without the sub-folder sandbox/blog.

There is one more thing that we can do to further clean our URLs, i.e.,
hiding the entry script index.php in the URL. This requires us to
configure the Web server as well as the
urlManager application component.

We first need to configure the Web server so that a URL without the entry
script can still be handled by the entry script. For Apache HTTP
server, this can be done by turning on the URL
rewriting engine and specifying some rewriting rules. We can create
the file /wwwroot/blog/.htaccess with the following content.
Note that the same content can also be put in the Apache configuration
file within the Directory element for /wwwroot/blog.

RewriteEngine on
# if a directory or a file exists, use it directly
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# otherwise forward it to index.php
RewriteRule . index.php

We may also add some suffix to our URLs. For example, we can have
/post/100.html instead of /post/100. This makes it look more like a URL
to a static Web page. To do so, simply configure the
urlManager component by setting its
urlSuffix property to the suffix you like.

Note: Using custom URL rule classes has been supported since version 1.1.8.

By default, each URL rule declared with CUrlManager is represented as
a CUrlRule object which performs the task of parsing requests and creating URLs
based on the rule specified. While CUrlRule is flexible enough to handle most
URL formats, sometimes we still want to enhance it with special features.

For example, in a car dealer website, we may want to support the URL format like
/Manufacturer/Model, where Manufacturer and Model must both match some data in
a database table. The CUrlRule class will not work because it mostly relies
on statically declared regular expressions which have no database knowledge.

We can write a new URL rule class by extending from CBaseUrlRule and use it in one
or multiple URL rules. Using the above car dealer website as an example,
we may declare the following URL rules,

In the above, we use the custom URL rule class CarUrlRule to handle
the URL format /Manufacturer/Model. The class can be written like the following:

classCarUrlRuleextendsCBaseUrlRule{public$connectionID = 'db';
publicfunctioncreateUrl($manager,$route,$params,$ampersand){if($route==='car/index'){if(isset($params['manufacturer'], $params['model']))return$params['manufacturer'] . '/' . $params['model'];
elseif(isset($params['manufacturer']))return$params['manufacturer'];
}returnfalse; // this rule does not apply}publicfunctionparseUrl($manager,$request,$pathInfo,$rawPathInfo){if(preg_match('%^(\w+)(/(\w+))?$%', $pathInfo, $matches)){// check $matches[1] and $matches[3] to see// if they match a manufacturer and a model in the database// If so, set $_GET['manufacturer'] and/or $_GET['model']// and return 'car/index'}returnfalse; // this rule does not apply}}

The custom URL class must implement the two abstract methods declared in CBaseUrlRule:

Besides the above typical usage, custom URL rule classes can also be implemented
for many other purposes. For example, we can write a rule class to log the URL parsing
and creation requests. This may be useful during development stage. We can also
write a rule class to display a special 404 error page in case all other URL rules fail
to resolve the current request. Note that in this case, the rule of this special class
must be declared as the last rule.