CUrlManager
| 包 | system.web |
|---|---|
| 继承 | class CUrlManager » CApplicationComponent » CComponent |
| 实现 | IApplicationComponent |
| 可用自 | 1.0 |
| 版本 | $Id$ |
CUrlManager manages the URLs of Yii Web applications.
It provides URL construction (createUrl()) as well as parsing (parseUrl()) functionality.
URLs managed via CUrlManager can be in one of the following two formats, by setting urlFormat property:
When using 'path' format, CUrlManager uses a set of rules to:
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 rules property as an array of rules (pattern=>route). For example,
Starting from version 1.0.5, 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,
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'.
CUrlManager is a default application component that may be accessed via CWebApplication::getUrlManager().
It provides URL construction (createUrl()) as well as parsing (parseUrl()) functionality.
URLs managed via CUrlManager can be in one of the following two formats, by setting 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 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 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.
Starting from version 1.0.5, 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+>'=>'<_a>/view',
'<_c:(post|comment)>s/*'=>'<_a>/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'.
CUrlManager is a default application component that may be accessed via CWebApplication::getUrlManager().
公共属性
| 属性 | 类型 | 描述 | 被定义在 |
|---|---|---|---|
| appendParams | boolean | whether to append GET parameters to the path info part. | CUrlManager |
| baseUrl | string | the base URL of the application (the part after host name and before query string). | CUrlManager |
| behaviors | array | the behaviors that should be attached to this component. | CApplicationComponent |
| cacheID | string | the ID of the cache application component that is used to cache the parsed URL rules. | CUrlManager |
| caseSensitive | boolean | whether routes are case-sensitive. | CUrlManager |
| isInitialized | boolean | whether this application component has been initialized (i. | CApplicationComponent |
| routeVar | string | the GET variable name for route. | CUrlManager |
| rules | array | the URL rules (pattern=>route). | CUrlManager |
| showScriptName | boolean | whether to show entry script name in the constructed URL. | CUrlManager |
| urlFormat | string | the URL format. | CUrlManager |
| urlSuffix | string | the URL suffix used when in 'path' format. | CUrlManager |
| useStrictParsing | boolean | whether to enable strict URL parsing. | CUrlManager |
公共方法
| 方法 | 描述 | 被定义在 |
|---|---|---|
| __call() | Calls the named method which is not a class method. | CComponent |
| __get() | Returns a property value, an event handler list or a behavior based on its name. | CComponent |
| __isset() | Checks if a property value is null. | CComponent |
| __set() | Sets value of a component property. | CComponent |
| __unset() | Sets a component property to be null. | CComponent |
| asa() | Returns the named behavior object. | CComponent |
| attachBehavior() | Attaches a behavior to this component. | CComponent |
| attachBehaviors() | Attaches a list of behaviors to the component. | CComponent |
| attachEventHandler() | Attaches an event handler to an event. | CComponent |
| canGetProperty() | Determines whether a property can be read. | CComponent |
| canSetProperty() | Determines whether a property can be set. | CComponent |
| createPathInfo() | Creates a path info based on the given parameters. | CUrlManager |
| createUrl() | Constructs a URL. | CUrlManager |
| detachBehavior() | Detaches a behavior from the component. | CComponent |
| detachBehaviors() | Detaches all behaviors from the component. | CComponent |
| detachEventHandler() | Detaches an existing event handler. | CComponent |
| disableBehavior() | Disables an attached behavior. | CComponent |
| disableBehaviors() | Disables all behaviors attached to this component. | CComponent |
| enableBehavior() | Enables an attached behavior. | CComponent |
| enableBehaviors() | Enables all behaviors attached to this component. | CComponent |
| getBaseUrl() | CUrlManager | |
| getEventHandlers() | Returns the list of attached event handlers for an event. | CComponent |
| getIsInitialized() | CApplicationComponent | |
| getUrlFormat() | CUrlManager | |
| hasEvent() | Determines whether an event is defined. | CComponent |
| hasEventHandler() | Checks whether the named event has attached handlers. | CComponent |
| hasProperty() | Determines whether a property is defined. | CComponent |
| init() | Initializes the application component. | CUrlManager |
| parsePathInfo() | Parses a path info into URL segments and saves them to $_GET and $_REQUEST. | CUrlManager |
| parseUrl() | Parses the user request. | CUrlManager |
| raiseEvent() | Raises an event. | CComponent |
| removeUrlSuffix() | Removes the URL suffix from path info. | CUrlManager |
| setUrlFormat() | CUrlManager |
受保护的方法
| 方法 | 描述 | 被定义在 |
|---|---|---|
| createUrlDefault() | Contructs a URL based on default settings. | CUrlManager |
| processRules() | Processes the URL rules. | CUrlManager |
属性详情
appendParams
属性
（自版本 v1.0.3 可用）
public boolean $appendParams;
whether to append GET parameters to the path info part. Defaults to true. This property is only effective when urlFormat is 'path' and is mainly used when creating URLs. When it is true, GET parameters will be appended to the path info and separate from each other using slashes. If this is false, GET parameters will be in query part.
baseUrl
属性
只读
public string getBaseUrl()
the base URL of the application (the part after host name and before query string). If showScriptName is true, it will include the script name part. Otherwise, it will not, and the ending slashes are stripped off.
cacheID
属性
（自版本 v1.0.3 可用）
public string $cacheID;
the ID of the cache application component that is used to cache the parsed URL rules. Defaults to 'cache' which refers to the primary cache application component. Set this property to false if you want to disable caching URL rules.
caseSensitive
属性
（自版本 v1.0.1 可用）
public boolean $caseSensitive;
whether routes are case-sensitive. Defaults to true. By setting this to false, the route in the incoming request will be turned to lower case first before further processing. As a result, you should follow the convention that you use lower case when specifying controller mapping (CWebApplication::controllerMap) and action mapping (CController::actions). Also, the directory names for organizing controllers should be in lower case.
routeVar
属性
public string $routeVar;
the GET variable name for route. Defaults to 'r'.
rules
属性
public array $rules;
the URL rules (pattern=>route).
showScriptName
属性
public boolean $showScriptName;
whether to show entry script name in the constructed URL. Defaults to true.
urlFormat
属性
the URL format. Defaults to 'path'. Valid values include 'path' and 'get'. Please refer to the guide for more details about the difference between these two formats.
urlSuffix
属性
public string $urlSuffix;
the URL suffix used when in 'path' format. For example, ".html" can be used so that the URL looks like pointing to a static HTML page. Defaults to empty.
useStrictParsing
属性
（自版本 v1.0.6 可用）
public boolean $useStrictParsing;
whether to enable strict URL parsing. This property is only effective when urlFormat is 'path'. If it is set true, then an incoming URL must match one of the URL rules. Otherwise, it will be treated as an invalid request and trigger a 404 HTTP exception. Defaults to false.
方法详情
createPathInfo()
方法
（自版本 v1.0.3 可用）
|
public string createPathInfo(array $params, string $equal, string $ampersand, string $key=NULL)
| ||
| $params | array | list of GET parameters |
| $equal | string | the separator between name and value |
| $ampersand | string | the separator between name-value pairs |
| $key | string | this is used internally. |
| {return} | string | the created path info |
Creates a path info based on the given parameters.
createUrl()
方法
|
public string createUrl(string $route, array $params=array (
), string $ampersand='&')
| ||
| $route | string | the controller and the action (e.g. article/read) |
| $params | array | list of GET parameters (name=>value). Both the name and value will be URL-encoded. If the name is '#', the corresponding value will be treated as an anchor and will be appended at the end of the URL. This anchor feature has been available since version 1.0.1. |
| $ampersand | string | the token separating name-value pairs in the URL. Defaults to '&'. |
| {return} | string | the constructed URL |
Constructs a URL.
createUrlDefault()
方法
|
protected string createUrlDefault(string $route, array $params, string $ampersand)
| ||
| $route | string | the controller and the action (e.g. article/read) |
| $params | array | list of GET parameters |
| $ampersand | string | the token separating name-value pairs in the URL. |
| {return} | string | the constructed URL |
Contructs a URL based on default settings.
getBaseUrl()
方法
|
public string getBaseUrl()
| ||
| {return} | string | the base URL of the application (the part after host name and before query string). If showScriptName is true, it will include the script name part. Otherwise, it will not, and the ending slashes are stripped off. |
getUrlFormat()
方法
|
public string getUrlFormat()
| ||
| {return} | string | the URL format. Defaults to 'path'. Valid values include 'path' and 'get'. Please refer to the guide for more details about the difference between these two formats. |
init()
方法
|
public void init()
|
Initializes the application component.
parsePathInfo()
方法
（自版本 v1.0.3 可用）
|
public static void parsePathInfo(string $pathInfo)
| ||
| $pathInfo | string | path info |
Parses a path info into URL segments and saves them to $_GET and $_REQUEST.
parseUrl()
方法
|
public string parseUrl(CHttpRequest $request)
| ||
| $request | CHttpRequest | the request application component |
| {return} | string | the route (controllerID/actionID) and perhaps GET parameters in path format. |
Parses the user request.
processRules()
方法
|
protected void processRules()
|
Processes the URL rules.
removeUrlSuffix()
方法
|
public string removeUrlSuffix(string $pathInfo, string $urlSuffix)
| ||
| $pathInfo | string | path info part in the URL |
| $urlSuffix | string | the URL suffix to be removed |
| {return} | string | path info with URL suffix removed. |
Removes the URL suffix from path info.
setUrlFormat()
方法
|
public void setUrlFormat(string $value)
| ||
| $value | string | the URL format. It must be either 'path' or 'get'. |