#3521: Added `yii\filters\HttpCache::sessionCacheLimiter`

docs/guide/caching-http.md

@@ -116,7 +116,23 @@ the cache if the page content has been modified.
 ## `Cache-Control` Header <a name="cache-control"></a>
 
 The `Cache-Control` header specifies the general caching policy for pages. You may send it by configuring
-the [[yii\filters\HttpCache::cacheControlHeader]] property with the header value.
+the [[yii\filters\HttpCache::cacheControlHeader]] property with the header value. By default, the following
+header will be sent:
+
+```
+Cache-Control: public, max-age=3600
+```
+
+## Session Cache Limiter <a name="session-cache-limiter"></a>
+
+When a page uses session, PHP will automatically send some cache-related HTTP headers as specified in
+the `session.cache_limiter` PHP INI setting. These headers may interfere or disable the caching
+that you want from `HttpCache`. To prevent this problem, by default `HttpCache` will disable sending
+these headers automatically. If you want to change this behavior, you should configure the
+[[yii\filters\HttpCache::sessionCacheLimiter]] property. The property can take a string value, including
+`public`, `private`, `private_no_expire`, and `nocache`. Please refer to the PHP manual about
+[session_cache_limiter()](http://www.php.net/manual/en/function.session-cache-limiter.php)
+for explanations about these values.
 
 
 ## SEO Implications <a name="seo-implications"></a>

framework/CHANGELOG.md

@@ -52,6 +52,7 @@ Yii Framework 2 Change Log
 - Enh #3328: `BaseMailer` generates better text body from html body (armab)
 - Enh #3472: Added configurable option to encode spaces in dropDownLists and listBoxes (kartik-v)
 - Enh #3518: `yii\helpers\Html::encode()` now replaces invalid code sequences with "?" (DaSourcerer)
+- Enh #3521: Added `yii\filters\HttpCache::sessionCacheLimiter` (qiangxue)
 - Enh: Added support for using sub-queries when building a DB query with `IN` condition (qiangxue)
 - Enh: Supported adding a new response formatter without the need to reconfigure existing formatters (qiangxue)
 - Enh: Added `yii\web\UrlManager::addRules()` to simplify adding new URL rules (qiangxue)

framework/filters/HttpCache.php

@@ -75,9 +75,25 @@ class HttpCache extends ActionFilter
      */
     public $params;
     /**
-     * @var string HTTP cache control header. If null, the header will not be sent.
+     * @var string the value of the `Cache-Control` HTTP header. If null, the header will not be sent.
      */
-    public $cacheControlHeader = 'max-age=3600, public';
+    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.
+     *
+     * If this is 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.
+     */
+    public $sessionCacheLimiter = '';
+    /**
+     * @var boolean a value indicating whether this filter should be enabled.
+     */
+    public $enabled = true;
+
 
     /**
      * This method is invoked right before an action is to be executed (after all possible filters.)
@@ -87,6 +103,10 @@ class HttpCache extends ActionFilter
      */
     public function beforeAction($action)
     {
+        if (!$this->enabled) {
+            return true;
+        }
+
         $verb = Yii::$app->getRequest()->getMethod();
         if ($verb !== 'GET' && $verb !== 'HEAD' || $this->lastModified === null && $this->etagSeed === null) {
             return true;
@@ -102,6 +122,7 @@ class HttpCache extends ActionFilter
         }
 
         $this->sendCacheControlHeader();
+
         $response = Yii::$app->getResponse();
         if ($etag !== null) {
             $response->getHeaders()->set('Etag', $etag);
@@ -142,9 +163,13 @@ class HttpCache extends ActionFilter
      */
     protected function sendCacheControlHeader()
     {
-        session_cache_limiter('public');
+        if ($this->sessionCacheLimiter !== null) {
+            session_cache_limiter($this->sessionCacheLimiter);
+        }
+
         $headers = Yii::$app->getResponse()->getHeaders();
         $headers->set('Pragma');
+
         if ($this->cacheControlHeader !== null) {
             $headers->set('Cache-Control', $this->cacheControlHeader);
         }