# HttpCache

> HttpCache implements client-side caching by utilizing the Last-Modified and ETag HTTP headers.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [filters](/docs/api/yii/filters/index.md) › HttpCache

| class | `yii\filters\HttpCache` |
| --- | --- |
| Extends | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/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/filters/HttpCache.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/filters/HttpCache.php#L50) |

HttpCache implements client-side caching by utilizing the `Last-Modified` and `ETag` HTTP headers.

It is an action filter that can be added to a controller and handles the `beforeAction` event.

To use HttpCache, declare it in the `behaviors()` method of your controller class.
In the following example the filter will be applied to the `index` action and
the Last-Modified header will contain the date of the last update to the user table in the database.

```
public function behaviors()
{
    return [
        [
            'class' => 'yii\filters\HttpCache',
            'only' => ['index'],
            'lastModified' => function ($action, $params) {
                $q = new \yii\db\Query();
                return $q->from('user')->max('updated_at');
            },
//            'etagSeed' => function ($action, $params) {
//                return // generate ETag seed here
//            }
        ],
    ];
}
```

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$cacheControlHeader`](#property-cacheControlHeader) | `string\|null` | The value of the `Cache-Control` HTTP header. Default: `'public, max-age=3600'`. | `HttpCache` |
| <span id="property-enabled"></span>`$enabled` | `bool` | A value indicating whether this filter should be enabled. Default: `true`. | `HttpCache` |
| [`$etagSeed`](#property-etagSeed) | `callable` | A PHP callback that generates the ETag seed string. Default: `null`. | `HttpCache` |
| <span id="property-except"></span>[`$except`](/docs/api/yii/base/actionfilter/index.md#property-except) | `array` | List of action IDs that this filter should not apply to. Default: `[]`. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| [`$lastModified`](#property-lastModified) | `callable` | A PHP callback that returns the UNIX timestamp of the last modification time. Default: `null`. | `HttpCache` |
| <span id="property-only"></span>[`$only`](/docs/api/yii/base/actionfilter/index.md#property-only) | `array` | List of action IDs that this filter should apply to. Default: `[]`. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <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-params"></span>`$params` | `mixed` | Additional parameters that should be passed to the [`$lastModified`](/docs/api/yii/filters/httpcache/index.md#property-lastModified) and [`$etagSeed`](/docs/api/yii/filters/httpcache/index.md#property-etagSeed) callbacks. Default: `null`. | `HttpCache` |
| [`$sessionCacheLimiter`](#property-sessionCacheLimiter) | `string\|null` | The name of the cache limiter to be set when [session_cache_limiter()](https://www.php.net/manual/en/function.session-cache-limiter.php) is called. Default: `''`. | `HttpCache` |
| [`$weakEtag`](#property-weakEtag) | `bool` | Whether to generate weak ETags. Default: `false`. Available since 2.0.8. | `HttpCache` |

## 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-afterAction"></span>[`afterAction()`](/docs/api/yii/base/actionfilter/index.md#method-afterAction) | This method is invoked right after an action is executed. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-afterFilter"></span>[`afterFilter()`](/docs/api/yii/base/actionfilter/index.md#method-afterFilter) |  | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-attach"></span>[`attach()`](/docs/api/yii/base/actionfilter/index.md#method-attach) | Attaches the behavior object to the component. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| [`beforeAction()`](#method-beforeAction) | This method is invoked right before an action is to be executed (after all possible filters.) You may override this method to do last-minute preparation for the action. | `HttpCache` |
| <span id="method-beforeFilter"></span>[`beforeFilter()`](/docs/api/yii/base/actionfilter/index.md#method-beforeFilter) |  | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/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/actionfilter/index.md#method-detach) | Detaches the behavior object from the component. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/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) |
| [`generateEtag()`](#method-generateEtag) protected | Generates an ETag from the given seed string. | `HttpCache` |
| <span id="method-getActionId"></span>[`getActionId()`](/docs/api/yii/base/actionfilter/index.md#method-getActionId) protected | Returns an action ID by converting [`Action::$uniqueId`](/docs/api/yii/base/action/index.md#property-uniqueId) into an ID relative to the module. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-isActive"></span>[`isActive()`](/docs/api/yii/base/actionfilter/index.md#method-isActive) protected | Returns a value indicating whether the filter is active for the given action. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| [`sendCacheControlHeader()`](#method-sendCacheControlHeader) protected | Sends the cache control header to the client. | `HttpCache` |
| [`validateCache()`](#method-validateCache) protected | Validates if the HTTP cache contains valid content. | `HttpCache` |

## Property details

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

```php
public string|null $cacheControlHeader = 'public, max-age=3600'
```

The value of the `Cache-Control` HTTP header.

If null, the header will not be sent.

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

```php
public callable $etagSeed = null
```

A PHP callback that generates the ETag seed string.

The callback's signature should be:

```
function ($action, $params)
```

where `$action` is the [`Action`](/docs/api/yii/base/action/index.md) object that this filter is currently handling;
`$params` takes the value of [`$params`](/docs/api/yii/filters/httpcache/index.md#property-params). The callback should return a string serving
as the seed for generating an ETag.

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

```php
public callable $lastModified = null
```

A PHP callback that returns the UNIX timestamp of the last modification time.

The callback's signature should be:

```
function ($action, $params)
```

where `$action` is the [`Action`](/docs/api/yii/base/action/index.md) object that this filter is currently handling;
`$params` takes the value of [`$params`](/docs/api/yii/filters/httpcache/index.md#property-params). The callback should return a UNIX timestamp.

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

```php
public string|null $sessionCacheLimiter = ''
```

The name of the cache limiter to be set when [session_cache_limiter()](https://www.php.net/manual/en/function.session-cache-limiter.php) is called.

The default value is an empty string, meaning turning off automatic sending of cache headers entirely.
You may set this property to be `public`, `private`, `private_no_expire`, and `nocache`.
Please refer to [session_cache_limiter()](https://www.php.net/manual/en/function.session-cache-limiter.php)
for detailed explanation of these values.

If this property is `null`, then `session_cache_limiter()` will not be called. As a result,
PHP will send headers according to the `session.cache_limiter` PHP ini setting.

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

```php
public bool $weakEtag = false
```

Whether to generate weak ETags.

Weak ETags should be used if the content should be considered semantically equivalent, but not byte-equal.

**Since**

2.0.8

## Method details

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

```php
public function beforeAction(mixed $action): bool
```

This method is invoked right before an action is to be executed (after all possible filters.)
You may override this method to do last-minute preparation for the action.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$action` | `mixed` | The action to be executed. |

**Returns**

`bool`: Whether the action should continue to be executed.

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

```php
protected function generateEtag(string $seed): string
```

Generates an ETag from the given seed string.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$seed` | `string` | Seed for the ETag |

**Returns**

`string`: The generated ETag

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

```php
protected function sendCacheControlHeader(): mixed
```

Sends the cache control header to the client.

**Returns**

`mixed`

**See also**

- [`$cacheControlHeader`](/docs/api/yii/filters/httpcache/index.md#property-cacheControlHeader)

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

```php
protected function validateCache(int|null $lastModified, string|null $etag): bool
```

Validates if the HTTP cache contains valid content.

If both Last-Modified and ETag are null, returns false.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$lastModified` | `int\|null` | The calculated Last-Modified value in terms of a UNIX timestamp. If null, the Last-Modified header will not be validated. |
| `$etag` | `string\|null` | The calculated ETag value. If null, the ETag header will not be validated. |

**Returns**

`bool`: Whether the HTTP cache is still valid.