Class yii\web\UrlManager

继承yii\web\UrlManager » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/web/UrlManager.php

UrlManager 根据一组规则处理 HTTP 请求解析和 URL 的创建.

UrlManager 默认配置为 yii\base\Application 中的应用程序组件. 你可以通过Yii::$app->urlManager访问这个实例.

你可以通过在components下的应用程序配置中添加一个数组来修改其配置, 如以下示例所示:

'urlManager' => [
    'enablePrettyUrl' => true,
    'rules' => [
        // 在这里定义你的规则
    ],
    // ...
]

规则(rules)是实现 yii\web\UrlRuleInterface 的类, 默认情况下是 yii\web\UrlRule. 对于嵌套规则, 还有一个 yii\web\GroupUrlRule 类.

有关 UrlManager 的更多详细信息和使用信息, 请参阅 权威指南 - 请求处理 - 路由引导与创建 URL(Routing and URL Creation).

公共属性

隐藏继承的属性

属性类型描述定义在
$baseUrl string createUrl() 用于在创建的 URL 之前使用的基本 URL. yii\web\UrlManager
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$cache yii\caching\CacheInterface|array|string 缓存对象或缓存对象的应用程序组件 ID. yii\web\UrlManager
$enablePrettyUrl boolean 是否启用 URL 美化. yii\web\UrlManager
$enableStrictParsing boolean 是否启用严格的解析. yii\web\UrlManager
$hostInfo string createAbsoluteUrl() 用于在创建的 URL 之前添加的主机信息(eg. "http://www.example.com"). yii\web\UrlManager
$normalizer yii\web\UrlNormalizer|array|string|false 此 UrlManager 使用的 yii\web\UrlNormalizer 的配置. yii\web\UrlManager
$routeParam string 路由的 GET 参数名称. yii\web\UrlManager
$ruleConfig array URL 规则的默认配置. yii\web\UrlManager
$rules array $enablePrettyUrltrue时创建和解析 URL 的规则. yii\web\UrlManager
$scriptUrl string createUrl() 用于在创建的 URL 之前添加的入口脚本 URL. yii\web\UrlManager
$showScriptName boolean 是否在创建的 URL 中显示入口脚本名称. yii\web\UrlManager
$suffix string $enablePrettyUrltrue时使用的 URL 后缀. yii\web\UrlManager

受保护的属性

隐藏继承的属性

属性类型描述定义在
$cacheKey string 缓存规则的缓存键. yii\web\UrlManager

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
addRules() 添加更多的 URL 规则. yii\web\UrlManager
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
createAbsoluteUrl() 使用给定的路由和查询参数创建绝对 URL. yii\web\UrlManager
createUrl() 使用给定的路由和查询参数创建一个 URL. yii\web\UrlManager
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
getBaseUrl() 返回 createUrl() 用来添加到创建的 URL 之前的基本 URL. 默认为 yii\web\Request::$baseUrl. yii\web\UrlManager
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getHostInfo() 返回 createAbsoluteUrl() 用来添加到创建的 URL 之前的主机信息. yii\web\UrlManager
getScriptUrl() 返回 createUrl() 用来添加到创建的 URL 之前的入口脚本 URL. 默认为 yii\web\Request::$scriptUrl. yii\web\UrlManager
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化 UrlManager. yii\web\UrlManager
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
parseRequest() 解析用户请求. yii\web\UrlManager
setBaseUrl() 设置 createUrl() 用来在拆改那就的 URL 之前使用的基本 URL. yii\web\UrlManager
setHostInfo() 设置 createAbsoluteUrl() 用来添加到创建的 URL 之前的主机信息. yii\web\UrlManager
setScriptUrl() 设置 createUrl() 用来添加到创建的 URL 之前的入口脚本 URL. yii\web\UrlManager
trigger() 触发事件. yii\base\Component

受保护的方法

隐藏继承的方法

方法描述定义在
buildRules() 根据给定的规则声明构建 URL 规则对象. yii\web\UrlManager
canBeCached() 返回指示是否将规则的 createUrl() 的结果缓存在内部缓存中的值. yii\web\UrlManager
getBuiltRulesFromCache() 提供与缓存中 $ruleDeclarations 关联的内置 URL 规则. yii\web\UrlManager
getUrlFromCache() 如果存在, 则从内部缓存中获取 URL. yii\web\UrlManager
setBuiltRulesCache() 使用 $rulesDeclaration 作为缓存键的一部分, 将 $builtRules 存储到缓存. yii\web\UrlManager
setRuleToCache() 将规则(eg. yii\web\UrlRule)存储到内部缓存中. yii\web\UrlManager

