Add CacheEngineInterface and SimpleCacheEngine implementation

Add a new interface for cake specific caching operations. This interface
is a sibling to the PSR16 interface and will allow the `Cache` frontend
to typehint adapters for non-standard methods in the frontend and allow
other methods to typehint on the methods they need.

src/Cache/Cache.php

@@ -415,7 +415,7 @@ public static function readMany($keys, $config = 'default')
      */
     public static function increment($key, $offset = 1, $config = 'default')
     {
-        $engine = static::engine($config);
+        $engine = static::pool($config);
         if (!is_int($offset) || $offset < 0) {
             return false;
         }
@@ -434,7 +434,7 @@ public static function increment($key, $offset = 1, $config = 'default')
      */
     public static function decrement($key, $offset = 1, $config = 'default')
     {
-        $engine = static::engine($config);
+        $engine = static::pool($config);
         if (!is_int($offset) || $offset < 0) {
             return false;
         }
@@ -539,7 +539,7 @@ public static function clearAll($check = false)
      */
     public static function clearGroup($group, $config = 'default')
     {
-        $engine = static::engine($config);
+        $engine = static::pool($config);
 
         return $engine->clearGroup($group);
     }

src/Cache/CacheEngineInterface.php

@@ -0,0 +1,57 @@
+<?php
+/**
+ * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
+ * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * For full copyright and license information, please see the LICENSE.txt
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ * @link          https://cakephp.org CakePHP(tm) Project
+ * @since         3.7.0
+ * @license       https://opensource.org/licenses/mit-license.php MIT License
+ */
+namespace Cake\Cache;
+
+/**
+ * Interface for cache engines that defines methods
+ * outside of the PSR16 interface that are used by `Cache`.
+ *
+ * Internally Cache uses this interface when calling engine
+ * methods.
+ *
+ * @since 3.7.0
+ */
+interface CacheEngineInterface
+{
+    /**
+     * Increment a number under the key and return incremented value
+     *
+     * @param string $key Identifier for the data
+     * @param int $offset How much to add
+     * @return bool|int New incremented value, false otherwise
+     */
+    public function increment($key, $offset = 1);
+
+    /**
+     * Decrement a number under the key and return decremented value
+     *
+     * @param string $key Identifier for the data
+     * @param int $offset How much to subtract
+     * @return bool|int New incremented value, false otherwise
+     */
+    public function decrement($key, $offset = 1);
+
+    /**
+     * Clear all values belonging to the named group.
+     *
+     * Each implementation needs to decide whether actually
+     * delete the keys or just augment a group generation value
+     * to achieve the same result.
+     *
+     * @param string $group name of the group to be cleared
+     * @return bool
+     */
+    public function clearGroup($group);
+}

src/Cache/SimpleCacheEngine.php

@@ -15,6 +15,7 @@
 
 namespace Cake\Cache;
 
+use Cake\Cache\CacheEngineInterface;
 use Psr\SimpleCache\CacheInterface;
 
 /**
@@ -24,7 +25,7 @@
  * @since 3.7.0
  * @link https://www.php-fig.org/psr/psr-16/
  */
-class SimpleCacheEngine implements CacheInterface
+class SimpleCacheEngine implements CacheInterface, CacheEngineInterface
 {
     /**
      * The wrapped cache engine object.
@@ -38,7 +39,7 @@ class SimpleCacheEngine implements CacheInterface
      *
      * @param \Cake\Cache\CacheEngine $innerEngine The decorated engine.
      */
-    public function __construct($innerEngine)
+    public function __construct(CacheEngine $innerEngine)
     {
         $this->innerEngine = $innerEngine;
     }
@@ -237,4 +238,28 @@ public function has($key)
     {
         return $this->get($key) !== null;
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function increment($key, $offset = 1)
+    {
+        return $this->innerEngine->increment($key, $offset);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function decrement($key, $offset = 1)
+    {
+        return $this->innerEngine->decrement($key, $offset);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function clearGroup($group)
+    {
+        return $this->innerEngine->clearGroup($group);
+    }
 }

tests/TestCase/Cache/SimpleCacheEngineTest.php

@@ -56,6 +56,7 @@ public function setUp()
             'prefix' => '',
             'path' => TMP . 'tests',
             'duration' => 5,
+            'groups' => ['blog', 'category']
         ]);
         $this->cache = new SimpleCacheEngine($this->innerEngine);
     }
@@ -432,4 +433,53 @@ public function testHasInvalidKey()
         $this->expectExceptionMessage('A cache key must be a non-empty string.');
         $this->cache->has('');
     }
+
+    /**
+     * Test pass through on clearGroup()
+     *
+     * @return void
+     */
+    public function testClearGroup()
+    {
+        $this->cache->set('one', 'val');
+        $this->cache->set('two', 'val 2');
+
+        $this->cache->clearGroup('blog');
+        $this->assertFalse($this->cache->has('one'));
+        $this->assertFalse($this->cache->has('two'));
+    }
+
+    /**
+     * Test pass through on increment()
+     *
+     * @return void
+     */
+    public function testIncrement()
+    {
+        $mock = $this->createMock(CacheEngine::class);
+        $mock->expects($this->once())
+            ->method('increment')
+            ->with('key', 2)
+            ->will($this->returnValue(true));
+
+        $cache = new SimpleCacheEngine($mock);
+        $this->assertTrue($cache->increment('key', 2));
+    }
+
+    /**
+     * Test pass through on decrement()
+     *
+     * @return void
+     */
+    public function testDecrement()
+    {
+        $mock = $this->createMock(CacheEngine::class);
+        $mock->expects($this->once())
+            ->method('decrement')
+            ->with('key', 2)
+            ->will($this->returnValue(true));
+
+        $cache = new SimpleCacheEngine($mock);
+        $this->assertTrue($cache->decrement('key', 2));
+    }
 }