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.

2 files changed, 32 insertions, 16 deletions

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);
 }
diff --git a/lib/contents.php b/lib/contents.php
index 4740f5c2..c65d6dfb 100644
--- a/lib/contents.php
+++ b/lib/contents.php
@@ -46,11 +46,11 @@ function getContents($url, $header = array(), $opts = array()){
 
 	// Initialize cache
 	$cache = Cache::create(Configuration::getConfig('cache', 'type'));
-	$cache->setPath(PATH_CACHE . 'server/');
+	$cache->setScope('server');
 	$cache->purgeCache(86400); // 24 hours (forced)
 
 	$params = [$url];
-	$cache->setParameters($params);
+	$cache->setKey($params);
 
 	// Use file_get_contents if in CLI mode with no root certificates defined
 	if(php_sapi_name() === 'cli' && empty(ini_get('curl.cainfo'))) {
@@ -271,11 +271,11 @@ function getSimpleHTMLDOMCached($url,
 
 	// Initialize cache
 	$cache = Cache::create(Configuration::getConfig('cache', 'type'));
-	$cache->setPath(PATH_CACHE . 'pages/');
+	$cache->setScope('pages');
 	$cache->purgeCache(86400); // 24 hours (forced)
 
 	$params = [$url];
-	$cache->setParameters($params);
+	$cache->setKey($params);
 
 	// Determine if cached file is within duration
 	$time = $cache->getTime();