From 21d3bf3b60bcf0e88165ef79c718b2efb1f5364c Mon Sep 17 00:00:00 2001
From: fulmeek <36341513+fulmeek@users.noreply.github.com>
Date: Mon, 29 Apr 2019 20:12:43 +0200
Subject: caches: Refactor the API (#1060)

- For consistency, functions should always return null on non-existing data.

- WordPressPluginUpdateBridge appears to have used its own cache instance in the past. Obviously not used anymore.

- Since $key can be anything, the cache implementation must ensure to assign the related data reliably; most commonly by serializing and hashing the key in an appropriate way.

- Even though the default path for storage is perfectly fine, some people may want to use a different location. This is an example how a cache implementation is responsible for its requirements.
---
 lib/CacheInterface.php | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)

(limited to 'lib/CacheInterface.php')

diff --git a/lib/CacheInterface.php b/lib/CacheInterface.php
index a74fc0dd..091c5f02 100644
--- a/lib/CacheInterface.php
+++ b/lib/CacheInterface.php
@@ -13,38 +13,54 @@
 
 /**
  * The cache interface
- *
- * @todo Add missing function to the interface
- * @todo Explain parameters and return values in more detail
- * @todo Return self more often (to allow call chaining)
  */
 interface CacheInterface {
+	/**
+	 * Set scope of the current cache
+	 *
+	 * If $scope is an empty string, the cache is set to a global context.
+	 *
+	 * @param string $scope The scope the data is related to
+	 */
+	public function setScope($scope);
+
+	/**
+	 * Set key to assign the current data
+	 *
+	 * Since $key can be anything, the cache implementation must ensure to
+	 * assign the related data reliably; most commonly by serializing and
+	 * hashing the key in an appropriate way.
+	 *
+	 * @param array $key The key the data is related to
+	 */
+	public function setKey($key);
+
 	/**
 	 * Loads data from cache
 	 *
-	 * @return mixed The cache data
+	 * @return mixed The cached data or null
 	 */
 	public function loadData();
 
 	/**
 	 * Stores data to the cache
 	 *
-	 * @param mixed $datas The data to store
+	 * @param mixed $data The data to store
 	 * @return self The cache object
 	 */
-	public function saveData($datas);
+	public function saveData($data);
 
 	/**
-	 * Returns the timestamp for the curent cache file
+	 * Returns the timestamp for the curent cache data
 	 *
-	 * @return int Timestamp
+	 * @return int Timestamp or null
 	 */
 	public function getTime();
 
 	/**
-	 * Removes any data that is older than the specified duration from cache
+	 * Removes any data that is older than the specified age from cache
 	 *
-	 * @param int $duration The cache duration in seconds
+	 * @param int $seconds The cache age in seconds
 	 */
-	public function purgeCache($duration);
+	public function purgeCache($seconds);
 }
-- 
cgit v1.2.3