Merge pull request #4629 from MGatner/cache-expires

MGatner · web-flow · commit 0118201fc9c9 · 2021-05-01T13:03:28.000-04:00
Cache getMetadata() Format
diff --git a/system/Cache/CacheInterface.php b/system/Cache/CacheInterface.php
@@ -108,7 +108,10 @@ public function getCacheInfo();
 	 *
 	 * @param string $key Cache item name.
 	 *
-	 * @return mixed
+	 * @return array|false|null
+	 *   Returns null if the item does not exist, otherwise array<string, mixed>
+	 *   with at least the 'expires' key for absolute epoch expiry (or null).
+	 *   Some handlers may return false when an item does not exist, which is deprecated.
 	 */
 	public function getMetaData(string $key);
 
diff --git a/system/Cache/Handlers/FileHandler.php b/system/Cache/Handlers/FileHandler.php
@@ -282,36 +282,47 @@ public function getCacheInfo()
 	 *
 	 * @param string $key Cache item name.
 	 *
-	 * @return mixed
+	 * @return array|false|null
+	 *   Returns null if the item does not exist, otherwise array<string, mixed>
+	 *   with at least the 'expires' key for absolute epoch expiry (or null).
+	 *   Some handlers may return false when an item does not exist, which is deprecated.
 	 */
 	public function getMetaData(string $key)
 	{
 		$key = $this->prefix . $key;
 
 		if (! is_file($this->path . $key))
 		{
-			return false;
+			return false; // This will return null in a future release
 		}
 
 		$data = @unserialize(file_get_contents($this->path . $key));
 
-		if (is_array($data))
+		if (! is_array($data) || ! isset($data['ttl']))
 		{
-			$mtime = filemtime($this->path . $key);
+			return false; // This will return null in a future release
+		}
 
-			if (! isset($data['ttl']))
+		// Consider expired items as missing
+		$expire = $data['time'] + $data['ttl'];
+
+		// @phpstan-ignore-next-line
+		if ($data['ttl'] > 0 && time() > $expire)
+		{
+			// If the file is still there then remove it
+			if (is_file($this->path . $key))
 			{
-				return false;
+				unlink($this->path . $key);
 			}
 
-			return [
-				'expire' => $mtime + $data['ttl'],
-				'mtime'  => $mtime,
-				'data'   => $data['data'],
-			];
+			return false; // This will return null in a future release
 		}
 
-		return false;
+		return [
+			'expire' => $expire,
+			'mtime'  => filemtime($this->path . $key),
+			'data'   => $data['data'],
+		];
 	}
 
 	//--------------------------------------------------------------------
diff --git a/system/Cache/Handlers/MemcachedHandler.php b/system/Cache/Handlers/MemcachedHandler.php
@@ -342,7 +342,10 @@ public function getCacheInfo()
 	 *
 	 * @param string $key Cache item name.
 	 *
