类 yii\rest\UrlRule
UrlRule 用于简化 RESTful API 支持的 URL 规则创建。
UrlRule 最简单的用法是在应用程序配置中声明一个规则,如下所示:
[
'class' => 'yii\rest\UrlRule',
'controller' => 'user',
]
以上代码将创建一组完整的 URL 规则,支持以下 RESTful API 端点
'PUT,PATCH users/<id>' => 'user/update'
: 更新用户'DELETE users/<id>' => 'user/delete'
: 删除用户'GET,HEAD users/<id>' => 'user/view'
: 返回用户的详细信息/概览/选项'POST users' => 'user/create'
: 创建一个新用户'GET,HEAD users' => 'user/index'
: 返回用户列表/概览/选项'users/<id>' => 'user/options'
: 处理用户的所有未处理的动词'users' => 'user/options'
: 处理用户集合的所有未处理的动词
您可以配置 $only 和/或 $except 来禁用上述某些规则。您可以配置 $patterns 来完全重新定义自己的规则列表。您可以配置 $controller 使用多个控制器 ID 为所有这些控制器生成规则。例如,以下代码将禁用 delete
规则并为 user
和 post
控制器生成规则
[
'class' => 'yii\rest\UrlRule',
'controller' => ['user', 'post'],
'except' => ['delete'],
]
属性 $controller 是必需的,应该代表一个或多个控制器 ID。每个控制器 ID 应该以模块 ID 为前缀,如果控制器在模块中。模式中使用的控制器 ID 将自动变为复数(例如 user
变为 users
,如上述示例所示)。
有关 UrlRule 的更多详细信息和使用信息,请参阅 关于 REST 路由的指南文章。
公共属性
属性 | 类型 | 描述 | 定义于 |
---|---|---|---|
$controller | string|array | 此复合规则中规则所处理的控制器 ID(例如,user 、post-comment )。 |
yii\rest\UrlRule |
$createStatus | integer|null | 最后一次 createUrl() 调用后,URL 创建的状态。 | yii\web\CompositeUrlRule |
$createUrlStatus | integer|null | 最后一次 createUrl() 调用后,URL 创建的状态。 | yii\web\CompositeUrlRule |
$except | array | 应该排除的动作列表。 | yii\rest\UrlRule |
$extraPatterns | array | 用于支持除了 $patterns 中列出的动作之外的额外动作的模式。 | yii\rest\UrlRule |
$only | array | 可接受的动作列表。 | yii\rest\UrlRule |
$patterns | array | 用于创建 URL 规则的可能的模式和相应的动作列表。 | yii\rest\UrlRule |
$pluralize | boolean | 是否自动将控制器的 URL 名称变为复数。 | yii\rest\UrlRule |
$prefix | string|null | 所有模式共有的公共前缀字符串。 | yii\rest\UrlRule |
$ruleConfig | array | 用于创建此规则包含的每个 URL 规则的默认配置。 | yii\rest\UrlRule |
$rules | yii\web\UrlRuleInterface[] | 此复合规则中包含的 URL 规则。 | yii\web\CompositeUrlRule |
$suffix | string | 将分配给 yii\web\UrlRule::$suffix 的后缀,用于每个生成的规则。 | yii\rest\UrlRule |
$tokens | array | 每个模式应替换的标记列表。 | yii\rest\UrlRule |
公共方法
方法 | 描述 | 定义于 |
---|---|---|
__call() | 调用不是类方法的命名方法。 | yii\base\BaseObject |
__construct() | 构造函数。 | yii\base\BaseObject |
__get() | 返回对象属性的值。 | yii\base\BaseObject |
__isset() | 检查属性是否已设置,即已定义且不为空。 | yii\base\BaseObject |
__set() | 设置对象属性的值。 | yii\base\BaseObject |
__unset() | 将对象属性设置为 null。 | yii\base\BaseObject |
canGetProperty() | 返回一个值,指示是否可以读取属性。 | yii\base\BaseObject |
canSetProperty() | 返回一个值,指示是否可以设置属性。 | yii\base\BaseObject |
className() | 返回此类的完全限定名称。 | yii\base\BaseObject |
createUrl() | 根据给定的路由和参数创建 URL。 | yii\rest\UrlRule |
getCreateUrlStatus() | 返回最后一次 createUrl() 调用后 URL 创建的状态。 | yii\web\CompositeUrlRule |
hasMethod() | 返回一个值,指示是否定义了方法。 | yii\base\BaseObject |
hasProperty() | 返回一个值,指示是否定义了属性。 | yii\base\BaseObject |
init() | 初始化对象。 | yii\rest\UrlRule |
parseRequest() | 解析给定的请求并返回相应的路由和参数。 | yii\rest\UrlRule |
受保护的方法
方法 | 描述 | 定义于 |
---|---|---|
createRule() | 使用给定的模式和动作创建 URL 规则。 | yii\rest\UrlRule |
createRules() | 创建应包含在此复合规则中的 URL 规则。 | yii\rest\UrlRule |
iterateRules() | 遍历指定的规则并为每个规则调用 createUrl()。 | yii\web\CompositeUrlRule |
属性详情
此复合规则中规则所处理的控制器 ID(例如,user
、post-comment
)。如果控制器在模块中,它应该以模块 ID 为前缀(例如,admin/user
)。
默认情况下,控制器 ID 在放入生成的规则的模式中时会自动变为复数。如果要明确指定控制器 ID 在模式中应该如何显示,可以使用数组,数组键作为模式中的控制器 ID,数组值作为实际控制器 ID。例如,['u' => 'user']
。
您也可以将多个控制器 ID 作为数组传递。如果是这种情况,此复合规则将为每个指定的控制器生成适用的 URL 规则。例如,['user', 'post']
。
创建 URL 规则时,可能的模式列表及其对应的动作。键是模式,值是对应的动作。模式的格式为 Verbs Pattern
,其中 Verbs
代表用逗号分隔的 HTTP 动词列表(不带空格)。如果未指定 Verbs
,则表示允许所有动词。Pattern
是可选的。它将在前面加上 $prefix/$controller/,其中的标记将被 $tokens 替换。
是否自动复数化控制器的 URL 名称。如果为 true,则控制器 ID 将以复数形式出现在 URL 中。例如,user
控制器将在 URL 中显示为 users
。
另请参阅 $controller.
用于创建此规则包含的每个 URL 规则的默认配置。
方法详情
public mixed __call ( $name, $params ) | ||
$name | string |
方法名称 |
$params | array |
方法参数 |
返回值 | mixed |
方法返回值 |
---|---|---|
抛出 | yii\base\UnknownMethodException |
调用未知方法时 |
public function __call($name, $params)
{
throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}
定义于: yii\base\BaseObject::__construct()
构造函数。
默认实现执行两件事
- 使用给定的配置
$config
初始化对象。 - 调用 init().
如果此方法在子类中被覆盖,建议
- 构造函数的最后一个参数是一个配置数组,就像这里显示的 `$config` 一样。
- 在构造函数的最后调用父类的实现。
public void __construct ( $config = [] ) | ||
$config | array |
用于初始化对象属性的键值对。 |
public function __construct($config = [])
{
if (!empty($config)) {
Yii::configure($this, $config);
}
$this->init();
}
定义于: yii\base\BaseObject::__get()
返回对象属性的值。
不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 `$value = $object->property;` 时会隐式调用。
另请参见 __set().
public mixed __get ( $name ) | ||
$name | string |
属性名称 |
返回值 | mixed |
属性值 |
---|---|---|
抛出 | yii\base\UnknownPropertyException |
如果属性未定义 |
抛出 | yii\base\InvalidCallException |
如果属性是只写 |
public function __get($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
return $this->$getter();
} elseif (method_exists($this, 'set' . $name)) {
throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
}
throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}
定义于: yii\base\BaseObject::__isset()
检查属性是否已设置,即已定义且不为空。
不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 `isset($object->property)` 时会隐式调用。
请注意,如果属性未定义,则将返回 false。
public boolean __isset ( $name ) | ||
$name | string |
属性名称或事件名称 |
返回值 | boolean |
命名的属性是否已设置(非空)。 |
---|
public function __isset($name)
{
$getter = 'get' . $name;
if (method_exists($this, $getter)) {
return $this->$getter() !== null;
}
return false;
}
定义于: yii\base\BaseObject::__set()
设置对象属性的值。
不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 `$object->property = $value;` 时会隐式调用。
另请参见 __get().
public void __set ( $name, $value ) | ||
$name | string |
属性名称或事件名称 |
$value | mixed |
属性值 |
抛出 | yii\base\UnknownPropertyException |
如果属性未定义 |
---|---|---|
抛出 | yii\base\InvalidCallException |
如果属性是只读 |
public function __set($name, $value)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
$this->$setter($value);
} elseif (method_exists($this, 'get' . $name)) {
throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
} else {
throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
}
}
定义于: yii\base\BaseObject::__unset()
将对象属性设置为 null。
不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 `unset($object->property)` 时会隐式调用。
请注意,如果属性未定义,此方法将不做任何操作。如果属性是只读的,它将抛出一个异常。
public void __unset ( $name ) | ||
$name | string |
属性名称 |
抛出 | yii\base\InvalidCallException |
如果属性是只读的。 |
---|
public function __unset($name)
{
$setter = 'set' . $name;
if (method_exists($this, $setter)) {
$this->$setter(null);
} elseif (method_exists($this, 'get' . $name)) {
throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
}
}
定义于: yii\base\BaseObject::canGetProperty()
返回一个值,指示是否可以读取属性。
属性可读,如果
- 该类具有与指定名称关联的 getter 方法(在这种情况下,属性名称不区分大小写);
- 该类具有与指定名称相同的成员变量(当 `$checkVars` 为 true 时);
另请参见 canSetProperty().
public boolean canGetProperty ( $name, $checkVars = true ) | ||
$name | string |
属性名称 |
$checkVars | boolean |
是否将成员变量视为属性 |
返回值 | boolean |
属性是否可读 |
---|
public function canGetProperty($name, $checkVars = true)
{
return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
}
定义于: yii\base\BaseObject::canSetProperty()
返回一个值,指示是否可以设置属性。
属性可写,如果
- 该类具有与指定名称关联的 setter 方法(在这种情况下,属性名称不区分大小写);
- 该类具有与指定名称相同的成员变量(当 `$checkVars` 为 true 时);
另请参见 canGetProperty().
public boolean canSetProperty ( $name, $checkVars = true ) | ||
$name | string |
属性名称 |
$checkVars | boolean |
是否将成员变量视为属性 |
返回值 | boolean |
属性是否可写 |
---|
public function canSetProperty($name, $checkVars = true)
{
return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
}
定义于: yii\base\BaseObject::className()
返回此类的完全限定名称。
public static string className ( ) | ||
返回值 | string |
此类的完全限定名称。 |
---|
public static function className()
{
return get_called_class();
}
使用给定的模式和动作创建 URL 规则。
protected yii\web\UrlRuleInterface createRule ( $pattern, $prefix, $action ) | ||
$pattern | string | |
$prefix | string | |
$action | string |
protected function createRule($pattern, $prefix, $action)
{
$verbs = 'GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS';
if (preg_match("/^((?:($verbs),)*($verbs))(?:\\s+(.*))?$/", $pattern, $matches)) {
$verbs = explode(',', $matches[1]);
$pattern = isset($matches[4]) ? $matches[4] : '';
} else {
$verbs = [];
}
$config = $this->ruleConfig;
$config['verb'] = $verbs;
$config['pattern'] = rtrim($prefix . '/' . strtr($pattern, $this->tokens), '/');
$config['route'] = $action;
$config['suffix'] = $this->suffix;
return Yii::createObject($config);
}
创建应包含在此复合规则中的 URL 规则。
protected yii\web\UrlRuleInterface[] createRules ( ) | ||
返回值 | yii\web\UrlRuleInterface[] |
URL 规则 |
---|
protected function createRules()
{
$only = array_flip($this->only);
$except = array_flip($this->except);
$patterns = $this->extraPatterns + $this->patterns;
$rules = [];
foreach ($this->controller as $urlName => $controller) {
$prefix = trim($this->prefix . '/' . $urlName, '/');
foreach ($patterns as $pattern => $action) {
if (!isset($except[$action]) && (empty($only) || isset($only[$action]))) {
$rules[$urlName][] = $this->createRule($pattern, $prefix, $controller . '/' . $action);
}
}
}
return $rules;
}
根据给定的路由和参数创建 URL。
public string|boolean createUrl ( $manager, $route, $params ) | ||
$manager | yii\web\UrlManager |
URL 管理器 |
$route | string |
路由。它不应该在开头或结尾有斜杠。 |
$params | array |
参数 |
返回值 | string|boolean |
创建的 URL,或者如果此规则不能用于创建此 URL,则为 false。 |
---|
public function createUrl($manager, $route, $params)
{
$this->createStatus = WebUrlRule::CREATE_STATUS_SUCCESS;
foreach ($this->controller as $urlName => $controller) {
if (strpos($route, $controller) !== false) {
/* @var $rules UrlRuleInterface[] */
$rules = $this->rules[$urlName];
$url = $this->iterateRules($rules, $manager, $route, $params);
if ($url !== false) {
return $url;
}
} else {
$this->createStatus |= WebUrlRule::CREATE_STATUS_ROUTE_MISMATCH;
}
}
if ($this->createStatus === WebUrlRule::CREATE_STATUS_SUCCESS) {
// create status was not changed - there is no rules configured
$this->createStatus = WebUrlRule::CREATE_STATUS_PARSING_ONLY;
}
return false;
}
定义于: yii\web\CompositeUrlRule::getCreateUrlStatus()
返回最后一次 createUrl() 调用后 URL 创建的状态。
对于多个规则,状态将通过按位 `or` 运算符组合(例如 `UrlRule::CREATE_STATUS_PARSING_ONLY | UrlRule::CREATE_STATUS_PARAMS_MISMATCH`)。
另请参见
public integer|null getCreateUrlStatus ( ) | ||
返回值 | integer|null |
最后一次 createUrl() 调用后 URL 创建的状态。如果规则未提供有关创建状态的信息,则为 `null`。 |
---|
public function getCreateUrlStatus()
{
return $this->createStatus;
}
定义于: yii\base\BaseObject::hasMethod()
返回一个值,指示是否定义了方法。
默认实现调用 PHP 函数 method_exists()
。当您实现 PHP 魔术方法 __call()
时,您可能需要重写此方法。
public boolean hasMethod ( $name ) | ||
$name | string |
方法名称 |
返回值 | boolean |
方法是否已定义 |
---|
public function hasMethod($name)
{
return method_exists($this, $name);
}
定义于: yii\base\BaseObject::hasProperty()
返回一个值,指示是否定义了属性。
如果属性定义了,则
- 该类拥有与指定名称关联的 getter 或 setter 方法(在这种情况下,属性名称不区分大小写);
- 该类具有与指定名称相同的成员变量(当 `$checkVars` 为 true 时);
另请参见
public boolean hasProperty ( $name, $checkVars = true ) | ||
$name | string |
属性名称 |
$checkVars | boolean |
是否将成员变量视为属性 |
返回值 | boolean |
属性是否已定义 |
---|
public function hasProperty($name, $checkVars = true)
{
return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
}
初始化对象。
此方法在构造函数结束时调用,在对象使用给定配置初始化后调用。
public void init ( ) |
public function init()
{
if (empty($this->controller)) {
throw new InvalidConfigException('"controller" must be set.');
}
$controllers = [];
foreach ((array) $this->controller as $urlName => $controller) {
if (is_int($urlName)) {
$urlName = $this->pluralize ? Inflector::pluralize($controller) : $controller;
}
$controllers[$urlName] = $controller;
}
$this->controller = $controllers;
$this->prefix = trim((string)$this->prefix, '/');
parent::init();
}
protected boolean|string iterateRules ( $rules, $manager, $route, $params ) | ||
$rules | yii\web\UrlRuleInterface[] |
要迭代的规则。 |
$manager | yii\web\UrlManager |
URL 管理器 |
$route | string |
路由。它不应该在开头或结尾有斜杠。 |
$params | array |
参数 |
返回值 | boolean|string |
生成的 URL,如果指定规则中没有一个可以用于生成此 URL,则为 |
---|
protected function iterateRules($rules, $manager, $route, $params)
{
/* @var $rule UrlRule */
foreach ($rules as $rule) {
$url = $rule->createUrl($manager, $route, $params);
if ($url !== false) {
$this->createStatus = UrlRule::CREATE_STATUS_SUCCESS;
return $url;
}
if (
$this->createStatus === null
|| !method_exists($rule, 'getCreateUrlStatus')
|| $rule->getCreateUrlStatus() === null
) {
$this->createStatus = null;
} else {
$this->createStatus |= $rule->getCreateUrlStatus();
}
}
return false;
}
解析给定的请求并返回相应的路由和参数。
public array|boolean parseRequest ( $manager, $request ) | ||
$manager | yii\web\UrlManager |
URL 管理器 |
$request | yii\web\Request |
请求组件 |
返回值 | array|boolean |
解析结果。路由和参数作为数组返回。如果为 false,则表示此规则不能用于解析此路径信息。 |
---|
public function parseRequest($manager, $request)
{
$pathInfo = $request->getPathInfo();
if (
$this->prefix !== ''
&& strpos($this->prefix, '<') === false
&& strpos($pathInfo . '/', $this->prefix . '/') !== 0
) {
return false;
}
foreach ($this->rules as $urlName => $rules) {
if (strpos($pathInfo, $urlName) !== false) {
foreach ($rules as $rule) {
/* @var $rule WebUrlRule */
$result = $rule->parseRequest($manager, $request);
if (YII_DEBUG) {
Yii::debug([
'rule' => method_exists($rule, '__toString') ? $rule->__toString() : get_class($rule),
'match' => $result !== false,
'parent' => self::className(),
], __METHOD__);
}
if ($result !== false) {
return $result;
}
}
}
}
return false;
}
此类默认将您尝试访问的资源的 ID 匹配为数字。如果您的唯一标识符不只是数字,例如 UUID V4,您可以在配置中重写
$tokens
成员变量以指定{id}
标记应匹配的内容。它使用正则表达式匹配。'urlManager' => [ ... 'rules' => [ [ 'class' => 'yii\rest\UrlRule', 'controller' => ['controllername'], 'tokens' => ['{id}' => '<id:\\w+>'], ], ], ],
此示例将
{id}
匹配为任何字母数字字符[a-zA-Z0-9_]
一次或多次。请注册或登录以评论。