# CacheableWidgetBehavior

> Cacheable widget behavior automatically caches widget contents according to duration and dependencies specified.

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

| class | `yii\behaviors\CacheableWidgetBehavior` |
| --- | --- |
| Extends | [`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.14 |
| Source | [`framework/behaviors/CacheableWidgetBehavior.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/behaviors/CacheableWidgetBehavior.php#L51) |

Cacheable widget behavior automatically caches widget contents according to duration and dependencies specified.

The behavior may be used without any configuration if an application has `cache` component configured.
By default the widget will be cached for one minute.

The following example will cache the posts widget for an indefinite duration until any post is modified.

```
use yii\behaviors\CacheableWidgetBehavior;

public function behaviors()
{
    return [
        [
            'class' => CacheableWidgetBehavior::class,
            'cacheDuration' => 0,
            'cacheDependency' => [
                'class' => 'yii\caching\DbDependency',
                'sql' => 'SELECT MAX(updated_at) FROM posts',
            ],
        ],
    ];
}
```

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$cache`](#property-cache) | [`yii\caching\CacheInterface`](/docs/api/yii/caching/cacheinterface/index.md)`\|string\|array` | A cache object or a cache component ID or a configuration array for creating a cache object. Default: `'cache'`. | `CacheableWidgetBehavior` |
| [`$cacheDependency`](#property-cacheDependency) | [`yii\caching\Dependency`](/docs/api/yii/caching/dependency/index.md)`\|array\|null` | A cache dependency or a configuration array for creating a cache dependency or `null` meaning no cache dependency. Default: `null`. | `CacheableWidgetBehavior` |
| [`$cacheDuration`](#property-cacheDuration) | `int` | Cache duration in seconds. Default: `60`. | `CacheableWidgetBehavior` |
| [`$cacheEnabled`](#property-cacheEnabled) | `bool` | Whether to enable caching or not. Default: `true`. | `CacheableWidgetBehavior` |
| [`$cacheKeyVariations`](#property-cacheKeyVariations) | `string[]\|string` | An array of strings or a single string which would cause the variation of the content being cached (e.g. an application language, a GET parameter). Default: `[]`. | `CacheableWidgetBehavior` |
| <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) |

## 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) |
| [`afterRun()`](#method-afterRun) | Outputs widget contents and ends fragment caching. | `CacheableWidgetBehavior` |
| [`attach()`](#method-attach) | Attaches the behavior object to the component. | `CacheableWidgetBehavior` |
| [`beforeRun()`](#method-beforeRun) | Begins fragment caching. Prevents owner widget from execution if its contents can be retrieved from the cache. | `CacheableWidgetBehavior` |
| <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-events"></span>[`events()`](/docs/api/yii/base/behavior/index.md#method-events) | Declares event handlers for the [`$owner`](/docs/api/yii/base/behavior/index.md#property-owner)'s events. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/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) |
| <span id="method-init"></span>[`init()`](/docs/api/yii/base/baseobject/index.md#method-init) | Initializes the object. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |

## Property details

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

```php
public yii\caching\CacheInterface|string|array $cache = 'cache'
```

A cache object or a cache component ID or a configuration array for creating a cache object.

Defaults to the `cache` application component.

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

```php
public yii\caching\Dependency|array|null $cacheDependency = null
```

A cache dependency or a configuration array for creating a cache dependency or `null` meaning no cache dependency.

For example,

```
[
    'class' => 'yii\caching\DbDependency',
    'sql' => 'SELECT MAX(updated_at) FROM posts',
]
```

would make the widget cache depend on the last modified time of all posts.
If any post has its modification time changed, the cached content would be invalidated.

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

```php
public int $cacheDuration = 60
```

Cache duration in seconds.

Set to `0` to indicate that the cached data will never expire.
Defaults to 60 seconds or 1 minute.

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

```php
public bool $cacheEnabled = true
```

Whether to enable caching or not.

Allows to turn the widget caching
on and off according to specific conditions.
The following configuration will disable caching when a special GET parameter is passed:

```
empty(Yii::$app->request->get('disable-caching'))
```

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

```php
public string[]|string $cacheKeyVariations = []
```

An array of strings or a single string which would cause the variation of the content being cached (e.g. an application language, a GET parameter).

The following variation setting will cause the content to be cached in different versions
according to the current application language:

```
[
    Yii::$app->language,
]
```

## Method details

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

```php
public function afterRun(yii\base\WidgetEvent $event): mixed
```

Outputs widget contents and ends fragment caching.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$event` | [`yii\base\WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | `Widget::EVENT_AFTER_RUN` event. |

**Returns**

`mixed`

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

```php
public function attach(mixed $owner): mixed
```

Attaches the behavior object to the component.

The default implementation will set the [`$owner`](/docs/api/yii/base/behavior/index.md#property-owner) property
and attach event handlers as declared in [`events()`](/docs/api/yii/base/behavior/index.md#method-events).
Make sure you call the parent implementation if you override this method.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$owner` | `mixed` | The component that this behavior is to be attached to. |

**Returns**

`mixed`

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

```php
public function beforeRun(yii\base\WidgetEvent $event): mixed
```

Begins fragment caching. Prevents owner widget from execution
if its contents can be retrieved from the cache.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$event` | [`yii\base\WidgetEvent`](/docs/api/yii/base/widgetevent/index.md) | `Widget::EVENT_BEFORE_RUN` event. |

**Returns**

`mixed`