HumHub Documentation (unofficial)

UrlRule extends BaseObject
in package

Application

implements UrlRuleInterface

UrlRule represents a rule used by [[UrlManager]] for parsing and generating URLs.

To define your own URL parsing and creation logic you can extend from this class and add it to [[UrlManager::rules]] like this:

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

Interfaces

UrlRuleInterface: UrlRuleInterface is the interface that should be implemented by URL rule classes.

Constants

CREATE_STATUS_PARAMS_MISMATCH = 4: Represents the unsuccessful URL generation by last [[createUrl()]] call, because of mismatched or missing parameters.
CREATE_STATUS_PARSING_ONLY = 1: Represents the unsuccessful URL generation by last [[createUrl()]] call, because rule does not support creating URLs.
CREATE_STATUS_ROUTE_MISMATCH = 2: Represents the unsuccessful URL generation by last [[createUrl()]] call, because of mismatched route.
CREATE_STATUS_SUCCESS = 0: Represents the successful URL generation by last [[createUrl()]] call.
CREATION_ONLY = 2: Set [[mode]] with this value to mark that this rule is for URL creation only.
PARSING_ONLY = 1: Set [[mode]] with this value to mark that this rule is for URL parsing only.

Properties

$createUrlStatus : int|null
$defaults : array<string|int, mixed>
$encodeParams : bool
$host : string|null
$mode : int|null
$name : string|null
$normalizer : UrlNormalizer|array<string|int, mixed>|false|null
$pattern : string: On the rule initialization, the [[pattern]] matching parameters names will be replaced with [[placeholders]].
$route : string
$suffix : string|null
$verb : string|array<string|int, mixed>|null
$createStatus : int|null
$placeholders : array<string|int, mixed>
$_paramRules : array<string|int, mixed>
$_routeParams : array<string|int, mixed>
$_routeRule : string
$_template : string

Methods

__call() : mixed: Calls the named method which is not a class method.
__construct() : mixed: Constructor.
__get() : mixed: Returns the value of an object property.
__isset() : bool: Checks if a property is set, i.e. defined and not null.
__set() : mixed: Sets value of an object property.
__toString() : string
__unset() : mixed: Sets an object property to null.
canGetProperty() : bool: Returns a value indicating whether a property can be read.
canSetProperty() : bool: Returns a value indicating whether a property can be set.
className() : string: Returns the fully qualified name of this class.
createUrl() : string|bool: Creates a URL according to the given route and parameters.
getCreateUrlStatus() : int|null: Returns status of the URL creation after the last [[createUrl()]] call.
hasMethod() : bool: Returns a value indicating whether a method is defined.
hasProperty() : bool: Returns a value indicating whether a property is defined.
init() : mixed: Initializes this rule.
parseRequest() : array<string|int, mixed>|bool: Parses the given request and returns the corresponding route and parameters.
getNormalizer() : UrlNormalizer|null
getParamRules() : array<string|int, mixed>: Returns list of regex for matching parameter.
hasNormalizer() : bool
substitutePlaceholderNames() : array<string|int, mixed>: Iterates over [[placeholders]] and checks whether each placeholder exists as a key in $matches array.
preparePattern() : mixed: Process [[$pattern]] on rule initialization.
translatePattern() : mixed: Prepares [[$pattern]] on rule initialization - replace parameter names by placeholders.
trimSlashes() : string: Trim slashes in passed string. If string begins with '//', two slashes are left as is in the beginning of a string.

CREATE_STATUS_PARAMS_MISMATCH

Represents the unsuccessful URL generation by last [[createUrl()]] call, because of mismatched or missing parameters.


    public
        mixed
    CREATE_STATUS_PARAMS_MISMATCH
    = 4

CREATE_STATUS_PARSING_ONLY

Represents the unsuccessful URL generation by last [[createUrl()]] call, because rule does not support creating URLs.


    public
        mixed
    CREATE_STATUS_PARSING_ONLY
    = 1

CREATE_STATUS_ROUTE_MISMATCH

Represents the unsuccessful URL generation by last [[createUrl()]] call, because of mismatched route.


    public
        mixed
    CREATE_STATUS_ROUTE_MISMATCH
    = 2

CREATE_STATUS_SUCCESS

Represents the successful URL generation by last [[createUrl()]] call.


    public
        mixed
    CREATE_STATUS_SUCCESS
    = 0

CREATION_ONLY

Set [[mode]] with this value to mark that this rule is for URL creation only.


    public
        mixed
    CREATION_ONLY
    = 2

PARSING_ONLY

Set [[mode]] with this value to mark that this rule is for URL parsing only.


    public
        mixed
    PARSING_ONLY
    = 1

$createUrlStatus read-only


    public
        int|null
    $createUrlStatus

Status of the URL creation after the last [[createUrl()]] call. null if rule does not provide info about create status.

$defaults


    public
        array<string|int, mixed>
    $defaults
     = []

the default GET parameters (name => value) that this rule provides. When this rule is used to parse the incoming request, the values declared in this property will be injected into $_GET.