属性详情

$baseUrl public 属性

createUrl() 用于在创建的 URL 之前使用的基本 URL.

public string $baseUrl null
$cache public 属性

缓存对象或缓存对象的应用程序组件 ID. 如果你不想使用应用程序组件, 它也可以是用于创建 yii\caching\CacheInterface 实例的数组 如果可用, 则将通过此缓存对象来缓存编译后的 URL 规则.

创建 UrlManager 对象后, 如果要更改此属性, 则应仅为其分配一个缓存对象. 如果你不想缓存 URL 规则, 请将此属性设置为falsenull.

缓存脚本的存储时间由缓存配置中的 $defaultDuration 设置, 默认情况下是无限的. 如果 $rules 频繁更改, 则可能需要调整此值.

$cacheKey protected 属性 (可用自版本: 2.0.8)

缓存规则的缓存键.

protected string $cacheKey __CLASS__
$enablePrettyUrl public 属性

是否启用 URL 美化.

美化的 URL 无需将所有参数都放在 URL 的查询字符串部分中, 而是允许使用路径信息来表示某些参数, 从而可以生成更加用户友好的 URL, eg, /news/Yii-is-released代替/index.php?r=news%2Fview&id=100.

public boolean $enablePrettyUrl false
$enableStrictParsing public 属性

是否启用严格的解析.

如果启用了严格解析, 则传入的请求 URL 必须至少与 $rules 中的一个匹配, 才能被视为有效的请求.

否则, 请求的路径信息部分将被视为请求的路由.

该属性仅在 $enablePrettyUrltrue时使用.

$hostInfo public 属性

createAbsoluteUrl() 用于在创建的 URL 之前添加的主机信息(eg. "http://www.example.com").

public string $hostInfo null
$normalizer public 属性 (可用自版本: 2.0.10)

此 UrlManager 使用的 yii\web\UrlNormalizer 的配置. 默认值为false, 这意味着将跳过标准化. 如果你需要启用 URL 标准化, 则应手动配置此属性. 例如:

[
    'class' => 'yii\web\UrlNormalizer',
    'collapseSlashes' => true,
    'normalizeTrailingSlash' => true,
]
$routeParam public 属性

路由的 GET 参数名称.

仅当 $enablePrettyUrlfalse时才使用此属性.

public string $routeParam 'r'
$ruleConfig public 属性

URL 规则的默认配置. 当配置规则的相同属性时, 通过 $rules 指定的单独规则配置将优先.

public array $ruleConfig = ['class' => 'yii\web\UrlRule']
$rules public 属性

$enablePrettyUrltrue时创建和解析 URL 的规则.

仅当 $enablePrettyUrltrue时, 才使用此属性.

数组中的每个元素都是用于创建单个 URL 规则的配置数组. 该配置将在用于创建规则对象之前先与 $ruleConfig 合并.

如果规则仅指定 patternroute: 'pattern' => 'route', 则可以使用特殊的快捷方式格式. 也就是说, 除了使用配置数组之外, 还可以使用键来表示模式, 并使用值来表示对应的路由. 例如: 'post/<id:\d+>' => 'post/view'.

对于 RESTful 路由, 上述快捷方式格式还允许你指定该规则应适用的 HTTP verb.

你可以通过将其放在模式中并以空格分隔来实现此目的. 例如: 'PUT post/<id:\d+>' => 'post/update'.

你可以使用逗号分隔多个动词(verb), 例如: 'POST,PUT post/index' => 'post/create'. 支持的快捷方式格式为: GET, HEAD, POST, PUT, PATCHDELETE.

Note: 当以这种方式指定动词时, mode 将被设置为PARSING_ONLY, 因此通常不会为普通的 GET 请求指定动词.

以下是 RESTful CRUD 控制器的配置示例:

[
    'dashboard' => 'site/index',

    'POST <controller:[\w-]+>' => '<controller>/create',
    '<controller:[\w-]+>s' => '<controller>/index',

    'PUT <controller:[\w-]+>/<id:\d+>'    => '<controller>/update',
    'DELETE <controller:[\w-]+>/<id:\d+>' => '<controller>/delete',
    '<controller:[\w-]+>/<id:\d+>'        => '<controller>/view',
];

Note: 如果在创建 UrlManager 对象后修改此属性, 请确保使用规则对象而不是规则配置填充数组.

public array $rules = []
$scriptUrl public 属性

createUrl() 用于在创建的 URL 之前添加的入口脚本 URL.

public string $scriptUrl null
$showScriptName public 属性

是否在创建的 URL 中显示入口脚本名称. 默认为true.

仅当 $enablePrettyUrltrue时才使用此属性.

public boolean $showScriptName true
$suffix public 属性

$enablePrettyUrltrue时使用的 URL 后缀.

例如, 可以使用.html, 以便 URL 看起来像指向一个静态的 HTML 页面.

仅当 $enablePrettyUrltrue时才使用此属性.

public string $suffix null

方法详情

addRules() public 方法

添加更多的 URL 规则.

此方法将调用 buildRules() 解析给定的规则声明, 然后将其追加或插入到现有的 $rules 中.

Note: 如果 $enablePrettyUrlfalse, 则此方法将无效.

public void addRules ( $rules, $append true )
$rules array

要添加的新规则. 每个数组元素表示一个规则声明. 有关可接受的规则格式, 请参阅 $rules.

$append boolean

是否通过将新规则附加到现有规则的末尾来添加新规则.

buildRules() protected 方法

根据给定的规则声明构建 URL 规则对象.

protected yii\web\UrlRuleInterface[] buildRules ( $ruleDeclarations )
$ruleDeclarations array

规则声明. 每个数组元素表示一个规则声明. 有关可接受的规则格式, 请参阅 $rules.

return yii\web\UrlRuleInterface[]

从给定规则声明构建的规则对象.

throws yii\base\InvalidConfigException

如果规则声明无效.

canBeCached() protected 方法 (可用自版本: 2.0.12)

返回指示是否将规则的 createUrl() 的结果缓存在内部缓存中的值.

参见:

protected boolean canBeCached ( yii\web\UrlRuleInterface $rule )
$rule yii\web\UrlRuleInterface
return boolean

如果结果应该被缓存, 则为true, 否则为false.

createAbsoluteUrl() public 方法

使用给定的路由和查询参数创建绝对 URL.

该方法将在 createUrl() 创建的 URL 之前附加 $hostInfo.

Note: yii\helpers\Url::toRoute() 不同, 此方法始终将给定路由视为绝对路由.

参见 createUrl().

public string createAbsoluteUrl ( $params, $scheme null )
$params string|array

使用字符串表示的路由(eg. site/index),, 或使用数组表示的带有查询参数的路由(eg. ['site/index', 'param1' => 'value1']).

$scheme string|null

用于 URL 的方案(用于协议相关 URL 的http, https或空字符串). 如果未指定, 则将使用当前请求的方案.

return string

创建的 URL.

createUrl() public 方法

使用给定的路由和查询参数创建一个 URL.

你可以将路由指定为一个字符串, eg, site/index. 如果要为创建的 URL 指定其它查询参数, 也可以使用数组. 数组格式必须是:

// generates: /index.php?r=site%2Findex&param1=value1&param2=value2
['site/index', 'param1' => 'value1', 'param2' => 'value2']

如果你想创建一个带有锚点的 URL, 你可以使用带#参数的数组格式. 例如,

// generates: /index.php?r=site%2Findex&param1=value1#name
['site/index', 'param1' => 'value1', '#' => 'name']

创建的 URL 是相对的. 使用 createAbsoluteUrl() 来创建绝对 URL.

Note: yii\helpers\Url::toRoute() 不同, 此方法始终将给定路由视为绝对路由.

public string createUrl ( $params )
$params string|array

使用字符串表示的路由(eg. site/index), 或使用数组表示的带查询参数的路由(eg. ['site/index', 'param1' => 'value1']).

return string

创建的 URL.

getBaseUrl() public 方法

返回 createUrl() 用来添加到创建的 URL 之前的基本 URL. 默认为 yii\web\Request::$baseUrl.

