php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-11-16 22:39:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update url.md

Browse Source 
Documentation updates
This commit is contained in:
Aris Karageorgos
2014-01-29 11:07:19 +07:00
parent bad5a1199f
commit 49704ff37b
1 changed files with 36 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/guide/url.md
View File

@@ -1,35 +1,33 @@
URL Management
==============
The concept of URL management in Yii fairly simple. URL management is based on the premise that the application uses
internal routes and parameters everywhere. The framework itself will then translates routes into URLs, and translate URLs
into routes, according to the URL manager's configuration. This approach allows you to change site-wide URLs merely by
editing a single config file, without ever touching the application code.
The concept of URL management in Yii is fairly simple. URL management is based on the premise that the application uses
internal routes and parameters everywhere. The framework itself will then translate routes into URLs, and vice vera, 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 the application code.
Internal route
Internal routes
--------------
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`.
In the former, `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 controller belongs to a *module*, the
internal route is prefixed with the module ID, such as `blog/post/index` for a blog module (with `post` being the
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`.
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
internal route is prefixed with the module ID. For example `blog/post/index` for a blog module (with `post` being the
controller ID and `index` being the action ID).
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 an
application component with the `urlManager` ID. This component is accessible both from web and console applications via
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
`\Yii::$app->urlManager`. The component makes availabe the two following URL creation methods:
- `createUrl($route, $params = [])`
- `createAbsoluteUrl($route, $params = [])`
The `createUrl` method creates a URL relative to the application root, such as `/index.php/site/index/`.
The `createAbsoluteUrl` method creates URL prefixed with the proper protocol and hostname:
The `createAbsoluteUrl` method creates a URL prefixed 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
is used when you need to create rules for outside the website, such as when sending emails or generating an RSS feed.
is used when you need to create URLs for external resources, such as connecting to third party services, sending email, generating RSS feeds etc.
Some examples:
@@ -42,7 +40,7 @@ echo \Yii::$app->urlManager->createAbsoluteUrl('blog/post/index');
// http://www.example.com/index.php/blog/post/index/
```
The exact format of the outputted URL will depend upon how the URL manager is configured (which is the point). The above
The exact format of the URL depends on how the URL manager is configured. The above
examples may also output:
* `/site/page/id/about/`
@@ -52,7 +50,7 @@ examples may also output:
* `http://www.example.com/blog/post/index/`
* `http://www.example.com/index.php?r=blog/post/index`
Inside a web application controller, you can use the controller's own `createUrl` shortcut method. Unlike the global
Inside a web application controller, you can use the controller's `createUrl` shortcut method. Unlike the global
`createUrl` method, the controller version is context sensitive:
```php
@@ -71,7 +69,7 @@ Customizing URLs
----------------
By default, Yii uses a query string format for URLs, such as `/index.php?r=news/view&id=100`. In order to make URLs
human-friendly (i.e., more readable), you need to configure the `urlManager` component in the application's configuration
human-friendly i.e., more readable, you need to configure the `urlManager` component in the application's configuration
file. Enabling "pretty" URLs will convert the query string format to a directory-based format: `/index.php/news/view?id=100`.
Disabling the `showScriptName` parameter means that `index.php` will not be part of the URLs. Here's the relevant part of
the application's configuration file:
@@ -94,15 +92,14 @@ Note that this configuration will only work if the web server has been properly
### Named parameters
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:
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:
```
<ParameterName:ParameterPattern>
```
`ParameterName` is a name of a GET parameter, and the optional `ParameterPattern` is the regular expression that should
be used to match the value of the GET parameter. In case when `ParameterPattern` is omitted, it means the parameter
`ParameterName` is a name of a `GET` parameter, and the optional `ParameterPattern` is the regular expression that should
be used to match the value of the `GET` parameter. In case `ParameterPattern` is omitted, it means the parameter
should match any characters except `/`. 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.
@@ -123,17 +120,13 @@ Let's use some examples to explain how URL rules work. We assume that our rule s
- Calling `$this->createUrl('post/read')` generates `/index.php/post/read`. None of the rules is applied, convention is used
instead.
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
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', ['id' => 100, 'year' => 2008])`, we would
obtain `/index.php/post/100?year=2008`.
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', ['id' => 100, 'year' => 2008])`, we will obtain `/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 `['id' => 100]` (accessible via
As we mentioned earlier, 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 `['id' => 100]` (accessible via
`Yii::$app->request->getQueryParam('id')`).
### Parameterizing Routes
@@ -152,17 +145,15 @@ We use the following example rules to illustrate how to parameterize routes with
]
```
In the above, 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, 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.
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`.
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`.
### Parameterizing hostnames
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 that is especially useful for handling subdomains. For example, the URL
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
`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.
@@ -174,15 +165,14 @@ In order to use parameterized hostnames, simply declare URL rules with host info
]
```
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.
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.
Note that [[UrlManager::showScriptName]] will not take effect when a URL is being created using a rule with parameterized
hostname.
Note that [[UrlManager::showScriptName]] will not take effect when a URL is being created using a rule with a parameterized hostname.
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`.
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
should still use the same URL rule as described above without the subfolder `sandbox/blog`.
### Faking URL Suffix
@@ -206,13 +196,11 @@ TBD: [[\yii\web\VerbFiler]]
URL parsing
-----------
Complimentary to creating URLs Yii is handling transforming custom URLs back into internal route and parameters.
Complimentary to creating URLs Yii also handles transforming custom URLs back into internal routes and parameters.
### Strict URL parsing
By default if there's no custom rule for URL and URL matches default format such as `/site/page` Yii tries to run a
corresponding controller's action. This behavior could be disabled so if there's no custom rule match, a 404 not found
error will be produced immediately.
By default if there's no custom rule for a URL and the URL matches the default format such as `/site/page`, Yii tries to run the corresponding controller's action. This behavior can be disabled so if there's no custom rule match, a 404 not found error will be produced immediately.
```php
<?php
@@ -230,7 +218,7 @@ Creating your own rule classes
------------------------------
[[\yii\web\UrlRule]] class is used for both parsing URL into parameters and creating URL based on parameters. Despite
the fact that default implementation is flexible enough for majority of projects, there could be a situation when using
the fact that default implementation is flexible enough for the majority of projects, there are situations when using
your own rule class is the best choice. 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 default rule
class will not work because it mostly relies on statically declared regular expressions which have no database knowledge.