$encodeParams


    public
        bool
    $encodeParams
     = true

a value indicating if parameters should be url encoded.

$host


    public
        string|null
    $host

the pattern used to parse and create the host info part of a URL (e.g. https://example.com).

$mode


    public
        int|null
    $mode

a value indicating if this rule should be used for both request parsing and URL creation, parsing only, or creation only. If not set or 0, it means the rule is both request parsing and URL creation. If it is [[PARSING_ONLY]], the rule is for request parsing only. If it is [[CREATION_ONLY]], the rule is for URL creation only.

$name


    public
        string|null
    $name

the name of this rule. If not set, it will use [[pattern]] as the name.

$normalizer


    public
        UrlNormalizer|array<string|int, mixed>|false|null
    $normalizer

the configuration for [[UrlNormalizer]] used by this rule. If null, [[UrlManager::normalizer]] will be used, if false, normalization will be skipped for this rule.

$pattern

On the rule initialization, the [[pattern]] matching parameters names will be replaced with [[placeholders]].


    public
        string
    $pattern

the pattern used to parse and create the path info part of a URL.

$route


    public
        string
    $route

the route to the controller action

$suffix


    public
        string|null
    $suffix

the URL suffix used for this rule. For example, ".html" can be used so that the URL looks like pointing to a static HTML page. If not set, the value of [[UrlManager::suffix]] will be used.

$verb


    public
        string|array<string|int, mixed>|null
    $verb

the HTTP verb (e.g. GET, POST, DELETE) that this rule should match. Use array to represent multiple verbs that this rule may match. If this property is not set, the rule can match any verb. Note that this property is only used when parsing a request. It is ignored for URL creation.

$createStatus


    protected
        int|null
    $createStatus

status of the URL creation after the last [[createUrl()]] call.

$placeholders


    protected
        array<string|int, mixed>
    $placeholders
     = []

list of placeholders for matching parameters names. Used in [[parseRequest()]], [[createUrl()]]. On the rule initialization, the [[pattern]] parameters names will be replaced with placeholders. This array contains relations between the original parameters names and their placeholders. The array keys are the placeholders and the values are the original names.

$_paramRules


    private
        array<string|int, mixed>
    $_paramRules
     = []

list of regex for matching parameters. This is used in generating URL.

$_routeParams


    private
        array<string|int, mixed>
    $_routeParams
     = []

list of parameters used in the route.

$_routeRule


    private
        string
    $_routeRule

the regex for matching the route part. This is used in generating URL.

$_template


    private
        string
    $_template

the template for generating a new URL. This is derived from [[pattern]] and is used in generating URL.

__call()

Calls the named method which is not a class method.


    public
                    __call(string $name, array<string|int, mixed> $params) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when an unknown method is being invoked.

Parameters

$name : string: the method name
$params : array<string|int, mixed>: method parameters

Return values

mixed —

the method return value

__construct()

Constructor.


    public
                    __construct([array<string|int, mixed> $config = [] ]) : mixed

The default implementation does two things:

Initializes the object with the given configuration $config.
Call [[init()]].

If this method is overridden in a child class, it is recommended that

the last parameter of the constructor is a configuration array, like $config here.
call the parent implementation at the end of the constructor.

Parameters

$config : array<string|int, mixed> = []: name-value pairs that will be used to initialize the object properties

__get()

Returns the value of an object property.


    public
                    __get(string $name) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $value = $object->property;.

Parameters

$name : string: the property name

Return values

mixed —

the property value

__isset()

Checks if a property is set, i.e. defined and not null.


    public
                    __isset(string $name) : bool

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing isset($object->property).

Note that if the property is not defined, false will be returned.

Parameters

$name : string: the property name or the event name

Return values

bool —

whether the named property is set (not null).

__set()

Sets value of an object property.


    public
                    __set(string $name, mixed $value) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $object->property = $value;.

Parameters

$name : string: the property name or the event name
$value : mixed: the property value

__toString()


    public
                    __toString() : string

Return values

string

__unset()

Sets an object property to null.


    public
                    __unset(string $name) : mixed

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing unset($object->property).

Note that if the property is not defined, this method will do nothing. If the property is read-only, it will throw an exception.

Parameters

$name : string: the property name

canGetProperty()

Returns a value indicating whether a property can be read.


    public
                    canGetProperty(string $name[, bool $checkVars = true ]) : bool

A property is readable if:

the class has a getter method associated with the specified name (in this case, property name is case-insensitive);
the class has a member variable with the specified name (when $checkVars is true);

Parameters

$name : string: the property name
$checkVars : bool = true: whether to treat member variables as properties

Return values

bool —

whether the property can be read

canSetProperty()

Returns a value indicating whether a property can be set.


    public
                    canSetProperty(string $name[, bool $checkVars = true ]) : bool

A property is writable if:

the class has a setter method associated with the specified name (in this case, property name is case-insensitive);
the class has a member variable with the specified name (when $checkVars is true);

Parameters

$name : string: the property name
$checkVars : bool = true: whether to treat member variables as properties

Return values

bool —

whether the property can be written

className()

Returns the fully qualified name of this class.


    public
            static        className() : string

Return values

string —

the fully qualified name of this class.

createUrl()

Creates a URL according to the given route and parameters.


    public
                    createUrl(UrlManager $manager, string $route, array<string|int, mixed> $params) : string|bool

Parameters

$manager : UrlManager: the URL manager
$route : string: the route. It should not have slashes at the beginning or the end.
$params : array<string|int, mixed>: the parameters

Return values

string|bool —

the created URL, or false if this rule cannot be used for creating this URL.

getCreateUrlStatus()

Returns status of the URL creation after the last [[createUrl()]] call.


    public
                    getCreateUrlStatus() : int|null

Return values

int|null —

Status of the URL creation after the last [[createUrl()]] call. null if rule does not provide info about create status.

hasMethod()

Returns a value indicating whether a method is defined.


    public
                    hasMethod(string $name) : bool

The default implementation is a call to php function method_exists(). You may override this method when you implemented the php magic method __call().

Parameters

$name : string: the method name

Return values

bool —

whether the method is defined

hasProperty()

Returns a value indicating whether a property is defined.


    public
                    hasProperty(string $name[, bool $checkVars = true ]) : bool

A property is defined if:

the class has a getter or setter method associated with the specified name (in this case, property name is case-insensitive);
the class has a member variable with the specified name (when $checkVars is true);

Parameters

$name : string: the property name
$checkVars : bool = true: whether to treat member variables as properties

Return values

bool —

whether the property is defined

init()

Initializes this rule.


    public
                    init() : mixed

parseRequest()

Parses the given request and returns the corresponding route and parameters.


    public
                    parseRequest(UrlManager $manager, Request $request) : array<string|int, mixed>|bool

Parameters

$manager : UrlManager: the URL manager
$request : Request: the request component

Return values

array<string|int, mixed>|bool —

the parsing result. The route and the parameters are returned as an array. If false, it means this rule cannot be used to parse this path info.

getNormalizer()


    protected
                    getNormalizer(UrlManager $manager) : UrlNormalizer|null

Parameters

$manager : UrlManager: the URL manager

Return values

UrlNormalizer|null

getParamRules()

Returns list of regex for matching parameter.


    protected
                    getParamRules() : array<string|int, mixed>

Return values

array<string|int, mixed> —

parameter keys and regexp rules.

hasNormalizer()


    protected
                    hasNormalizer(UrlManager $manager) : bool

Parameters

$manager : UrlManager: the URL manager

Return values

bool

substitutePlaceholderNames()

Iterates over [[placeholders]] and checks whether each placeholder exists as a key in $matches array.


    protected
                    substitutePlaceholderNames(array<string|int, mixed> $matches) : array<string|int, mixed>

When found - replaces this placeholder key with a appropriate name of matching parameter. Used in [[parseRequest()]], [[createUrl()]].

Parameters

$matches : array<string|int, mixed>: result of preg_match() call

Return values

array<string|int, mixed> —

input array with replaced placeholder keys

preparePattern()

Process [[$pattern]] on rule initialization.


    private
                    preparePattern() : mixed

translatePattern()

Prepares [[$pattern]] on rule initialization - replace parameter names by placeholders.


    private
                    translatePattern(bool $allowAppendSlash) : mixed

Parameters

$allowAppendSlash : bool: Defines position of slash in the param pattern in [[$pattern]]. If false slash will be placed at the beginning of param pattern. If true slash position will be detected depending on non-optional pattern part.

trimSlashes()

Trim slashes in passed string. If string begins with '//', two slashes are left as is in the beginning of a string.


    private
                    trimSlashes(string $string) : string

Parameters

$string : string

Return values

string

UrlRule extends BaseObject in package Application implements UrlRuleInterface

Tags

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

CREATE_STATUS_PARAMS_MISMATCH

Tags

CREATE_STATUS_PARSING_ONLY

Tags

CREATE_STATUS_ROUTE_MISMATCH

Tags

CREATE_STATUS_SUCCESS

Tags

CREATION_ONLY

PARSING_ONLY

Properties

$createUrlStatus read-only

$defaults

$encodeParams

$host

Tags

$mode

$name

$normalizer

Tags

$pattern

Tags

$route

$suffix

$verb

$createStatus

Tags

$placeholders

Tags

$_paramRules

$_routeParams

$_routeRule

$_template

Methods

__call()

Parameters

Tags

Return values

__construct()

Parameters

__get()

Parameters

Tags

Return values

__isset()

Parameters

Tags

Return values

__set()

Parameters

Tags

__toString()

Tags

Return values

__unset()

Parameters

Tags

canGetProperty()

Parameters

Tags

Return values

canSetProperty()

Parameters

Tags

Return values

UrlRule extends BaseObject
in package

Application

implements UrlRuleInterface