-	 * @return mixed
+	 * @return array|false|null
+	 *   Returns null if the item does not exist, otherwise array<string, mixed>
+	 *   with at least the 'expires' key for absolute epoch expiry (or null).
+	 *   Some handlers may return false when an item does not exist, which is deprecated.
 	 */
 	public function getMetaData(string $key)
 	{
@@ -353,13 +356,16 @@ public function getMetaData(string $key)
 		// if not an array, don't try to count for PHP7.2
 		if (! is_array($stored) || count($stored) !== 3)
 		{
-			return false;
+			return false; // This will return null in a future release
 		}
 
-		list($data, $time, $ttl) = $stored;
+		list($data, $time, $limit) = $stored;
+
+		// Calculate the remaining time to live from the original limit
+		$ttl = time() - $time - $limit;
 
 		return [
-			'expire' => $time + $ttl,
+			'expire' => $limit > 0 ? $time + $limit : null,
 			'mtime'  => $time,
 			'data'   => $data,
 		];
diff --git a/system/Cache/Handlers/PredisHandler.php b/system/Cache/Handlers/PredisHandler.php
@@ -269,7 +269,9 @@ public function getCacheInfo()
 	 *
 	 * @param string $key Cache item name.
 	 *
-	 * @return mixed
+	 * @return array|false|null
+	 *   Returns null if the item does not exist, otherwise array<string, mixed>
+	 *   with at least the 'expires' key for absolute epoch expiry (or null).
 	 */
 	public function getMetaData(string $key)
 	{
@@ -278,8 +280,10 @@ public function getMetaData(string $key)
 		if (isset($data['__ci_value']) && $data['__ci_value'] !== false)
 		{
 			$time = time();
+			$ttl  = $this->redis->ttl($key);
+
 			return [
-				'expire' => $time + $this->redis->ttl($key),
+				'expire' => $ttl > 0 ? time() + $ttl : null,
 				'mtime'  => $time,
 				'data'   => $data['__ci_value'],
 			];
diff --git a/system/Cache/Handlers/RedisHandler.php b/system/Cache/Handlers/RedisHandler.php
@@ -322,7 +322,9 @@ public function getCacheInfo()
 	 *
 	 * @param string $key Cache item name.
 	 *
-	 * @return mixed
+	 * @return array|null
+	 *   Returns null if the item does not exist, otherwise array<string, mixed>
+	 *   with at least the 'expires' key for absolute epoch expiry (or null).
 	 */
 	public function getMetaData(string $key)
 	{
@@ -333,8 +335,10 @@ public function getMetaData(string $key)
 		if ($value !== null)
 		{
 			$time = time();
+			$ttl  = $this->redis->ttl($key);
+
 			return [
-				'expire' => $time + $this->redis->ttl($key),
+				'expire' => $ttl > 0 ? time() + $ttl : null,
 				'mtime'  => $time,
 				'data'   => $value,
 			];
diff --git a/system/Cache/Handlers/WincacheHandler.php b/system/Cache/Handlers/WincacheHandler.php
@@ -71,7 +71,7 @@ public function get(string $key)
 		$data    = wincache_ucache_get($key, $success);
 
 		// Success returned by reference from wincache_ucache_get()
-		return ($success) ? $data : null;
+		return $success ? $data : null;
 	}
 
 	//--------------------------------------------------------------------
@@ -147,7 +147,7 @@ public function increment(string $key, int $offset = 1)
 		$success = false;
 		$value   = wincache_ucache_inc($key, $offset, $success);
 
-		return ($success === true) ? $value : false; // @phpstan-ignore-line
+		return $success ? $value : false; // @phpstan-ignore-line
 	}
 
 	//--------------------------------------------------------------------
@@ -169,7 +169,7 @@ public function decrement(string $key, int $offset = 1)
 		$success = false;
 		$value   = wincache_ucache_dec($key, $offset, $success);
 
-		return ($success === true) ? $value : false; // @phpstan-ignore-line
+		return $success ? $value : false; // @phpstan-ignore-line
 	}
 
 	//--------------------------------------------------------------------
@@ -210,7 +210,10 @@ public function getCacheInfo()
 	 *
 	 * @param string $key Cache item name.
 	 *
-	 * @return mixed
+	 * @return array|false|null
+	 *   Returns null if the item does not exist, otherwise array<string, mixed>
+	 *   with at least the 'expires' key for absolute epoch expiry (or null).
+	 *   Some handlers may return false when an item does not exist, which is deprecated.
 	 *
 	 * @codeCoverageIgnore
 	 */
@@ -225,14 +228,14 @@ public function getMetaData(string $key)
 			$hitcount = $stored['ucache_entries'][1]['hitcount'];
 
 			return [
-				'expire'   => $ttl - $age,
+				'expire'   => $ttl > 0 ? time() + $ttl : null,
 				'hitcount' => $hitcount,
 				'age'      => $age,
 				'ttl'      => $ttl,
 			];
 		}
 
-		return false;
+		return false; // This will return null in a future release
 	}
 
 	//--------------------------------------------------------------------
