0 关注者

类 yii\rest\UrlRule

继承关系yii\rest\UrlRule » yii\web\CompositeUrlRule » yii\base\BaseObject
实现yii\base\Configurable, yii\web\UrlRuleInterface
可用版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/rest/UrlRule.php

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 规则并为 userpost 控制器生成规则

[
    'class' => 'yii\rest\UrlRule',
    'controller' => ['user', 'post'],
    'except' => ['delete'],
]

属性 $controller 是必需的,应该代表一个或多个控制器 ID。每个控制器 ID 应该以模块 ID 为前缀,如果控制器在模块中。模式中使用的控制器 ID 将自动变为复数(例如 user 变为 users,如上述示例所示)。

有关 UrlRule 的更多详细信息和使用信息,请参阅 关于 REST 路由的指南文章

公共属性

隐藏继承的属性

属性 类型 描述 定义于
$controller string|array 此复合规则中规则所处理的控制器 ID(例如,userpost-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

属性详情

隐藏继承的属性

$controller 公共属性

此复合规则中规则所处理的控制器 ID(例如,userpost-comment)。如果控制器在模块中,它应该以模块 ID 为前缀(例如,admin/user)。

默认情况下,控制器 ID 在放入生成的规则的模式中时会自动变为复数。如果要明确指定控制器 ID 在模式中应该如何显示,可以使用数组,数组键作为模式中的控制器 ID,数组值作为实际控制器 ID。例如,['u' => 'user']

您也可以将多个控制器 ID 作为数组传递。如果是这种情况,此复合规则将为每个指定的控制器生成适用的 URL 规则。例如,['user', 'post']

public string|array $controller null
$except 公共属性

应该被排除的动作列表。在这个数组中找到的任何动作都不会创建其 URL 规则。

另请参阅 $patterns.

public array $except = []
$extraPatterns 公共属性

除了 $patterns 中列出的动作之外,支持额外动作的模式。键是模式,值是相应的动作 ID。这些额外的模式将优先于 $patterns

public array $extraPatterns = []
$only 公共属性

可接受的动作列表。如果非空,则只有此数组中的动作才会创建相应的 URL 规则。

另请参阅 $patterns.

public array $only = []
$patterns 公共属性

创建 URL 规则时,可能的模式列表及其对应的动作。键是模式,值是对应的动作。模式的格式为 Verbs Pattern,其中 Verbs 代表用逗号分隔的 HTTP 动词列表(不带空格)。如果未指定 Verbs,则表示允许所有动词。Pattern 是可选的。它将在前面加上 $prefix/$controller/,其中的标记将被 $tokens 替换。

public array $patterns = [
    
'PUT,PATCH {id}' => 'update',
    
'DELETE {id}' => 'delete',
    
'GET,HEAD {id}' => 'view',
    
'POST' => 'create',
    
'GET,HEAD' => 'index',
    
'{id}' => 'options',
    
'' => 'options',
]
$pluralize 公共属性

是否自动复数化控制器的 URL 名称。如果为 true,则控制器 ID 将以复数形式出现在 URL 中。例如,user 控制器将在 URL 中显示为 users

另请参阅 $controller.

public boolean $pluralize true
$prefix 公共属性

所有模式共有的公共前缀字符串。

public string|null $prefix null
$ruleConfig 公共属性

用于创建此规则包含的每个 URL 规则的默认配置。

public array $ruleConfig = [
    
'class' => 'yii\web\UrlRule',
]
$suffix 公共属性

将分配给 yii\web\UrlRule::$suffix 的后缀,用于每个生成的规则。

public string $suffix null
$tokens 公共属性

应该为每个模式替换的标记列表。键是标记名称,值是相应的替换。

另请参阅 $patterns.

public array $tokens = [
    
'{id}' => '<id:\d[\d,]*>',
]

方法详情

隐藏继承的方法

__call() 公共方法

定义于: yii\base\BaseObject::__call()

调用不是类方法的命名方法。

不要直接调用此方法,因为它是一个 PHP 魔术方法,当调用未知方法时会隐式调用。

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()");
}

            
__construct() 公共方法

定义于: 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();
}

            
__get() public method

定义于: 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);
}

            
__isset() public method

定义于: yii\base\BaseObject::__isset()

检查属性是否已设置,即已定义且不为空。

不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 `isset($object->property)` 时会隐式调用。

请注意,如果属性未定义,则将返回 false。

另请参见 https://php.ac.cn/manual/en/function.isset.php.

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;
}

            
__set() public method

定义于: 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);
    }
}

            
__unset() public method

定义于: yii\base\BaseObject::__unset()

将对象属性设置为 null。

不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 `unset($object->property)` 时会隐式调用。

请注意,如果属性未定义,此方法将不做任何操作。如果属性是只读的,它将抛出一个异常。

另请参见 https://php.ac.cn/manual/en/function.unset.php.

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);
    }
}

            
canGetProperty() public method

定义于: 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);
}

            
canSetProperty() public method

定义于: 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);
}

            
className() public static method
从 2.0.14 版本开始弃用。在 PHP >=5.5 上,使用 `::class` 代替。

定义于: yii\base\BaseObject::className()

返回此类的完全限定名称。

public static string className ( )
返回值 string

此类的完全限定名称。

                public static function className()
{
    return get_called_class();
}

            
createRule() protected method

使用给定的模式和动作创建 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);
}

            
createRules() protected method

创建应包含在此复合规则中的 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;
}

            
createUrl() public method

根据给定的路由和参数创建 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;
}

            
getCreateUrlStatus() public method (available since version 2.0.12)

定义于: 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;
}

            
hasMethod() 公共方法

定义于: 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);
}

            
hasProperty() 公共方法

定义于: 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);
}

            
init() 公共方法

初始化对象。

此方法在构造函数结束时调用,在对象使用给定配置初始化后调用。

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();
}

            
iterateRules() 受保护方法 (自版本 2.0.12 起可用)

定义于: yii\web\CompositeUrlRule::iterateRules()

遍历指定的规则并为每个规则调用 createUrl()

另请参阅 createUrl().

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,则为 false

                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;
}

            
parseRequest() 公共方法

解析给定的请求并返回相应的路由和参数。

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;
}