Add $maxAge arg for caching API

See https://github.com/silverstripe/silverstripe-framework/issues/8272

src/Control/Middleware/HTTPCacheControlMiddleware.php

@@ -507,7 +507,8 @@ class HTTPCacheControlMiddleware implements HTTPMiddleware, Resettable
     /**
      * Specifies the maximum amount of time (seconds) a resource will be considered fresh.
      * This directive is relative to the time of the request.
-     * Affects all non-disabled states. Use setStateDirective() instead to set for a single state.
+     * Affects all non-disabled states. Use enableCache(), publicCache() or
+     * setStateDirective() instead to set the max age for a single state.
      *
      * @param int $age
      * @return $this
@@ -560,6 +561,7 @@ class HTTPCacheControlMiddleware implements HTTPMiddleware, Resettable
 
     /**
      * Simple way to set cache control header to a cacheable state.
+     * Needs either `setMaxAge()` or the `$maxAge` method argument in order to activate caching.
      *
      * The resulting cache-control headers will be chosen from the 'enabled' set of directives.
      *
@@ -568,14 +570,20 @@ class HTTPCacheControlMiddleware implements HTTPMiddleware, Resettable
      *
      * @see https://docs.silverstripe.org/en/developer_guides/performance/http_cache_headers/
      * @param bool $force Force the cache to public even if its unforced private or public
+     * @param int $maxAge Shortcut for `setMaxAge()`, which is required to actually enable the cache.
      * @return $this
      */
-    public function enableCache($force = false)
+    public function enableCache($force = false, $maxAge = null)
     {
         // Only execute this if its forcing level is high enough
         if ($this->applyChangeLevel(self::LEVEL_ENABLED, $force)) {
             $this->setState(self::STATE_ENABLED);
         }
+
+        if (!is_null($maxAge)) {
+            $this->setMaxAge($maxAge);
+        }
+
         return $this;
     }
 
@@ -627,20 +635,27 @@ class HTTPCacheControlMiddleware implements HTTPMiddleware, Resettable
 
     /**
      * Advanced way to set cache control header to a cacheable state.
-     * Indicates that the response may be cached by any cache. (eg: CDNs, Proxies, Web browsers)
+     * Indicates that the response may be cached by any cache. (eg: CDNs, Proxies, Web browsers).
+     * Needs either `setMaxAge()` or the `$maxAge` method argument in order to activate caching.
      *
      * The resulting cache-control headers will be chosen from the 'private' set of directives.
      *
      * @see https://docs.silverstripe.org/en/developer_guides/performance/http_cache_headers/
      * @param bool $force Force the cache to public even if it's private, unless it's been forced private
+     * @param int $maxAge Shortcut for `setMaxAge()`, which is required to actually enable the cache.
      * @return $this
      */
-    public function publicCache($force = false)
+    public function publicCache($force = false, $maxAge = null)
     {
         // Only execute this if its forcing level is high enough
         if ($this->applyChangeLevel(self::LEVEL_PUBLIC, $force)) {
             $this->setState(self::STATE_PUBLIC);
         }
+
+        if (!is_null($maxAge)) {
+            $this->setMaxAge($maxAge);
+        }
+
         return $this;
     }
 

tests/php/Control/Middleware/HTTPCacheControlMiddlewareTest.php

@@ -68,6 +68,65 @@ class HTTPCacheControlMiddlewareTest extends SapphireTest
         }
     }
 
+    public function testEnableCacheWithMaxAge()
+    {
+        $maxAge = 300;
+
+        $cc = HTTPCacheControlMiddleware::singleton();
+        $cc->enableCache(false, $maxAge);
+
+        $response = new HTTPResponse();
+        $cc->applyToResponse($response);
+
+        $this->assertContains('max-age=300', $response->getHeader('cache-control'));
+        $this->assertNotContains('no-cache', $response->getHeader('cache-control'));
+        $this->assertNotContains('no-store', $response->getHeader('cache-control'));
+    }
+
+    public function testEnableCacheWithMaxAgeAppliesWhenLevelDoesNot()
+    {
+        $maxAge = 300;
+
+        $cc = HTTPCacheControlMiddleware::singleton();
+        $cc->privateCache(true);
+        $cc->enableCache(false, $maxAge);
+
+        $response = new HTTPResponse();
+        $cc->applyToResponse($response);
+
+        $this->assertContains('max-age=300', $response->getHeader('cache-control'));
+    }
+
+    public function testPublicCacheWithMaxAge()
+    {
+        $maxAge = 300;
+
+        $cc = HTTPCacheControlMiddleware::singleton();
+        $cc->publicCache(false, $maxAge);
+
+        $response = new HTTPResponse();
+        $cc->applyToResponse($response);
+
+        $this->assertContains('max-age=300', $response->getHeader('cache-control'));
+        // STATE_PUBLIC doesn't contain no-cache or no-store headers to begin with,
+        // so can't test their removal effectively
+        $this->assertNotContains('no-cache', $response->getHeader('cache-control'));
+    }
+
+    public function testPublicCacheWithMaxAgeAppliesWhenLevelDoesNot()
+    {
+        $maxAge = 300;
+
+        $cc = HTTPCacheControlMiddleware::singleton();
+        $cc->privateCache(true);
+        $cc->publicCache(false, $maxAge);
+
+        $response = new HTTPResponse();
+        $cc->applyToResponse($response);
+
+        $this->assertContains('max-age=300', $response->getHeader('cache-control'));
+    }
+
     /**
      * @dataProvider provideCacheStates
      */