diff --git a/user_guide_src/source/changelogs/v4.1.2.rst b/user_guide_src/source/changelogs/v4.1.2.rst
@@ -26,6 +26,7 @@ Changes:
 - ``Entity::mutateDate`` uses external cast handler ``DatetimeCast::get``.
 - In order for ``Config\**`` classes to get their respective properties' values from the ``.env``, it is now necessary to namespace the property with the name of the class. Previously, the property names are enough but now disallowed because it can get system environment variables, like ``PATH``.
 - The array helper ``_array_search_dot`` is now marked for ``@internal`` use. As this is used by ``dot_array_search``, users should not use ``_array_search_dot`` directly in their code.
+- ``CacheInterface::getMetaData()`` returns ``null`` for misses, or an array with at least the "expires" key set to the absolute epoch expiration, or ``null`` for "never expires". The File, Memcached, and Wincache Handlers still return ``false`` which will become ``null`` in a future release.
 
 Deprecations:
 
diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst
@@ -215,8 +215,8 @@ Class Reference
 .. php:method:: getMetadata(string $key)
 
     :param string $key: Cache item name
-    :returns: Metadata for the cached item
-    :rtype: mixed
+    :returns: Metadata for the cached item. ``null`` for missing items, or an array with at least the "expire" key for absolute epoch expiry (``null`` for never expires).
+    :rtype: array|null
 
     This method will return detailed information on a specific item in the
     cache.
@@ -226,7 +226,8 @@ Class Reference
         var_dump($cache->getMetadata('my_cached_item'));
 
 .. note:: The information returned and the structure of the data is dependent
-          on which adapter is being used.
+          on which adapter is being used. Some adapters (File, Memcached, Wincache)
+          still return ``false`` for missing items.
 
 *******
 Drivers

Original file line number	Diff line number	Diff line change
`@@ -108,7 +108,10 @@ public function getCacheInfo();`
`108`	`108`	`*`
`109`	`109`	`* @param string $key Cache item name.`
`110`	`110`	`*`
`111`		`- * @return mixed`
	`111`	`+ * @return array\|false\|null`
	`112`	`+ * Returns null if the item does not exist, otherwise array<string, mixed>`
	`113`	`+ * with at least the 'expires' key for absolute epoch expiry (or null).`
	`114`	`+ * Some handlers may return false when an item does not exist, which is deprecated.`
`112`	`115`	`*/`
`113`	`116`	`public function getMetaData(string $key);`
`114`	`117`
Original file line number	Diff line number	Diff line change
`@@ -282,36 +282,47 @@ public function getCacheInfo()`
`282`	`282`	`*`
`283`	`283`	`* @param string $key Cache item name.`
`284`	`284`	`*`
`285`		`- * @return mixed`
	`285`	`+ * @return array\|false\|null`
	`286`	`+ * Returns null if the item does not exist, otherwise array<string, mixed>`
	`287`	`+ * with at least the 'expires' key for absolute epoch expiry (or null).`
	`288`	`+ * Some handlers may return false when an item does not exist, which is deprecated.`
`286`	`289`	`*/`
`287`	`290`	`public function getMetaData(string $key)`
`288`	`291`	`{`
`289`	`292`	`$key = $this->prefix . $key;`
`290`	`293`
`291`	`294`	`if (! is_file($this->path . $key))`
`292`	`295`	`{`
`293`		`- return false;`
	`296`	`+ return false; // This will return null in a future release`
`294`	`297`	`}`
`295`	`298`
`296`	`299`	`$data = @unserialize(file_get_contents($this->path . $key));`
`297`	`300`
`298`		`- if (is_array($data))`
	`301`	`+ if (! is_array($data) \|\| ! isset($data['ttl']))`
`299`	`302`	`{`
`300`		`- $mtime = filemtime($this->path . $key);`
	`303`	`+ return false; // This will return null in a future release`
	`304`	`+ }`
`301`	`305`
`302`		`- if (! isset($data['ttl']))`
	`306`	`+ // Consider expired items as missing`
	`307`	`+ $expire = $data['time'] + $data['ttl'];`
	`308`	`+`
	`309`	`+ // @phpstan-ignore-next-line`
	`310`	`+ if ($data['ttl'] > 0 && time() > $expire)`
	`311`	`+ {`
	`312`	`+ // If the file is still there then remove it`
	`313`	`+ if (is_file($this->path . $key))`
