0 关注者

类 yii\web\UrlRule

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

UrlRule 代表 yii\web\UrlManager 用于解析和生成 URL 的规则。

要定义您自己的 URL 解析和创建逻辑,您可以从此类扩展并将其添加到 yii\web\UrlManager::$rules,如下所示

'rules' => [
    ['class' => 'MyUrlRule', 'pattern' => '...', 'route' => 'site/index', ...],
    // ...
]

公共属性

隐藏继承的属性

属性 类型 描述 定义于
$createStatus integer|null 最后一次调用 createUrl() 后 URL 创建的状态。 yii\web\UrlRule
$createUrlStatus integer|null 最后一次调用 createUrl() 后 URL 创建的状态。 yii\web\UrlRule
$defaults array 此规则提供的默认 GET 参数 (名称 => 值)。 yii\web\UrlRule
$encodeParams boolean 一个值,指示是否应对参数进行 URL 编码。 yii\web\UrlRule
$host string|null 用于解析和创建 URL 主机信息部分的模式 (例如 https://example.com)。 yii\web\UrlRule
$mode integer|null 一个值,指示此规则是否应同时用于请求解析和 URL 创建、仅解析或仅创建。 yii\web\UrlRule
$name string|null 此规则的名称。 yii\web\UrlRule
$normalizer yii\web\UrlNormalizer|array|false|null 此规则使用的 yii\web\UrlNormalizer 的配置。 yii\web\UrlRule
$pattern string 用于解析和创建 URL 路径信息部分的模式。 yii\web\UrlRule
$placeholders array 匹配参数名称的占位符列表。 yii\web\UrlRule
$route string 控制器操作的路由。 yii\web\UrlRule
$suffix string|null 此规则使用的 URL 后缀。 yii\web\UrlRule
$verb string|array|null 此规则应匹配的 HTTP 方法 (例如 GET、POST、DELETE)。 yii\web\UrlRule

受保护属性

隐藏继承的属性

属性 类型 描述 定义于

公共方法

隐藏继承的方法

方法 描述 定义于
__call() 调用不是类方法的命名方法。 yii\base\BaseObject
__construct() 构造函数。 yii\base\BaseObject
__get() 返回对象属性的值。 yii\base\BaseObject
__isset() 检查属性是否已设置,即定义且不为 null。 yii\base\BaseObject
__set() 设置对象属性的值。 yii\base\BaseObject
__toString() yii\web\UrlRule
__unset() 将对象属性设置为 null。 yii\base\BaseObject
canGetProperty() 返回一个值,指示属性是否可读。 yii\base\BaseObject
canSetProperty() 返回一个值,指示属性是否可写。 yii\base\BaseObject
className() 返回此类的完全限定名称。 yii\base\BaseObject
createUrl() 根据给定的路由和参数创建 URL。 yii\web\UrlRule
getCreateUrlStatus() 返回最后一次调用 createUrl() 后 URL 创建的状态。 yii\web\UrlRule
hasMethod() 返回一个值,指示方法是否已定义。 yii\base\BaseObject
hasProperty() 返回一个值,指示属性是否已定义。 yii\base\BaseObject
init() 初始化此规则。 yii\web\UrlRule
parseRequest() 解析给定的请求并返回相应的路由和参数。 yii\web\UrlRule

受保护方法

隐藏继承的方法

方法 描述 定义于
getNormalizer() yii\web\UrlRule
getParamRules() 返回用于匹配参数的正则表达式列表。 yii\web\UrlRule
hasNormalizer() yii\web\UrlRule
substitutePlaceholderNames() 遍历 $placeholders 并检查每个占位符是否作为键存在于 $matches 数组中。 yii\web\UrlRule

常量

隐藏继承的常量

常量 描述 定义于
CREATE_STATUS_PARAMS_MISMATCH 4 表示最后一次调用 createUrl() 未成功生成 URL,因为参数不匹配或缺少参数。 yii\web\UrlRule
CREATE_STATUS_PARSING_ONLY 1 表示最后一次调用 createUrl() 未成功生成 URL,因为规则不支持创建 URL。 yii\web\UrlRule
CREATE_STATUS_ROUTE_MISMATCH 2 表示最后一次调用 createUrl() 未成功生成 URL,因为路由不匹配。 yii\web\UrlRule
CREATE_STATUS_SUCCESS 0 表示最后一次调用 createUrl() 成功生成 URL。 yii\web\UrlRule
CREATION_ONLY 2 使用此值设置 $mode 以标记此规则仅用于 URL 创建。 yii\web\UrlRule
PARSING_ONLY 1 使用此值设置 $mode 以标记此规则仅用于 URL 解析。 yii\web\UrlRule

属性详情

隐藏继承的属性

$createStatus 受保护属性 (自版本 2.0.12 起可用)

最后一次调用 createUrl() 后 URL 创建的状态。

protected integer|null $createStatus null
$createUrlStatus 公共属性

最后一次调用 createUrl() 后 URL 创建的状态。如果规则未提供有关创建状态的信息,则为 null

$defaults 公共属性

此规则提供的默认 GET 参数 (名称 => 值)。当此规则用于解析传入请求时,此属性中声明的值将注入到 $_GET 中。

public array $defaults = []
$encodeParams 公共属性

一个值,指示是否应对参数进行 URL 编码。

public boolean $encodeParams true
$host 公共属性

用于解析和创建 URL 主机信息部分的模式 (例如 https://example.com)。

另请参阅 $pattern

public string|null $host null
$mode 公共属性

一个值,指示此规则是否应用于请求解析和 URL 创建、仅解析或仅创建。如果未设置或为 0,则表示该规则同时用于请求解析和 URL 创建。如果它是 PARSING_ONLY,则该规则仅用于请求解析。如果它是 CREATION_ONLY,则该规则仅用于 URL 创建。

public integer|null $mode null
$name 公共属性

此规则的名称。如果未设置,它将使用 $pattern 作为名称。

public string|null $name null
$normalizer 公共属性 (自版本 2.0.10 起可用)

此规则使用的 yii\web\UrlNormalizer 的配置。如果为 null,则将使用 yii\web\UrlManager::$normalizer,如果为 false,则将跳过此规则的规范化。

$pattern 公共属性

用于解析和创建 URL 路径信息部分的模式。

另请参阅

public string $pattern null
$placeholders 受保护属性 (自版本 2.0.7 起可用)

匹配参数名称占位符列表。用于 parseRequest()createUrl()。在规则初始化时,$pattern 参数名称将替换为占位符。此数组包含原始参数名称与其占位符之间的关系。数组键是占位符,值是原始名称。

另请参阅

protected array $placeholders = []
$route 公共属性

控制器操作的路由。

public string $route null
$suffix 公共属性

此规则使用的 URL 后缀。例如,可以使用“.html”使 URL 看起来像指向静态 HTML 页面。如果未设置,则将使用 yii\web\UrlManager::$suffix 的值。

public string|null $suffix null
$verb 公共属性

此规则应匹配的 HTTP 方法(例如 GET、POST、DELETE)。使用数组表示此规则可能匹配的多个方法。如果未设置此属性,则该规则可以匹配任何方法。请注意,此属性仅在解析请求时使用。它在 URL 创建中被忽略。

public string|array|null $verb null

方法详情

隐藏继承的方法

__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() 公共方法

定义于: 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() 公共方法

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

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

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

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

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

public boolean __isset ( $name )
$name string

属性名称或事件名称

返回值 boolean

命名的属性是否已设置(非 null)。

                public function __isset($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter() !== null;
    }
    return false;
}

            
__set() 公共方法

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

            
__toString() 公共方法 (自版本 2.0.11 起可用)

public string __toString ( )

                public function __toString()
{
    $str = '';
    if ($this->verb !== null) {
        $str .= implode(',', $this->verb) . ' ';
    }
    if ($this->host !== null && strrpos($this->name, $this->host) === false) {
        $str .= $this->host . '/';
    }
    $str .= $this->name;
    if ($str === '') {
        return '/';
    }
    return $str;
}

            
__unset() 公共方法

定义于: 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() 公共方法

定义于: 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() 公共方法

定义于: 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() 公共静态方法
自 2.0.14 版起已弃用。在 PHP >=5.5 上,请改用::class

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

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

public static string className ( )
返回值 string

此类的完全限定名称。

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

            
createUrl() 公共方法

根据给定的路由和参数创建 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)
{
    if ($this->mode === self::PARSING_ONLY) {
        $this->createStatus = self::CREATE_STATUS_PARSING_ONLY;
        return false;
    }
    $tr = [];
    // match the route part first
    if ($route !== $this->route) {
        if ($this->_routeRule !== null && preg_match($this->_routeRule, $route, $matches)) {
            $matches = $this->substitutePlaceholderNames($matches);
            foreach ($this->_routeParams as $name => $token) {
                if (isset($this->defaults[$name]) && strcmp($this->defaults[$name], $matches[$name]) === 0) {
                    $tr[$token] = '';
                } else {
                    $tr[$token] = $matches[$name];
                }
            }
        } else {
            $this->createStatus = self::CREATE_STATUS_ROUTE_MISMATCH;
            return false;
        }
    }
    // match default params
    // if a default param is not in the route pattern, its value must also be matched
    foreach ($this->defaults as $name => $value) {
        if (isset($this->_routeParams[$name])) {
            continue;
        }
        if (!isset($params[$name])) {
            // allow omit empty optional params
            // @see https://github.com/yiisoft/yii2/issues/10970
            if (in_array($name, $this->placeholders) && strcmp($value, '') === 0) {
                $params[$name] = '';
            } else {
                $this->createStatus = self::CREATE_STATUS_PARAMS_MISMATCH;
                return false;
            }
        }
        if (strcmp($params[$name], $value) === 0) { // strcmp will do string conversion automatically
            unset($params[$name]);
            if (isset($this->_paramRules[$name])) {
                $tr["<$name>"] = '';
            }
        } elseif (!isset($this->_paramRules[$name])) {
            $this->createStatus = self::CREATE_STATUS_PARAMS_MISMATCH;
            return false;
        }
    }
    // match params in the pattern
    foreach ($this->_paramRules as $name => $rule) {
        if (isset($params[$name]) && !is_array($params[$name]) && ($rule === '' || preg_match($rule, $params[$name]))) {
            $tr["<$name>"] = $this->encodeParams ? urlencode($params[$name]) : $params[$name];
            unset($params[$name]);
        } elseif (!isset($this->defaults[$name]) || isset($params[$name])) {
            $this->createStatus = self::CREATE_STATUS_PARAMS_MISMATCH;
            return false;
        }
    }
    $url = $this->trimSlashes(strtr($this->_template, $tr));
    if ($this->host !== null) {
        $pos = strpos($url, '/', 8);
        if ($pos !== false) {
            $url = substr($url, 0, $pos) . preg_replace('#/+#', '/', substr($url, $pos));
        }
    } elseif (strpos($url, '//') !== false) {
        $url = preg_replace('#/+#', '/', trim($url, '/'));
    }
    if ($url !== '') {
        $url .= ($this->suffix === null ? $manager->suffix : $this->suffix);
    }
    if (!empty($params) && ($query = http_build_query($params)) !== '') {
        $url .= '?' . $query;
    }
    $this->createStatus = self::CREATE_STATUS_SUCCESS;
    return $url;
}

            
getCreateUrlStatus() 公共方法 (自版本 2.0.12 起可用)

