CacheableWidgetBehavior

API reference › yii › behaviors › CacheableWidgetBehavior

class	`yii\behaviors\CacheableWidgetBehavior`
Extends	`yii\base\Behavior` » `yii\base\BaseObject`
Implements	`yii\base\Configurable`
Since	2.0.14
Source	`framework/behaviors/CacheableWidgetBehavior.php`

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`	`yii\caching\CacheInterface\|string\|array`	A cache object or a cache component ID or a configuration array for creating a cache object. Default: `'cache'`.	`CacheableWidgetBehavior`
`$cacheDependency`	`yii\caching\Dependency\|array\|null`	A cache dependency or a configuration array for creating a cache dependency or `null` meaning no cache dependency. Default: `null`.	`CacheableWidgetBehavior`
`$cacheDuration`	`int`	Cache duration in seconds. Default: `60`.	`CacheableWidgetBehavior`
`$cacheEnabled`	`bool`	Whether to enable caching or not. Default: `true`.	`CacheableWidgetBehavior`
`$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`
`$owner`	`yii\base\T\|null`	The owner of this behavior Default: `null`.	`yii\base\Behavior`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__call()`	Calls the named method which is not a class method.	`yii\base\BaseObject`
`__get()`	Returns the value of an object property.	`yii\base\BaseObject`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\BaseObject`
`__set()`	Sets value of an object property.	`yii\base\BaseObject`
`__unset()`	Sets an object property to null.	`yii\base\BaseObject`
`afterRun()`	Outputs widget contents and ends fragment caching.	`CacheableWidgetBehavior`
`attach()`	Attaches the behavior object to the component.	`CacheableWidgetBehavior`
`beforeRun()`	Begins fragment caching. Prevents owner widget from execution if its contents can be retrieved from the cache.	`CacheableWidgetBehavior`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\BaseObject`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\BaseObject`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`detach()`	Detaches the behavior object from the component.	`yii\base\Behavior`
`events()`	Declares event handlers for the `$owner`’s events.	`yii\base\Behavior`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\BaseObject`
`hasProperty()`	Returns a value indicating whether a property is defined.	`yii\base\BaseObject`
`init()`	Initializes the object.	`yii\base\BaseObject`

Property details

$cache

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

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

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

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

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()

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

Outputs widget contents and ends fragment caching.

Parameters

Parameter	Type	Description
`$event`	`yii\base\WidgetEvent`	`Widget::EVENT_AFTER_RUN` event.

Returns

mixed

attach()

public function attach(mixed $owner): mixed

Attaches the behavior object to the component.

The default implementation will set the $owner property and attach event handlers as declared in 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()

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`	`Widget::EVENT_BEFORE_RUN` event.

Returns

mixed