`303`	`314`	`{`
`304`		`- return false;`
	`315`	`+ unlink($this->path . $key);`
`305`	`316`	`}`
`306`	`317`
`307`		`- return [`
`308`		`- 'expire' => $mtime + $data['ttl'],`
`309`		`- 'mtime' => $mtime,`
`310`		`- 'data' => $data['data'],`
`311`		`- ];`
	`318`	`+ return false; // This will return null in a future release`
`312`	`319`	`}`
`313`	`320`
`314`		`- return false;`
	`321`	`+ return [`
	`322`	`+ 'expire' => $expire,`
	`323`	`+ 'mtime' => filemtime($this->path . $key),`
	`324`	`+ 'data' => $data['data'],`
	`325`	`+ ];`
`315`	`326`	`}`
`316`	`327`
`317`	`328`	`//--------------------------------------------------------------------`
Original file line number	Diff line number	Diff line change
`@@ -342,7 +342,10 @@ public function getCacheInfo()`
`342`	`342`	`*`
`343`	`343`	`* @param string $key Cache item name.`
`344`	`344`	`*`
`345`		`- * @return mixed`
	`345`	`+ * @return array\|false\|null`
	`346`	`+ * Returns null if the item does not exist, otherwise array<string, mixed>`
	`347`	`+ * with at least the 'expires' key for absolute epoch expiry (or null).`
	`348`	`+ * Some handlers may return false when an item does not exist, which is deprecated.`
`346`	`349`	`*/`
`347`	`350`	`public function getMetaData(string $key)`
`348`	`351`	`{`
`@@ -353,13 +356,16 @@ public function getMetaData(string $key)`
`353`	`356`	`// if not an array, don't try to count for PHP7.2`
`354`	`357`	`if (! is_array($stored) \|\| count($stored) !== 3)`
`355`	`358`	`{`
`356`		`- return false;`
	`359`	`+ return false; // This will return null in a future release`
`357`	`360`	`}`
`358`	`361`
`359`		`- list($data, $time, $ttl) = $stored;`
	`362`	`+ list($data, $time, $limit) = $stored;`
	`363`	`+`
	`364`	`+ // Calculate the remaining time to live from the original limit`
	`365`	`+ $ttl = time() - $time - $limit;`
`360`	`366`
`361`	`367`	`return [`
`362`		`- 'expire' => $time + $ttl,`
	`368`	`+ 'expire' => $limit > 0 ? $time + $limit : null,`
`363`	`369`	`'mtime' => $time,`
`364`	`370`	`'data' => $data,`
`365`	`371`	`];`
Original file line number	Diff line number	Diff line change
`@@ -269,7 +269,9 @@ public function getCacheInfo()`
`269`	`269`	`*`
`270`	`270`	`* @param string $key Cache item name.`
`271`	`271`	`*`
`272`		`- * @return mixed`
	`272`	`+ * @return array\|false\|null`
	`273`	`+ * Returns null if the item does not exist, otherwise array<string, mixed>`
	`274`	`+ * with at least the 'expires' key for absolute epoch expiry (or null).`
`273`	`275`	`*/`
`274`	`276`	`public function getMetaData(string $key)`
`275`	`277`	`{`
`@@ -278,8 +280,10 @@ public function getMetaData(string $key)`
`278`	`280`	`if (isset($data['__ci_value']) && $data['__ci_value'] !== false)`
`279`	`281`	`{`
`280`	`282`	`$time = time();`
	`283`	`+ $ttl = $this->redis->ttl($key);`
	`284`	`+`
`281`	`285`	`return [`
`282`		`- 'expire' => $time + $this->redis->ttl($key),`
	`286`	`+ 'expire' => $ttl > 0 ? time() + $ttl : null,`
