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.

caches/FileCache.php

@@ -3,20 +3,21 @@
 * Cache with file system
 */
 class FileCache implements CacheInterface {
-
 	protected $path;
-	protected $param;
+	protected $key;
 
 	public function loadData(){
 		if(file_exists($this->getCacheFile())) {
 			return unserialize(file_get_contents($this->getCacheFile()));
 		}
+
+		return null;
 	}
 
-	public function saveData($datas){
+	public function saveData($data){
 		// Notice: We use plain serialize() here to reduce memory footprint on
 		// large input data.
-		$writeStream = file_put_contents($this->getCacheFile(), serialize($datas));
+		$writeStream = file_put_contents($this->getCacheFile(), serialize($data));
 
 		if($writeStream === false) {
 			throw new \Exception('Cannot write the cache... Do you have the right permissions ?');
@@ -29,13 +30,14 @@ class FileCache implements CacheInterface {
 		$cacheFile = $this->getCacheFile();
 		clearstatcache(false, $cacheFile);
 		if(file_exists($cacheFile)) {
-			return filemtime($cacheFile);
+			$time = filemtime($cacheFile);
+			return ($time !== false) ? $time : null;
 		}
 
-		return false;
+		return null;
 	}
 
-	public function purgeCache($duration){
+	public function purgeCache($seconds){
 		$cachePath = $this->getPath();
 		if(file_exists($cachePath)) {
 			$cacheIterator = new RecursiveIteratorIterator(
@@ -47,7 +49,7 @@ class FileCache implements CacheInterface {
 				if(in_array($cacheFile->getBasename(), array('.', '..', '.gitkeep')))
 					continue;
 				elseif($cacheFile->isFile()) {
-					if(filemtime($cacheFile->getPathname()) < time() - $duration)
+					if(filemtime($cacheFile->getPathname()) < time() - $seconds)
 						unlink($cacheFile->getPathname());
 				}
 			}
@@ -55,34 +57,34 @@ class FileCache implements CacheInterface {
 	}
 
 	/**
-	* Set cache path
+	* Set scope
 	* @return self
 	*/
-	public function setPath($path){
-		if(is_null($path) || !is_string($path)) {
-			throw new \Exception('The given path is invalid!');
+	public function setScope($scope){
+		if(is_null($scope) || !is_string($scope)) {
+			throw new \Exception('The given scope is invalid!');
 		}
 
-		$this->path = $path;
-
-		// Make sure path ends with '/' or '\'
-		$lastchar = substr($this->path, -1, 1);
-		if($lastchar !== '/' && $lastchar !== '\\')
-			$this->path .= '/';
-
-		if(!is_dir($this->path))
-			mkdir($this->path, 0755, true);
+		$this->path = PATH_CACHE . trim($scope, " \t\n\r\0\x0B\\\/") . '/';
 
 		return $this;
 	}
 
 	/**
-	* Set HTTP GET parameters
+	* Set key
 	* @return self
 	*/
-	public function setParameters(array $param){
-		$this->param = array_map('strtolower', $param);
+	public function setKey($key){
+		if (!empty($key) && is_array($key)) {
+			$key = array_map('strtolower', $key);
+		}
+		$key = json_encode($key);
 
+		if (!is_string($key)) {
+			throw new \Exception('The given key is invalid!');
+		}
+
+		$this->key = $key;
 		return $this;
 	}
 
@@ -90,9 +92,15 @@ class FileCache implements CacheInterface {
 	* Return cache path (and create if not exist)
 	* @return string Cache path
 	*/
-	protected function getPath(){
+	private function getPath(){
 		if(is_null($this->path)) {
-			throw new \Exception('Call "setPath" first!');
+			throw new \Exception('Call "setScope" first!');
+		}
+
+		if(!is_dir($this->path)) {
+			if (mkdir($this->path, 0755, true) !== true) {
+				throw new \Exception('Unable to create ' . $this->path);
+			}
 		}
 
 		return $this->path;
@@ -102,7 +110,7 @@ class FileCache implements CacheInterface {
 	* Get the file name use for cache store
 	* @return string Path to the file cache
 	*/
-	protected function getCacheFile(){
+	private function getCacheFile(){
 		return $this->getPath() . $this->getCacheName();
 	}
 
@@ -110,13 +118,11 @@ class FileCache implements CacheInterface {
 	* Determines file name for store the cache
 	* return string
 	*/
-	protected function getCacheName(){
-		if(is_null($this->param)) {
-			throw new \Exception('Call "setParameters" first!');
+	private function getCacheName(){
+		if(is_null($this->key)) {
+			throw new \Exception('Call "setKey" first!');
 		}
 
-		// Change character when making incompatible changes to prevent loading
-		// errors due to incompatible file contents         \|/
-		return hash('md5', http_build_query($this->param) . 'A') . '.cache';
+		return hash('md5', $this->key) . '.cache';
 	}
 }