The concept of URL management in Yii is fairly simple. URL management is based on the premise that the application uses
The concept of *URL management* in Yii is fairly simple: the application simply uses internal routes and parameters everywhere. The framework itself will then translate routes into URLs, and vice versa, according to the URL manager's configuration. This approach allows you to make site-wide changes to URLs merely by
internal routes and parameters everywhere. The framework itself will then translate routes into URLs, and vice versa, according to the URL manager's configuration. This approach allows you to change site-wide URLs merely by
editing a single configuration file, without ever touching any application code.
editing a single configuration file, without ever touching the application code.
Internal routes
Internal Routes
---------------
---------------
When implementing an application using Yii, you'll deal with internal routes, often referred to as routes and parameters.
When implementing an application using Yii, you'll deal with *internal* routes, often referred to as "routes and parameters".
Each controller and controller action has a corresponding internal route such as `site/index` or `user/create`.
Each controller and controller action has a corresponding internal route, such as `site/index` or `user/create`.
In the first example, `site` is referred to as the *controller ID* while `index` is referred to as the *action ID*. In the
second example, `user` is the controller ID and `create` is the action ID. If the controller belongs to a *module*, the
In the first example, `site` is the *controller ID*, while `index` is the *action ID*. In the
internal route is prefixed with the module ID. For example `blog/post/index` for a blog module (with `post` being the
second example, `user` is the controller ID and `create` is the action ID.
controller ID and `index` being the action ID).
If the controller belongs to a *module*, the
internal route is prefixed with the module ID: for example, `blog/post/index` represents a blog module, the module's `post`
controller, and the `index` action.
Creating URLs
Creating URLs
-------------
-------------
The most important rule for creating URLs in your site is to always do so using the URL manager. The URL manager is a built-in application component named `urlManager`. This component is accessible from both web and console applications via
The most important rule for creating URLs in your site is to always do so through the URL manager. The URL manager is a built-in application component fittingly named `urlManager`. This component is accessible from both web and console applications via
`\Yii::$app->urlManager`. The component makes available the two following URL creation methods:
`\Yii::$app->urlManager`. The component makes available two methods for creating URLs:
-`createUrl($params)`
-`createUrl($params)`
-`createAbsoluteUrl($params, $schema = null)`
-`createAbsoluteUrl($params, $schema = null)`
The `createUrl` method creates an URL relative to the application root, such as `/index.php/site/index/`.
The `createUrl` method creates an URL relative to the application root, such as `/index.php/site/index/`.
The `createAbsoluteUrl` method creates an URL prefixed with the proper protocol and hostname:
The `createAbsoluteUrl` method creates an URL that beings with with the proper protocol and hostname:
`http://www.example.com/index.php/site/index`. The former is suitable for internal application URLs, while the latter
`http://www.example.com/index.php/site/index`. Relative URLs, and the `createUrl` method are suitable for internal application URLs, while absolute URLs, and the `createAbsoluteUrl` method, are appropriate when you need to create URLs for external resources, such as connecting to third party services, sending email,
is used when you need to create URLs for external resources, such as connecting to third party services, sending email,
generating RSS feeds, etc.
generating RSS feeds etc.
Both methods can be passed parameters used to further customize the URL, such as appending values to pass along as part of the request.
In order to simplify URL creation there is [[yii\helpers\Url]] helper. Assuming we're at `/index.php?r=management/default/users&id=10` the following
In order to simplify URL creation, Yii has the [[yii\helpers\Url]] helper. Assuming the current URL is `/index.php?r=management/default/users&id=10`, the following
`/index.php/post/2008/a%20sample%20post`. The third rule is applied.
`/index.php/post/2008/a%20sample%20post`. The third rule is applied.
- Calling `Url::toRoute('post/read')` generates `/index.php/post/read`. None of the rules is applied, convention is used
- Calling `Url::toRoute('post/read')` generates `/index.php/post/read`. None of the rules is applied; convention is used instead.
instead.
In summary, when using `createUrl` to generate a URL, the route and the `GET` parameters passed to the method are used to
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
decide which URL rule will 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.
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 `Url::toRoute` are more than those required by a rule, the additional parameters will
If the `GET` parameters passed to `Url::toRoute` are more than those required by a rule, the additional parameters will
appear in the query string. For example, if we call `Url::toRoute(['post/read', 'id' => 100, 'year' => 2008])`, we will
appear in the query string. For example, the call `Url::toRoute(['post/read', 'id' => 100, 'year' => 2008])`, will
obtain`/index.php/post/100?year=2008`.
generate`/index.php/post/100?year=2008`.
As we mentioned earlier, the other purpose of URL rules is to parse the requesting URLs. Naturally, this is an inverse
As mentioned earlier, the other purpose of URL rules is to parse the requesting URLs. Naturally, this is the inverse of URL creation. For example, when a user requests for `/index.php/post/100`, the second rule in the above example
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 to the route `post/read` with the `GET` parameter `['id' => 100]` (accessible via
will apply, which resolves in the route `post/read` and the `GET` parameter `['id' => 100]` (accessible via
`Yii::$app->request->get('id')`).
`Yii::$app->request->get('id')`).
### Parameterizing Routes
### Parameterizing Routes
We may reference named parameters in the route part of a rule. This allows a rule to be applied to multiple routes based
Rules may also make use of named parameters as part of a route. Named parameters allow 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
on matching criteria. Named parameters may also help reduce the number of rules needed for an application, and thus improve the overall
performance.
performance.
We use the following example rules to illustrate how to parameterize routes with named parameters:
The following example rules illustrate how to parameterize routes with named parameters:
```php
```php
[
[
...
@@ -205,19 +207,19 @@ We use the following example rules to illustrate how to parameterize routes with
...
@@ -205,19 +207,19 @@ We use the following example rules to illustrate how to parameterize routes with
]
]
```
```
In the above example, we use two named parameters in the route part of the rules: `controller` and `action`. 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.
In the above example, two named parameters are found in the route part of the rules: `controller` and `action`. The former matches a controller ID that's either "post" or "comment", while the latter matches an action ID that could be "create", "update", or "delete". You may name the parameters differently as long as they do not conflict with any GET parameters that may appear in your URLs.
Using the above rules, the URL `/index.php/post/123/create` will be parsed as the route `post/create` with `GET` parameter
Using the above rules, the URL `/index.php/post/123/create` will be parsed as the route `post/create` with `GET` parameter
`id=123`. Given the route `comment/list` and `GET` parameter `page=2`, we can create a URL `/index.php/comments?page=2`.
`id=123`. Given the route `comment/list` and `GET` parameter `page=2`, Yii can create a URL `/index.php/comments?page=2`.
### Parameterizing hostnames
### Parameterizing Hostnames
It is also possible to include hostnames in the rules for parsing and creating URLs. One may extract part of the hostname
It is also possible to include hostnames in the rules for parsing and creating URLs. One may extract part of the hostname
to be a `GET` parameter. This is especially useful for handling subdomains. For example, the URL
to be a `GET` parameter. This is especially useful for handling subdomains. 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,
`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.
rules with hostnames 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.:
In order to use parameterized hostnames, simply declare the URL rules while including the host info:
```php
```php
[
[
...
@@ -225,13 +227,13 @@ In order to use parameterized hostnames, simply declare URL rules with host info
...
@@ -225,13 +227,13 @@ In order to use parameterized hostnames, simply declare URL rules with host info
]
]
```
```
In the above example the first segment of the hostname is treated as the user parameter while the first segment
In the above example, the first segment of the hostname is treated as the "user" parameter while the first segment
of the path info is treated as the lang parameter. The rule corresponds to the `user/profile` route.
of the pat is treated as the "lang" parameter. The rule corresponds to the `user/profile` route.
Note that [[yii\web\UrlManager::showScriptName]] will not take effect when a URL is being created using a rule with a parameterized hostname.
Note that [[yii\web\UrlManager::showScriptName]] will not take effect when a URL is being created using a rule with a parameterized hostname.
Also note that any rule with a parameterized hostname should NOT contain the subfolder if the application is under
Also note that any rule with a parameterized hostname should NOT contain the subfolder if the application is under
a subfolder of the Web root. For example, if the application is under `http://www.example.com/sandbox/blog`, then we
a subfolder of the web root. For example, if the application is under `http://www.example.com/sandbox/blog`, then you
should still use the same URL rule as described above without the subfolder `sandbox/blog`.
should still use the same URL rule as described above without the subfolder `sandbox/blog`.
