# UrlRule

> UrlRule represents a rule used by yii\web\UrlManager for parsing and generating URLs.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [web](/docs/api/yii/web/index.md) › UrlRule

| class | `yii\web\UrlRule` |
| --- | --- |
| Extends | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`UrlRuleInterface`](/docs/api/yii/web/urlruleinterface/index.md), [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/web/UrlRule.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/web/UrlRule.php#L34) |

UrlRule represents a rule used by [`UrlManager`](/docs/api/yii/web/urlmanager/index.md) 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`](/docs/api/yii/web/urlmanager/index.md#property-rules) like this:

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

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-createUrlStatus"></span>`$createUrlStatus` read-only | `int\|null` | Status of the URL creation after the last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call. `null` if rule does not provide info about create status. | `UrlRule` |
| [`$defaults`](#property-defaults) | `array` | The default GET parameters (name => value) that this rule provides. Default: `[]`. | `UrlRule` |
| <span id="property-encodeParams"></span>`$encodeParams` | `bool` | A value indicating if parameters should be url encoded. Default: `true`. | `UrlRule` |
| <span id="property-host"></span>`$host` | `string\|null` | The pattern used to parse and create the host info part of a URL (e.g. `https://example.com`). Default: `null`. | `UrlRule` |
| [`$mode`](#property-mode) | `int\|null` | A value indicating if this rule should be used for both request parsing and URL creation, parsing only, or creation only. Default: `null`. | `UrlRule` |
| [`$name`](#property-name) | `string\|null` | The name of this rule. Default: `null`. | `UrlRule` |
| [`$normalizer`](#property-normalizer) | [`UrlNormalizer`](/docs/api/yii/web/urlnormalizer/index.md)`\|array\|false\|null` | The configuration for [`UrlNormalizer`](/docs/api/yii/web/urlnormalizer/index.md) used by this rule. Default: `null`. Available since 2.0.10. | `UrlRule` |
| <span id="property-pattern"></span>`$pattern` | `string` | The pattern used to parse and create the path info part of a URL. Default: `null`. | `UrlRule` |
| <span id="property-route"></span>`$route` | `string` | The route to the controller action Default: `null`. | `UrlRule` |
| [`$suffix`](#property-suffix) | `string\|null` | The URL suffix used for this rule. Default: `null`. | `UrlRule` |
| [`$verb`](#property-verb) | `string\|array\|null` | The HTTP verb (e.g. Default: `null`. | `UrlRule` |
| <span id="property-createStatus"></span>`$createStatus` protected | `int\|null` | Status of the URL creation after the last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call. Default: `null`. Available since 2.0.12. | `UrlRule` |
| [`$placeholders`](#property-placeholders) protected | `array` | List of placeholders for matching parameters names. Default: `[]`. Available since 2.0.7. | `UrlRule` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/baseobject/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/baseobject/index.md#method-__get) | Returns the value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/baseobject/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/baseobject/index.md#method-__set) | Sets value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`__toString()`](#method-__toString) |  | `UrlRule` |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/baseobject/index.md#method-__unset) | Sets an object property to null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`createUrl()`](#method-createUrl) | Creates a URL according to the given route and parameters. | `UrlRule` |
| [`getCreateUrlStatus()`](#method-getCreateUrlStatus) | Returns status of the URL creation after the last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call. | `UrlRule` |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/baseobject/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/baseobject/index.md#method-hasProperty) | Returns a value indicating whether a property is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`init()`](#method-init) | Initializes this rule. | `UrlRule` |
| [`parseRequest()`](#method-parseRequest) | Parses the given request and returns the corresponding route and parameters. | `UrlRule` |
| [`getNormalizer()`](#method-getNormalizer) protected |  | `UrlRule` |
| [`getParamRules()`](#method-getParamRules) protected | Returns list of regex for matching parameter. | `UrlRule` |
| [`hasNormalizer()`](#method-hasNormalizer) protected |  | `UrlRule` |
| [`substitutePlaceholderNames()`](#method-substitutePlaceholderNames) protected | Iterates over [`$placeholders`](/docs/api/yii/web/urlrule/index.md#property-placeholders) and checks whether each placeholder exists as a key in $matches array. | `UrlRule` |

## Constants

| Constant | Value | Description | Defined by |
| --- | --- | --- | --- |
| <span id="const-PARSING_ONLY"></span>`PARSING_ONLY` | `1` | Set [`$mode`](/docs/api/yii/web/urlrule/index.md#property-mode) with this value to mark that this rule is for URL parsing only. | `UrlRule` |
| <span id="const-CREATION_ONLY"></span>`CREATION_ONLY` | `2` | Set [`$mode`](/docs/api/yii/web/urlrule/index.md#property-mode) with this value to mark that this rule is for URL creation only. | `UrlRule` |
| <span id="const-CREATE_STATUS_SUCCESS"></span>`CREATE_STATUS_SUCCESS` | `0` | Represents the successful URL generation by last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call. Available since 2.0.12. | `UrlRule` |
| <span id="const-CREATE_STATUS_PARSING_ONLY"></span>`CREATE_STATUS_PARSING_ONLY` | `1` | Represents the unsuccessful URL generation by last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call, because rule does not support creating URLs. Available since 2.0.12. | `UrlRule` |
| <span id="const-CREATE_STATUS_ROUTE_MISMATCH"></span>`CREATE_STATUS_ROUTE_MISMATCH` | `2` | Represents the unsuccessful URL generation by last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call, because of mismatched route. Available since 2.0.12. | `UrlRule` |
| <span id="const-CREATE_STATUS_PARAMS_MISMATCH"></span>`CREATE_STATUS_PARAMS_MISMATCH` | `4` | Represents the unsuccessful URL generation by last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call, because of mismatched or missing parameters. Available since 2.0.12. | `UrlRule` |

## Property details

### $defaults <span id="property-defaults"></span>

```php
public array $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.

### $mode <span id="property-mode"></span>

```php
public int|null $mode = null
```

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`](/docs/api/yii/web/urlrule/index.md#const-PARSING_ONLY), the rule is for request parsing only.
If it is [`CREATION_ONLY`](/docs/api/yii/web/urlrule/index.md#const-CREATION_ONLY), the rule is for URL creation only.

### $name <span id="property-name"></span>

```php
public string|null $name = null
```

The name of this rule.

If not set, it will use [`$pattern`](/docs/api/yii/web/urlrule/index.md#property-pattern) as the name.

### $normalizer <span id="property-normalizer"></span>

```php
public yii\web\UrlNormalizer|array|false|null $normalizer = null
```

The configuration for [`UrlNormalizer`](/docs/api/yii/web/urlnormalizer/index.md) used by this rule.

If `null`, [`UrlManager::$normalizer`](/docs/api/yii/web/urlmanager/index.md#property-normalizer) will be used, if `false`, normalization will be skipped
for this rule.

**Since**

2.0.10

### $suffix <span id="property-suffix"></span>

```php
public string|null $suffix = null
```

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`](/docs/api/yii/web/urlmanager/index.md#property-suffix) will be used.
Default values should be strings. Non-string values will be automatically converted to
strings for comparison with URL parameters.

### $verb <span id="property-verb"></span>

```php
public string|array|null $verb = null
```

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.

### $placeholders <span id="property-placeholders"></span>

```php
protected array $placeholders = []
```

List of placeholders for matching parameters names.

Used in [`parseRequest()`](/docs/api/yii/web/urlrule/index.md#method-parseRequest), [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl).
On the rule initialization, the [`$pattern`](/docs/api/yii/web/urlrule/index.md#property-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.

**Since**

2.0.7

## Method details

### __toString() <span id="method-__toString"></span>

```php
public function __toString(): string
```

**Returns**

`string`

**Since**

2.0.11

### createUrl() <span id="method-createUrl"></span>

```php
public function createUrl(yii\web\UrlManager $manager, string $route, array $params): string|bool
```

Creates a URL according to the given route and parameters.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$manager` | [`UrlManager`](/docs/api/yii/web/urlmanager/index.md) | The URL manager |
| `$route` | `string` | The route. It should not have slashes at the beginning or the end. |
| `$params` | `array` | The parameters |

**Returns**

`string|bool`: The created URL, or `false` if this rule cannot be used for creating this URL.

### getCreateUrlStatus() <span id="method-getCreateUrlStatus"></span>

```php
public function getCreateUrlStatus(): int|null
```

Returns status of the URL creation after the last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call.

**Returns**

`int|null`: Status of the URL creation after the last [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl) call. `null` if rule does not provide info about create status.

**Since**

2.0.12

**See also**

- [`$createStatus`](/docs/api/yii/web/urlrule/index.md#property-createStatus)

### init() <span id="method-init"></span>

```php
public function init(): mixed
```

Initializes this rule.

**Returns**

`mixed`

### parseRequest() <span id="method-parseRequest"></span>

```php
public function parseRequest(yii\web\UrlManager $manager, yii\web\Request $request): array|bool
```

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

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$manager` | [`UrlManager`](/docs/api/yii/web/urlmanager/index.md) | The URL manager |
| `$request` | [`Request`](/docs/api/yii/web/request/index.md) | The request component |

**Returns**

`array|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() <span id="method-getNormalizer"></span>

```php
protected function getNormalizer(yii\web\UrlManager $manager): yii\web\UrlNormalizer|null
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$manager` | [`UrlManager`](/docs/api/yii/web/urlmanager/index.md) | The URL manager |

**Returns**

[`UrlNormalizer`](/docs/api/yii/web/urlnormalizer/index.md)`|null`

**Since**

2.0.10

### getParamRules() <span id="method-getParamRules"></span>

```php
protected function getParamRules(): array
```

Returns list of regex for matching parameter.

**Returns**

`array`: Parameter keys and regexp rules.

**Since**

2.0.6

### hasNormalizer() <span id="method-hasNormalizer"></span>

```php
protected function hasNormalizer(yii\web\UrlManager $manager): bool
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$manager` | [`UrlManager`](/docs/api/yii/web/urlmanager/index.md) | The URL manager |

**Returns**

`bool`

**Since**

2.0.10

### substitutePlaceholderNames() <span id="method-substitutePlaceholderNames"></span>

```php
protected function substitutePlaceholderNames(array $matches): array
```

Iterates over [`$placeholders`](/docs/api/yii/web/urlrule/index.md#property-placeholders) and checks whether each placeholder exists as a key in $matches array.

When found - replaces this placeholder key with a appropriate name of matching parameter.
Used in [`parseRequest()`](/docs/api/yii/web/urlrule/index.md#method-parseRequest), [`createUrl()`](/docs/api/yii/web/urlrule/index.md#method-createUrl).

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$matches` | `array` | Result of `preg_match()` call |

**Returns**

`array`: Input array with replaced placeholder keys

**Since**

2.0.7

**See also**

- [`$placeholders`](/docs/api/yii/web/urlrule/index.md#property-placeholders)