主要在 $enablePrettyUrlfalse$showScriptNametrue时使用.

public string getBaseUrl ( )
return string

createUrl() 用于在创建的 URL 之前使用的基本 URL.

throws yii\base\InvalidConfigException

如果在控制台应用程序中运行并且未配置 $baseUrl.

getBuiltRulesFromCache() protected 方法 (可用自版本: 2.0.14)

提供与缓存中 $ruleDeclarations 关联的内置 URL 规则.

protected yii\web\UrlRuleInterface[]|false getBuiltRulesFromCache ( $ruleDeclarations )
$ruleDeclarations array

规则声明. 每个数组元素表示一个规则声明. 有关可接受的规则格式, 请参阅 $rules.

return yii\web\UrlRuleInterface[]|false

从给的规则生命构建的规则对象, 如果不存在用于此定义的缓存项, 则为false.

getHostInfo() public 方法

返回 createAbsoluteUrl() 用来添加到创建的 URL 之前的主机信息.

public string getHostInfo ( )
return string

createAbsoluteUrl() 用来添加到创建的 URL 之前的主机信息(eg. http://www.example.com).

throws yii\base\InvalidConfigException

如果在控制台应用程序中运行并且未配置 $hostInfo.

getScriptUrl() public 方法

返回 createUrl() 用来添加到创建的 URL 之前的入口脚本 URL. 默认为 yii\web\Request::$scriptUrl.

主要在 $enablePrettyUrlfalse$showScriptNametrue时使用.

public string getScriptUrl ( )
return string

createUrl() 用于在创建的 URL 之前添加的入口脚本 URL.

throws yii\base\InvalidConfigException

如果在控制台应用程序中运行并且未配置 $scriptUrl.

getUrlFromCache() protected 方法 (可用自版本: 2.0.8)

如果存在, 则从内部缓存中获取 URL.

参见 createUrl().

protected boolean|string getUrlFromCache ( $cacheKey, $route, $params )
$cacheKey string

生成的用来存储数据的缓存键.

$route string

路由(eg. site/index).

$params array

规则参数.

return boolean|string

创建的 URL.

init() public 方法

初始化 UrlManager.

public void init ( )
parseRequest() public 方法

解析用户请求.

public array|boolean parseRequest ( $request )
$request yii\web\Request

请求(request)组件.

return array|boolean

路由和相关的参数. 如果 $enablePrettyUrlfalse, 则后者始终为空. 如果无法成功解析当前请求, 则返回false.

setBaseUrl() public 方法

设置 createUrl() 用来在拆改那就的 URL 之前使用的基本 URL.

主要在 $enablePrettyUrlfalse$showScriptNametrue时使用.

public void setBaseUrl ( $value )
$value string

createUrl() 用于在创建的 URL 之前使用的基本 URL.

setBuiltRulesCache() protected 方法 (可用自版本: 2.0.14)

使用 $rulesDeclaration 作为缓存键的一部分, 将 $builtRules 存储到缓存.

protected boolean setBuiltRulesCache ( $ruleDeclarations, $builtRules )
$ruleDeclarations array

规则声明. 每个数组元素表示一个规则声明. 有关可接受的规则格式, 请参阅 $rules.

$builtRules yii\web\UrlRuleInterface[]

根据给定规则声明构建的规则对象.

return boolean

该值是否成功存储到缓存中.

setHostInfo() public 方法

设置 createAbsoluteUrl() 用来添加到创建的 URL 之前的主机信息.

public void setHostInfo ( $value )
$value string

createAbsoluteUrl() 用来在创建的 URL 之前添加的主机信息(eg. http://www.example.com).

setRuleToCache() protected 方法 (可用自版本: 2.0.8)

将规则(eg. yii\web\UrlRule)存储到内部缓存中.

protected void setRuleToCache ( $cacheKey, yii\web\UrlRuleInterface $rule )
$cacheKey
$rule yii\web\UrlRuleInterface
setScriptUrl() public 方法

设置 createUrl() 用来添加到创建的 URL 之前的入口脚本 URL.

主要在 $enablePrettyUrlfalse$showScriptNametrue时使用.

public void setScriptUrl ( $value )
$value string

createUrl() 用于在创建的 URL 之前添加的入口脚本 URL.