返回最后一次调用 createUrl() 后 URL 创建的状态。

另请参阅 $createStatus

public integer|null getCreateUrlStatus ( )
返回值 integer|null

最后一次调用 createUrl() 后 URL 创建的状态。如果规则未提供有关创建状态的信息,则为 null

                public function getCreateUrlStatus()
{
    return $this->createStatus;
}

            
getNormalizer() 受保护方法 (自版本 2.0.10 起可用)

受保护 yii\web\UrlNormalizer|null getNormalizer ( $manager )
$manager yii\web\UrlManager

URL 管理器

                protected function getNormalizer($manager)
{
    if ($this->normalizer === null) {
        return $manager->normalizer;
    }
    return $this->normalizer;
}

            
getParamRules() 受保护方法 (自版本 2.0.6 起可用)

返回用于匹配参数的正则表达式列表。

受保护 array getParamRules ( )
返回值 array

参数键和正则表达式规则。

                protected function getParamRules()
{
    return $this->_paramRules;
}

            
hasMethod() 公共方法

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

返回一个值,指示方法是否已定义。

默认实现是调用 PHP 函数 method_exists()。当您实现了 PHP 魔术方法 __call() 时,您可以重写此方法。

公共 boolean hasMethod ( $name )
$name string

方法名称

返回值 boolean

