# SluggableBehavior

> SluggableBehavior automatically fills the specified attribute with a value that can be used a slug in a URL.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [behaviors](/docs/api/yii/behaviors/index.md) › SluggableBehavior

| class | `yii\behaviors\SluggableBehavior` |
| --- | --- |
| Extends | [`AttributeBehavior`](/docs/api/yii/behaviors/attributebehavior/index.md) » [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/behaviors/SluggableBehavior.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/behaviors/SluggableBehavior.php#L68) |

SluggableBehavior automatically fills the specified attribute with a value that can be used a slug in a URL.

Note: This behavior relies on php-intl extension for transliteration. If it is not installed it
falls back to replacements defined in [`Inflector::$transliteration`](/docs/api/yii/helpers/baseinflector/index.md#property-transliteration).

To use SluggableBehavior, insert the following code to your ActiveRecord class:

```
use yii\behaviors\SluggableBehavior;

public function behaviors()
{
    return [
        [
            'class' => SluggableBehavior::class,
            'attribute' => 'title',
            // 'slugAttribute' => 'slug',
        ],
    ];
}
```

By default, SluggableBehavior will fill the `slug` attribute with a value that can be used a slug in a URL
when the associated AR object is being validated.

Because attribute values will be set automatically by this behavior, they are usually not user input and should therefore
not be validated, i.e. the `slug` attribute should not appear in the [rules()](/docs/api/yii/base/model/index.md#method-rules) method of the model.

If your attribute name is different, you may configure the [`$slugAttribute`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-slugAttribute) property like the following:

```
public function behaviors()
{
    return [
        [
            'class' => SluggableBehavior::class,
            'slugAttribute' => 'alias',
        ],
    ];
}
```

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-attribute"></span>`$attribute` | `string\|array\|null` | The attribute or list of attributes whose value will be converted into a slug or `null` meaning that the `$value` property will be used to generate a slug. Default: `null`. | `SluggableBehavior` |
| <span id="property-attributes"></span>[`$attributes`](/docs/api/yii/behaviors/attributebehavior/index.md#property-attributes) | `array` | List of attributes that are to be automatically filled with the value specified via [`$value`](/docs/api/yii/behaviors/attributebehavior/index.md#property-value). Default: `[]`. | [`AttributeBehavior`](/docs/api/yii/behaviors/attributebehavior/index.md) |
| [`$ensureUnique`](#property-ensureUnique) | `bool` | Whether to ensure generated slug value to be unique among owner class records. Default: `false`. | `SluggableBehavior` |
| [`$immutable`](#property-immutable) | `bool` | Whether to generate a new slug if it has already been generated before. Default: `false`. Available since 2.0.2. | `SluggableBehavior` |
| <span id="property-owner"></span>[`$owner`](/docs/api/yii/base/behavior/index.md#property-owner) | `yii\base\T\|null` | The owner of this behavior Default: `null`. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) |
| <span id="property-preserveNonEmptyValues"></span>[`$preserveNonEmptyValues`](/docs/api/yii/behaviors/attributebehavior/index.md#property-preserveNonEmptyValues) | `bool` | Whether to preserve non-empty attribute values. Default: `false`. Available since 2.0.13. | [`AttributeBehavior`](/docs/api/yii/behaviors/attributebehavior/index.md) |
| [`$skipOnEmpty`](#property-skipOnEmpty) | `bool` | Whether to skip slug generation if [`$attribute`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-attribute) is null or an empty string. Default: `false`. Available since 2.0.13. | `SluggableBehavior` |
| <span id="property-skipUpdateOnClean"></span>[`$skipUpdateOnClean`](/docs/api/yii/behaviors/attributebehavior/index.md#property-skipUpdateOnClean) | `bool` | Whether to skip this behavior when the `$owner` has not been modified Default: `true`. Available since 2.0.8. | [`AttributeBehavior`](/docs/api/yii/behaviors/attributebehavior/index.md) |
| <span id="property-slugAttribute"></span>`$slugAttribute` | `string` | The attribute that will receive the slug value Default: `'slug'`. | `SluggableBehavior` |
| [`$uniqueSlugGenerator`](#property-uniqueSlugGenerator) | `callable\|null` | Slug unique value generator. Default: `null`. | `SluggableBehavior` |
| [`$uniqueValidator`](#property-uniqueValidator) | `array` | Configuration for slug uniqueness validator. Default: `[]`. | `SluggableBehavior` |
| [`$value`](#property-value) | `callable\|string\|null` | The value that will be used as a slug. Default: `null`. | `SluggableBehavior` |

## 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) |
| <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-attach"></span>[`attach()`](/docs/api/yii/base/behavior/index.md#method-attach) | Attaches the behavior object to the component. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/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) |
| <span id="method-detach"></span>[`detach()`](/docs/api/yii/base/behavior/index.md#method-detach) | Detaches the behavior object from the component. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) |
| <span id="method-evaluateAttributes"></span>[`evaluateAttributes()`](/docs/api/yii/behaviors/attributebehavior/index.md#method-evaluateAttributes) | Evaluates the attribute value and assigns it to the current attributes. | [`AttributeBehavior`](/docs/api/yii/behaviors/attributebehavior/index.md) |
| <span id="method-events"></span>[`events()`](/docs/api/yii/behaviors/attributebehavior/index.md#method-events) | Declares event handlers for the [`$owner`](/docs/api/yii/base/behavior/index.md#property-owner)'s events. | [`AttributeBehavior`](/docs/api/yii/behaviors/attributebehavior/index.md) |
| <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 the object. | `SluggableBehavior` |
| [`generateSlug()`](#method-generateSlug) protected | This method is called by [`getValue()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-getValue) to generate the slug. | `SluggableBehavior` |
| [`generateUniqueSlug()`](#method-generateUniqueSlug) protected | Generates slug using configured callback or increment of iteration. | `SluggableBehavior` |
| [`getValue()`](#method-getValue) protected | Returns the value for the current attributes. | `SluggableBehavior` |
| [`isEmpty()`](#method-isEmpty) protected | Checks if $slugPart is empty string or null. | `SluggableBehavior` |
| [`isNewSlugNeeded()`](#method-isNewSlugNeeded) protected | Checks whether the new slug generation is needed This method is called by [`getValue()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-getValue) to check whether the new slug generation is needed. | `SluggableBehavior` |
| [`makeUnique()`](#method-makeUnique) protected | This method is called by [`getValue()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-getValue) when [`$ensureUnique`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-ensureUnique) is true to generate the unique slug. | `SluggableBehavior` |
| [`validateSlug()`](#method-validateSlug) protected | Checks if given slug value is unique. | `SluggableBehavior` |

## Property details

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

```php
public bool $ensureUnique = false
```

Whether to ensure generated slug value to be unique among owner class records.

If enabled behavior will validate slug uniqueness automatically. If validation fails it will attempt
generating unique slug value from based one until success.

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

```php
public bool $immutable = false
```

Whether to generate a new slug if it has already been generated before.

If true, the behavior will not generate a new slug even if [`$attribute`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-attribute) is changed.

**Since**

2.0.2

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

```php
public bool $skipOnEmpty = false
```

Whether to skip slug generation if [`$attribute`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-attribute) is null or an empty string.

If true, the behaviour will not generate a new slug if [`$attribute`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-attribute) is null or an empty string.

**Since**

2.0.13

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

```php
public callable|null $uniqueSlugGenerator = null
```

Slug unique value generator.

It is used in case [`$ensureUnique`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-ensureUnique) enabled and generated
slug is not unique. This should be a PHP callable with following signature:

```
function ($baseSlug, $iteration, $model)
{
    // return uniqueSlug
}
```

If not set unique slug will be generated adding incrementing suffix to the base slug.

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

```php
public array $uniqueValidator = []
```

Configuration for slug uniqueness validator.

Parameter 'class' may be omitted - by default
[`UniqueValidator`](/docs/api/yii/validators/uniquevalidator/index.md) will be used.

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

```php
public callable|string|null $value = null
```

The value that will be used as a slug.

This can be an anonymous function
or an arbitrary value or null. If the former, the return value of the function will be used as a slug.
If `null` then the `$attribute` property will be used to generate a slug.
The signature of the function should be as follows,

```
function ($event)
{
    // return slug
}
```

## Method details

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

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

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the
given configuration.

**Returns**

`mixed`

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

```php
protected function generateSlug(array $slugParts): string
```

This method is called by [`getValue()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-getValue) to generate the slug.

You may override it to customize slug generation.
The default implementation calls [`Inflector::slug()`](/docs/api/yii/helpers/baseinflector/index.md#method-slug) on the input strings
concatenated by dashes (`-`).

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$slugParts` | `array` | An array of strings that should be concatenated and converted to generate the slug value. |

**Returns**

`string`: The conversion result.

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

```php
protected function generateUniqueSlug(string $baseSlug, int $iteration): string
```

Generates slug using configured callback or increment of iteration.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$baseSlug` | `string` | Base slug value |
| `$iteration` | `int` | Iteration number |

**Returns**

`string`: New slug value

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md)

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

```php
protected function getValue(mixed $event): mixed
```

Returns the value for the current attributes.

This method is called by [`evaluateAttributes()`](/docs/api/yii/behaviors/attributebehavior/index.md#method-evaluateAttributes). Its return value will be assigned
to the attributes corresponding to the triggering event.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$event` | `mixed` | The event that triggers the current attribute updating. |

**Returns**

`mixed`: The attribute value

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

```php
protected function isEmpty(string $slugPart): bool
```

Checks if $slugPart is empty string or null.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$slugPart` | `string` | One of attributes that is used for slug generation. |

**Returns**

`bool`: Whether $slugPart empty or not.

**Since**

2.0.13

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

```php
protected function isNewSlugNeeded(): bool
```

Checks whether the new slug generation is needed
This method is called by [`getValue()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-getValue) to check whether the new slug generation is needed.

You may override it to customize checking.

**Returns**

`bool`

**Since**

2.0.7

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

```php
protected function makeUnique(string $slug): string
```

This method is called by [`getValue()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-getValue) when [`$ensureUnique`](/docs/api/yii/behaviors/sluggablebehavior/index.md#property-ensureUnique) is true to generate the unique slug.

Calls [`generateUniqueSlug()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-generateUniqueSlug) until generated slug is unique and returns it.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$slug` | `string` | Basic slug value |

**Returns**

`string`: Unique slug

**Since**

2.0.7

**See also**

- [`getValue()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-getValue)
- [`generateUniqueSlug()`](/docs/api/yii/behaviors/sluggablebehavior/index.md#method-generateUniqueSlug)

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

```php
protected function validateSlug(string $slug): bool
```

Checks if given slug value is unique.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$slug` | `string` | Slug value |

**Returns**

`bool`: Whether slug is unique.