Add SimpleCacheEngine::add()

I forgot this method last time around. I've also added soft deprecations
for Cache::engine(). Having hard deprecations would require more
refactoring than I want to do right now.

src/Cache/Cache.php

@@ -216,6 +216,8 @@ class Cache
      *
      * @param string $config The configuration name you want an engine for.
      * @return \Cake\Cache\CacheEngine When caching is disabled a null engine will be returned.
+     * @deprecated 3.7.0 Use Cache::pool() instead. In 4.0 all cache engines will implement the
+     *   PSR16 interface and this method does not return objects implementing that interface.
      */
     public static function engine($config)
     {
@@ -253,6 +255,7 @@ class Cache
      * @param string $config [optional] The config name you wish to have garbage collected. Defaults to 'default'
      * @param int|null $expires [optional] An expires timestamp. Defaults to NULL
      * @return void
+     * @deprecated 3.7.0 Will be removed in 4.0
      */
     public static function gc($config = 'default', $expires = null)
     {
@@ -503,7 +506,8 @@ class Cache
     /**
      * Delete all keys from the cache.
      *
-     * @param bool $check if true will check expiration, otherwise delete all
+     * @param bool $check if true will check expiration, otherwise delete all. This parameter
+     *   will become a no-op value in 4.0 as it is deprecated.
      * @param string $config name of the configuration to use. Defaults to 'default'
      * @return bool True if the cache was successfully cleared, false otherwise
      */
@@ -517,7 +521,8 @@ class Cache
     /**
      * Delete all keys from the cache from all configurations.
      *
-     * @param bool $check if true will check expiration, otherwise delete all
+     * @param bool $check if true will check expiration, otherwise delete all. This parameter
+     *   will become a no-op value in 4.0 as it is deprecated.
      * @return array Status code. For each configuration, it reports the status of the operation
      */
     public static function clearAll($check = false)
@@ -674,11 +679,11 @@ class Cache
      */
     public static function add($key, $value, $config = 'default')
     {
-        $engine = static::engine($config);
+        $pool = static::pool($config);
         if (is_resource($value)) {
             return false;
         }
 
-        return $engine->add($key, $value);
+        return $pool->add($key, $value);
     }
 }

src/Cache/CacheEngineInterface.php

@@ -26,6 +26,16 @@ namespace Cake\Cache;
 interface CacheEngineInterface
 {
     /**
+     * Write data for key into a cache engine if it doesn't exist already.
+     *
+     * @param string $key Identifier for the data.
+     * @param mixed $value Data to be cached - anything except a resource.
+     * @return bool True if the data was successfully cached, false on failure.
+     *   Or if the key existed already.
+     */
+    public function add($key, $value);
+
+    /**
      * Increment a number under the key and return incremented value
      *
      * @param string $key Identifier for the data

src/Cache/SimpleCacheEngine.php

@@ -251,6 +251,14 @@ class SimpleCacheEngine implements CacheInterface, CacheEngineInterface
     /**
      * {@inheritDoc}
      */
+    public function add($key, $value)
+    {
+        return $this->innerEngine->add($key, $value);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
     public function increment($key, $offset = 1)
     {
         return $this->innerEngine->increment($key, $offset);

tests/TestCase/Cache/SimpleCacheEngineTest.php

@@ -484,4 +484,21 @@ class SimpleCacheEngineTest extends TestCase
         $cache = new SimpleCacheEngine($mock);
         $this->assertTrue($cache->decrement('key', 2));
     }
+
+    /**
+     * Test pass through on add()
+     *
+     * @return void
+     */
+    public function testAdd()
+    {
+        $mock = $this->createMock(CacheEngine::class);
+        $mock->expects($this->once())
+            ->method('add')
+            ->with('key', 2)
+            ->will($this->returnValue(true));
+
+        $cache = new SimpleCacheEngine($mock);
+        $this->assertTrue($cache->add('key', 2));
+    }
 }