方法是否已定义

                public function hasMethod($name)
{
    return method_exists($this, $name);
}

            
hasNormalizer() 受保护方法 (自版本 2.0.10 起可用)

受保护 boolean hasNormalizer ( $manager )
$manager yii\web\UrlManager

URL 管理器

                protected function hasNormalizer($manager)
{
    return $this->getNormalizer($manager) instanceof UrlNormalizer;
}

            
hasProperty() 公共方法

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

返回一个值,指示属性是否已定义。

如果属性已定义,则

  • 类具有与指定名称关联的 getter 或 setter 方法(在这种情况下,属性名称不区分大小写);
  • 类具有与指定名称相同的成员变量(当$checkVars为 true 时);

另请参阅

公共 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() 公共方法

初始化此规则。

公共 void init ( )

                public function init()
{
    if ($this->pattern === null) {
        throw new InvalidConfigException('UrlRule::pattern must be set.');
    }
    if ($this->route === null) {
        throw new InvalidConfigException('UrlRule::route must be set.');
    }
    if (is_array($this->normalizer)) {
        $normalizerConfig = array_merge(['class' => UrlNormalizer::className()], $this->normalizer);
        $this->normalizer = Yii::createObject($normalizerConfig);
    }
    if ($this->normalizer !== null && $this->normalizer !== false && !$this->normalizer instanceof UrlNormalizer) {
        throw new InvalidConfigException('Invalid config for UrlRule::normalizer.');
    }
    if ($this->verb !== null) {
        if (is_array($this->verb)) {
            foreach ($this->verb as $i => $verb) {
                $this->verb[$i] = strtoupper($verb);
            }
        } else {
            $this->verb = [strtoupper($this->verb)];
        }
    }
    if ($this->name === null) {
        $this->name = $this->pattern;
    }
    $this->preparePattern();
}

            
parseRequest() 公共方法

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

