HttpCache.php 6.96 KB
Newer Older
1 2 3 4 5 6 7
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

8
namespace yii\filters;
9 10 11 12 13 14

use Yii;
use yii\base\ActionFilter;
use yii\base\Action;

/**
15
 * HttpCache implements client-side caching by utilizing the `Last-Modified` and `Etag` HTTP headers.
16 17 18
 *
 * It is an action filter that can be added to a controller and handles the `beforeAction` event.
 *
19
 * To use HttpCache, declare it in the `behaviors()` method of your controller class.
20 21 22 23 24 25 26
 * In the following example the filter will be applied to the `list`-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 [
27
 *         [
28
 *             'class' => 'yii\filters\HttpCache',
29
 *             'only' => ['index'],
30
 *             'lastModified' => function ($action, $params) {
31 32
 *                 $q = new \yii\db\Query();
 *                 return $q->from('user')->max('updated_at');
33 34 35 36 37 38 39 40
 *             },
 * //            'etagSeed' => function ($action, $params) {
 * //                return // generate etag seed here
 * //            }
 *         ],
 *     ];
 * }
 * ~~~
41
 *
42 43 44 45 46 47
 * @author Da:Sourcerer <webmaster@dasourcerer.net>
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class HttpCache extends ActionFilter
{
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
    /**
     * @var callable 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]] object that this filter is currently handling;
     * `$params` takes the value of [[params]]. The callback should return a UNIX timestamp.
     */
    public $lastModified;
    /**
     * @var callable a PHP callback that generates the Etag seed string.
     * The callback's signature should be:
     *
     * ~~~
     * function ($action, $params)
     * ~~~
     *
     * where `$action` is the [[Action]] object that this filter is currently handling;
     * `$params` takes the value of [[params]]. The callback should return a string serving
     * as the seed for generating an Etag.
     */
    public $etagSeed;
    /**
     * @var mixed additional parameters that should be passed to the [[lastModified]] and [[etagSeed]] callbacks.
     */
    public $params;
    /**
78
     * @var string the value of the `Cache-Control` HTTP header. If null, the header will not be sent.
79
     */
80 81 82 83 84 85 86 87
    public $cacheControlHeader = 'public, max-age=3600';
    /**
     * @var string the name of the cache limiter to be set when [session_cache_limiter()](http://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()](http://www.php.net/manual/en/function.session-cache-limiter.php)
     * for detailed explanation of these values.
     *
Carsten Brandt committed
88
     * If this property is `null`, then `session_cache_limiter()` will not be called. As a result,
89 90 91 92 93 94 95 96
     * PHP will send headers according to the `session.cache_limiter` PHP ini setting.
     */
    public $sessionCacheLimiter = '';
    /**
     * @var boolean a value indicating whether this filter should be enabled.
     */
    public $enabled = true;

97

98 99 100
    /**
     * 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.
101
     * @param Action $action the action to be executed.
102 103 104 105
     * @return boolean whether the action should continue to be executed.
     */
    public function beforeAction($action)
    {
106 107 108 109
        if (!$this->enabled) {
            return true;
        }

110 111 112 113
        $verb = Yii::$app->getRequest()->getMethod();
        if ($verb !== 'GET' && $verb !== 'HEAD' || $this->lastModified === null && $this->etagSeed === null) {
            return true;
        }
114

115 116 117 118 119 120 121 122
        $lastModified = $etag = null;
        if ($this->lastModified !== null) {
            $lastModified = call_user_func($this->lastModified, $action, $this->params);
        }
        if ($this->etagSeed !== null) {
            $seed = call_user_func($this->etagSeed, $action, $this->params);
            $etag = $this->generateEtag($seed);
        }
123

124
        $this->sendCacheControlHeader();
125

126 127 128 129
        $response = Yii::$app->getResponse();
        if ($etag !== null) {
            $response->getHeaders()->set('Etag', $etag);
        }
130

131 132 133 134
        if ($this->validateCache($lastModified, $etag)) {
            $response->setStatusCode(304);
            return false;
        }
135

136 137 138
        if ($lastModified !== null) {
            $response->getHeaders()->set('Last-Modified', gmdate('D, d M Y H:i:s', $lastModified) . ' GMT');
        }
139

140 141
        return true;
    }
142

143 144
    /**
     * Validates if the HTTP cache contains valid content.
145 146 147
     * @param integer $lastModified the calculated Last-Modified value in terms of a UNIX timestamp.
     * If null, the Last-Modified header will not be validated.
     * @param string $etag the calculated ETag value. If null, the ETag header will not be validated.
148 149 150 151
     * @return boolean whether the HTTP cache is still valid.
     */
    protected function validateCache($lastModified, $etag)
    {
Qiang Xue committed
152 153 154
        if (isset($_SERVER['HTTP_IF_NONE_MATCH'])) {
            // HTTP_IF_NONE_MATCH takes precedence over HTTP_IF_MODIFIED_SINCE
            // http://tools.ietf.org/html/rfc7232#section-3.3
Qiang Xue committed
155
            return $etag !== null && in_array($etag, Yii::$app->request->getEtags(), true);
Qiang Xue committed
156
        } elseif (isset($_SERVER['HTTP_IF_MODIFIED_SINCE'])) {
Qiang Xue committed
157
            return $lastModified !== null && @strtotime($_SERVER['HTTP_IF_MODIFIED_SINCE']) >= $lastModified;
158
        } else {
Qiang Xue committed
159
            return $etag === null && $lastModified === null;
160 161 162 163 164
        }
    }

    /**
     * Sends the cache control header to the client
165
     * @see cacheControlHeader
166 167 168
     */
    protected function sendCacheControlHeader()
    {
169
        if ($this->sessionCacheLimiter !== null) {
170 171 172 173 174 175
            if ($this->sessionCacheLimiter === '' && !headers_sent() && Yii::$app->getSession()->getIsActive()) {
                header_remove('Expires');
                header_remove('Cache-Control');
                header_remove('Last-Modified');
                header_remove('Pragma');
            }
176 177 178
            session_cache_limiter($this->sessionCacheLimiter);
        }

179 180
        $headers = Yii::$app->getResponse()->getHeaders();
        $headers->set('Pragma');
181

182 183 184 185 186 187 188
        if ($this->cacheControlHeader !== null) {
            $headers->set('Cache-Control', $this->cacheControlHeader);
        }
    }

    /**
     * Generates an Etag from the given seed string.
189
     * @param string $seed Seed for the ETag
190 191 192 193 194 195
     * @return string the generated Etag
     */
    protected function generateEtag($seed)
    {
        return '"' . base64_encode(sha1($seed, true)) . '"';
    }
Zander Baldwin committed
196
}