`283`	`287`	`'mtime' => $time,`
`284`	`288`	`'data' => $data['__ci_value'],`
`285`	`289`	`];`
Original file line number	Diff line number	Diff line change
`@@ -322,7 +322,9 @@ public function getCacheInfo()`
`322`	`322`	`*`
`323`	`323`	`* @param string $key Cache item name.`
`324`	`324`	`*`
`325`		`- * @return mixed`
	`325`	`+ * @return array\|null`
	`326`	`+ * Returns null if the item does not exist, otherwise array<string, mixed>`
	`327`	`+ * with at least the 'expires' key for absolute epoch expiry (or null).`
`326`	`328`	`*/`
`327`	`329`	`public function getMetaData(string $key)`
`328`	`330`	`{`
`@@ -333,8 +335,10 @@ public function getMetaData(string $key)`
`333`	`335`	`if ($value !== null)`
`334`	`336`	`{`
`335`	`337`	`$time = time();`
	`338`	`+ $ttl = $this->redis->ttl($key);`
	`339`	`+`
`336`	`340`	`return [`
`337`		`- 'expire' => $time + $this->redis->ttl($key),`
	`341`	`+ 'expire' => $ttl > 0 ? time() + $ttl : null,`
`338`	`342`	`'mtime' => $time,`
`339`	`343`	`'data' => $value,`
`340`	`344`	`];`
Original file line number	Diff line number	Diff line change
`@@ -71,7 +71,7 @@ public function get(string $key)`
`71`	`71`	`$data = wincache_ucache_get($key, $success);`
`72`	`72`
`73`	`73`	`// Success returned by reference from wincache_ucache_get()`
`74`		`- return ($success) ? $data : null;`
	`74`	`+ return $success ? $data : null;`
`75`	`75`	`}`
`76`	`76`
`77`	`77`	`//--------------------------------------------------------------------`
`@@ -147,7 +147,7 @@ public function increment(string $key, int $offset = 1)`
`147`	`147`	`$success = false;`
`148`	`148`	`$value = wincache_ucache_inc($key, $offset, $success);`
`149`	`149`
`150`		`- return ($success === true) ? $value : false; // @phpstan-ignore-line`
	`150`	`+ return $success ? $value : false; // @phpstan-ignore-line`
`151`	`151`	`}`
`152`	`152`
`153`	`153`	`//--------------------------------------------------------------------`
`@@ -169,7 +169,7 @@ public function decrement(string $key, int $offset = 1)`
`169`	`169`	`$success = false;`
`170`	`170`	`$value = wincache_ucache_dec($key, $offset, $success);`
`171`	`171`
`172`		`- return ($success === true) ? $value : false; // @phpstan-ignore-line`
	`172`	`+ return $success ? $value : false; // @phpstan-ignore-line`
`173`	`173`	`}`
`174`	`174`
`175`	`175`	`//--------------------------------------------------------------------`
`@@ -210,7 +210,10 @@ public function getCacheInfo()`
`210`	`210`	`*`
`211`	`211`	`* @param string $key Cache item name.`
`212`	`212`	`*`
`213`		`- * @return mixed`
	`213`	`+ * @return array\|false\|null`
	`214`	`+ * Returns null if the item does not exist, otherwise array<string, mixed>`
	`215`	`+ * with at least the 'expires' key for absolute epoch expiry (or null).`
	`216`	`+ * Some handlers may return false when an item does not exist, which is deprecated.`
`214`	`217`	`*`
`215`	`218`	`* @codeCoverageIgnore`
`216`	`219`	`*/`
`@@ -225,14 +228,14 @@ public function getMetaData(string $key)`
`225`	`228`	`$hitcount = $stored['ucache_entries'][1]['hitcount'];`
`226`	`229`
`227`	`230`	`return [`
`228`		`- 'expire' => $ttl - $age,`
	`231`	`+ 'expire' => $ttl > 0 ? time() + $ttl : null,`
`229`	`232`	`'hitcount' => $hitcount,`
`230`	`233`	`'age' => $age,`
`231`	`234`	`'ttl' => $ttl,`
`232`	`235`	`];`
`233`	`236`	`}`
`234`	`237`
`235`		`- return false;`
	`238`	`+ return false; // This will return null in a future release`
`236`	`239`	`}`
`237`	`240`
`238`	`241`	`//--------------------------------------------------------------------`