公共 array|boolean parseRequest ( $manager, $request )
$manager yii\web\UrlManager

URL 管理器

$request yii\web\Request

请求组件

返回值 array|boolean

解析结果。路由和参数作为数组返回。如果为 false,则表示此规则不能用于解析此路径信息。

                public function parseRequest($manager, $request)
{
    if ($this->mode === self::CREATION_ONLY) {
        return false;
    }
    if (!empty($this->verb) && !in_array($request->getMethod(), $this->verb, true)) {
        return false;
    }
    $suffix = (string) ($this->suffix === null ? $manager->suffix : $this->suffix);
    $pathInfo = $request->getPathInfo();
    $normalized = false;
    if ($this->hasNormalizer($manager)) {
        $pathInfo = $this->getNormalizer($manager)->normalizePathInfo($pathInfo, $suffix, $normalized);
    }
    if ($suffix !== '' && $pathInfo !== '') {
        $n = strlen($suffix);
        if (substr_compare($pathInfo, $suffix, -$n, $n) === 0) {
            $pathInfo = substr($pathInfo, 0, -$n);
            if ($pathInfo === '') {
                // suffix alone is not allowed
                return false;
            }
        } else {
            return false;
        }
    }
    if ($this->host !== null) {
        $pathInfo = strtolower($request->getHostInfo()) . ($pathInfo === '' ? '' : '/' . $pathInfo);
    }
    if (!preg_match($this->pattern, $pathInfo, $matches)) {
        return false;
    }
    $matches = $this->substitutePlaceholderNames($matches);
    foreach ($this->defaults as $name => $value) {
        if (!isset($matches[$name]) || $matches[$name] === '') {
            $matches[$name] = $value;
        }
    }
    $params = $this->defaults;
    $tr = [];
    foreach ($matches as $name => $value) {
        if (isset($this->_routeParams[$name])) {
            $tr[$this->_routeParams[$name]] = $value;
            unset($params[$name]);
        } elseif (isset($this->_paramRules[$name])) {
            $params[$name] = $value;
        }
    }
    if ($this->_routeRule !== null) {
        $route = strtr($this->route, $tr);
    } else {
        $route = $this->route;
    }
    Yii::debug("Request parsed with URL rule: {$this->name}", __METHOD__);
    if ($normalized) {
        // pathInfo was changed by normalizer - we need also normalize route
        return $this->getNormalizer($manager)->normalizeRoute([$route, $params]);
    }
    return [$route, $params];
}

            
substitutePlaceholderNames() 受保护方法 (自版本 2.0.7 起可用)

遍历 $placeholders 并检查每个占位符是否作为键存在于 $matches 数组中。

找到后 - 将此占位符键替换为匹配参数的适当名称。用于 parseRequest()createUrl()

另请参阅 $placeholders

受保护 array substitutePlaceholderNames ( array $matches )
$matches array

preg_match() 调用的结果

返回值 array

包含已替换占位符键的输入数组

                protected function substitutePlaceholderNames(array $matches)
{
    foreach ($this->placeholders as $placeholder => $name) {
        if (isset($matches[$placeholder])) {
            $matches[$name] = $matches[$placeholder];
            unset($matches[$placeholder]);
        }
    }
    return $matches;
}