From 83cb41e72a7352e22e2d00b6f3f99332000643e7 Mon Sep 17 00:00:00 2001
From: Marc Alexander <admin@m-a-styles.de>
Date: Tue, 27 Dec 2022 16:12:53 +0100
Subject: [PATCH] [ticket/16955] Add stubs for cache classes and clean up

PHPBB3-16955
---
 build/psalm/stubs/apcu/apcu.php               | 24 +++++++++++++++
 build/psalm/stubs/memcached/memcached.php     | 20 +++++++++++++
 build/psalm/stubs/redis/redis.php             | 21 +++++++++++++
 build/psalm/stubs/sqlite3/sqlite3.php         |  1 +
 phpBB/phpbb/cache/driver/apcu.php             | 28 +++++------------
 phpBB/phpbb/cache/driver/base.php             | 11 ++++++-
 phpBB/phpbb/cache/driver/driver_interface.php |  2 +-
 phpBB/phpbb/cache/driver/dummy.php            |  8 +++++
 phpBB/phpbb/cache/driver/file.php             | 12 +++-----
 phpBB/phpbb/cache/driver/memcached.php        | 28 +++++------------
 phpBB/phpbb/cache/driver/memory.php           | 24 +++++++++++++--
 phpBB/phpbb/cache/driver/redis.php            | 30 +++++--------------
 phpBB/phpbb/cache/driver/wincache.php         | 30 +++++--------------
 psalm.xml                                     |  3 ++
 tests/cache/cache_memory.php                  | 30 +++++--------------
 15 files changed, 153 insertions(+), 119 deletions(-)
 create mode 100644 build/psalm/stubs/apcu/apcu.php
 create mode 100644 build/psalm/stubs/memcached/memcached.php
 create mode 100644 build/psalm/stubs/redis/redis.php

diff --git a/build/psalm/stubs/apcu/apcu.php b/build/psalm/stubs/apcu/apcu.php
new file mode 100644
index 0000000000..55d1463e4d
--- /dev/null
+++ b/build/psalm/stubs/apcu/apcu.php
@@ -0,0 +1,24 @@
+<?php
+
+class APCUIterator implements Iterator
+{
+	public function current()
+	{
+	}
+
+	public function next()
+	{
+	}
+
+	public function key()
+	{
+	}
+
+	public function valid()
+	{
+	}
+
+	public function rewind()
+	{
+	}
+}
diff --git a/build/psalm/stubs/memcached/memcached.php b/build/psalm/stubs/memcached/memcached.php
new file mode 100644
index 0000000000..9283d877f8
--- /dev/null
+++ b/build/psalm/stubs/memcached/memcached.php
@@ -0,0 +1,20 @@
+<?php
+/**
+ *
+ * This file is part of the phpBB Forum Software package.
+ *
+ * @copyright (c) phpBB Limited <https://www.phpbb.com>
+ * @license GNU General Public License, version 2 (GPL-2.0)
+ *
+ * For full copyright and license information, please see
+ * the docs/CREDITS.txt file.
+ *
+ */
+
+/** @link https://www.php.net/manual/en/memcached.constants.php */
+class Memcached
+{
+	public const OPT_COMPRESSION = -1001;
+
+	public const OPT_BINARY_PROTOCOL = 18;
+}
diff --git a/build/psalm/stubs/redis/redis.php b/build/psalm/stubs/redis/redis.php
new file mode 100644
index 0000000000..b18c224bd0
--- /dev/null
+++ b/build/psalm/stubs/redis/redis.php
@@ -0,0 +1,21 @@
+<?php
+/**
+ *
+ * This file is part of the phpBB Forum Software package.
+ *
+ * @copyright (c) phpBB Limited <https://www.phpbb.com>
+ * @license GNU General Public License, version 2 (GPL-2.0)
+ *
+ * For full copyright and license information, please see
+ * the docs/CREDITS.txt file.
+ *
+ */
+
+/** @link https://phpredis.github.io/phpredis/Redis.html */
+class Redis
+{
+	public const OPT_PREFIX = 2;
+
+	public const SERIALIZER_PHP = 1;
+
+}
diff --git a/build/psalm/stubs/sqlite3/sqlite3.php b/build/psalm/stubs/sqlite3/sqlite3.php
index a102b39fca..5646c6623e 100644
--- a/build/psalm/stubs/sqlite3/sqlite3.php
+++ b/build/psalm/stubs/sqlite3/sqlite3.php
@@ -10,6 +10,7 @@
  * the docs/CREDITS.txt file.
  *
  */
+
 class SQLite3
 {
 	public function query(string $query) {}
diff --git a/phpBB/phpbb/cache/driver/apcu.php b/phpBB/phpbb/cache/driver/apcu.php
index 6bcc13cf78..0160ef7eb9 100644
--- a/phpBB/phpbb/cache/driver/apcu.php
+++ b/phpBB/phpbb/cache/driver/apcu.php
@@ -38,39 +38,25 @@ class apcu extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Fetch an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return mixed Cached data
+	* {@inheritDoc}
 	*/
-	function _read($var)
+	protected function _read(string $var)
 	{
 		return apcu_fetch($this->key_prefix . $var);
 	}
 
 	/**
-	* Store data in the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @param mixed $data Data to store
-	* @param int $ttl Time-to-live of cached data
-	* @return bool True if the operation succeeded
+	* {@inheritDoc}
 	*/
-	function _write($var, $data, $ttl = 2592000)
+	protected function _write(string $var, $data, int $ttl = 2592000): bool
 	{
 		return apcu_store($this->key_prefix . $var, $data, $ttl);
 	}
 
 	/**
-	* Remove an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return bool True if the operation succeeded
-	*/
-	function _delete($var)
+	 * {@inheritDoc}
+	 */
+	protected function _delete(string $var): bool
 	{
 		return apcu_delete($this->key_prefix . $var);
 	}
diff --git a/phpBB/phpbb/cache/driver/base.php b/phpBB/phpbb/cache/driver/base.php
index 3eca521148..29352e84b3 100644
--- a/phpBB/phpbb/cache/driver/base.php
+++ b/phpBB/phpbb/cache/driver/base.php
@@ -199,7 +199,7 @@ abstract class base implements \phpbb\cache\driver\driver_interface
 	*
 	* @param string $dir Directory to remove
 	*
-	* @return null
+	* @return void
 	*/
 	protected function remove_dir($dir)
 	{
@@ -231,4 +231,13 @@ abstract class base implements \phpbb\cache\driver\driver_interface
 
 		@rmdir($dir);
 	}
+
+	/**
+	 * Fetch an item from the cache
+	 *
+	 * @param string $var Cache key
+	 *
+	 * @return mixed Cached data
+	 */
+	abstract protected function _read(string $var);
 }
diff --git a/phpBB/phpbb/cache/driver/driver_interface.php b/phpBB/phpbb/cache/driver/driver_interface.php
index 9ac9ca0c59..61ce39d496 100644
--- a/phpBB/phpbb/cache/driver/driver_interface.php
+++ b/phpBB/phpbb/cache/driver/driver_interface.php
@@ -95,7 +95,7 @@ interface driver_interface
 	*
 	* @param string $query			SQL query
 	*
-	* @return int|bool				Query ID (integer) if cache contains a rowset
+	* @return string|false			Query ID (md5 of query) if cache contains a rowset
 	*								for the specified query.
 	*								False otherwise.
 	*/
diff --git a/phpBB/phpbb/cache/driver/dummy.php b/phpBB/phpbb/cache/driver/dummy.php
index 1f74f6dd77..df5896d4e9 100644
--- a/phpBB/phpbb/cache/driver/dummy.php
+++ b/phpBB/phpbb/cache/driver/dummy.php
@@ -95,6 +95,14 @@ class dummy extends \phpbb\cache\driver\base
 		return false;
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
+	protected function _read(string $var)
+	{
+		return false;
+	}
+
 	/**
 	* {@inheritDoc}
 	*/
diff --git a/phpBB/phpbb/cache/driver/file.php b/phpBB/phpbb/cache/driver/file.php
index 36150d0589..2dc9f350c2 100644
--- a/phpBB/phpbb/cache/driver/file.php
+++ b/phpBB/phpbb/cache/driver/file.php
@@ -331,17 +331,13 @@ class file extends \phpbb\cache\driver\base
 	}
 
 	/**
-	* Read cached data from a specified file
-	*
-	* @access private
-	* @param string $filename Filename to write
-	* @return mixed False if an error was encountered, otherwise the data type of the cached data
-	*/
-	function _read($filename)
+	 * {@inheritDoc}
+	 */
+	protected function _read(string $var)
 	{
 		global $phpEx;
 
-		$filename = $this->clean_varname($filename);
+		$filename = $this->clean_varname($var);
 		$file = "{$this->cache_dir}$filename.$phpEx";
 
 		$type = substr($filename, 0, strpos($filename, '_'));
diff --git a/phpBB/phpbb/cache/driver/memcached.php b/phpBB/phpbb/cache/driver/memcached.php
index fbb587a369..ca4922b73f 100644
--- a/phpBB/phpbb/cache/driver/memcached.php
+++ b/phpBB/phpbb/cache/driver/memcached.php
@@ -37,7 +37,7 @@ if (!defined('PHPBB_ACM_MEMCACHED'))
 /**
 * ACM for Memcached
 */
-class memcached extends \phpbb\cache\driver\memory
+class memcached extends memory
 {
 	/** @var string Extension to use */
 	protected $extension = 'memcached';
@@ -107,26 +107,17 @@ class memcached extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Fetch an item from the cache
-	*
-	* @param string $var Cache key
-	*
-	* @return mixed Cached data
-	*/
-	protected function _read($var)
+	 * {@inheritDoc}
+	 */
+	protected function _read(string $var)
 	{
 		return $this->memcached->get($this->key_prefix . $var);
 	}
 
 	/**
-	* Store data in the cache
-	*
-	* @param string $var Cache key
-	* @param mixed $data Data to store
-	* @param int $ttl Time-to-live of cached data
-	* @return bool True if the operation succeeded
+	* {@inheritDoc}
 	*/
-	protected function _write($var, $data, $ttl = 2592000)
+	protected function _write(string $var, $data, int $ttl = 2592000): bool
 	{
 		if (!$this->memcached->replace($this->key_prefix . $var, $data, $ttl))
 		{
@@ -136,12 +127,9 @@ class memcached extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Remove an item from the cache
-	*
-	* @param string $var Cache key
-	* @return bool True if the operation succeeded
+	* {@inheritDoc}
 	*/
-	protected function _delete($var)
+	protected function _delete(string $var): bool
 	{
 		return $this->memcached->delete($this->key_prefix . $var);
 	}
diff --git a/phpBB/phpbb/cache/driver/memory.php b/phpBB/phpbb/cache/driver/memory.php
index 956936bf6f..0a4ea304ad 100644
--- a/phpBB/phpbb/cache/driver/memory.php
+++ b/phpBB/phpbb/cache/driver/memory.php
@@ -270,13 +270,33 @@ abstract class memory extends \phpbb\cache\driver\base
 	/**
 	* Check if a cache var exists
 	*
-	* @access protected
 	* @param string $var Cache key
+	*
 	* @return bool True if it exists, otherwise false
 	*/
-	function _isset($var)
+	protected function _isset(string $var): bool
 	{
 		// Most caches don't need to check
 		return true;
 	}
+
+	/**
+	 * Remove an item from the cache
+	 *
+	 * @param string $var Cache key
+	 *
+	 * @return bool True if the operation succeeded
+	 */
+	abstract protected function _delete(string $var): bool;
+
+	/**
+	 * Store data in the cache
+	 *
+	 * @param string $var Cache key
+	 * @param mixed $data Data to store
+	 * @param int $ttl Time-to-live of cached data
+	 *
+	 * @return bool True if the operation succeeded
+	 */
+	abstract protected function _write(string $var, $data, int $ttl = 2592000): bool;
 }
diff --git a/phpBB/phpbb/cache/driver/redis.php b/phpBB/phpbb/cache/driver/redis.php
index eaeb529918..c0b47dae46 100644
--- a/phpBB/phpbb/cache/driver/redis.php
+++ b/phpBB/phpbb/cache/driver/redis.php
@@ -115,27 +115,17 @@ class redis extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Fetch an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return mixed Cached data
-	*/
-	function _read($var)
+	 * {@inheritDoc}
+	 */
+	protected function _read(string $var)
 	{
 		return $this->redis->get($var);
 	}
 
 	/**
-	* Store data in the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @param mixed $data Data to store
-	* @param int $ttl Time-to-live of cached data
-	* @return bool True if the operation succeeded
+	* {@inheritDoc}
 	*/
-	function _write($var, $data, $ttl = 2592000)
+	protected function _write(string $var, $data, int $ttl = 2592000): bool
 	{
 		if ($ttl == 0)
 		{
@@ -145,13 +135,9 @@ class redis extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Remove an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return bool True if the operation succeeded
-	*/
-	function _delete($var)
+	 * {@inheritDoc}
+	 */
+	protected function _delete(string $var): bool
 	{
 		if ($this->redis->delete($var) > 0)
 		{
diff --git a/phpBB/phpbb/cache/driver/wincache.php b/phpBB/phpbb/cache/driver/wincache.php
index 632b534362..367de2478b 100644
--- a/phpBB/phpbb/cache/driver/wincache.php
+++ b/phpBB/phpbb/cache/driver/wincache.php
@@ -31,13 +31,9 @@ class wincache extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Fetch an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return mixed Cached data
-	*/
-	function _read($var)
+	 * {@inheritDoc}
+	 */
+	protected function _read(string $var)
 	{
 		$success = false;
 		$result = wincache_ucache_get($this->key_prefix . $var, $success);
@@ -46,27 +42,17 @@ class wincache extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Store data in the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @param mixed $data Data to store
-	* @param int $ttl Time-to-live of cached data
-	* @return bool True if the operation succeeded
+	* {@inheritDoc}
 	*/
-	function _write($var, $data, $ttl = 2592000)
+	protected function _write(string $var, $data, int $ttl = 2592000): bool
 	{
 		return wincache_ucache_set($this->key_prefix . $var, $data, $ttl);
 	}
 
 	/**
-	* Remove an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return bool True if the operation succeeded
-	*/
-	function _delete($var)
+	 * {@inheritDoc}
+	 */
+	protected function _delete(string $var): bool
 	{
 		return wincache_ucache_delete($this->key_prefix . $var);
 	}
diff --git a/psalm.xml b/psalm.xml
index 0fbf33cdef..cb434cfaf8 100644
--- a/psalm.xml
+++ b/psalm.xml
@@ -22,8 +22,11 @@
     </issueHandlers>
 
     <stubs>
+        <file name="build/psalm/stubs/apcu/apcu.php"/>
+        <file name="build/psalm/stubs/memcached/memcached.php"/>
         <file name="build/psalm/stubs/oci8/oci8.php"/>
         <file name="build/psalm/stubs/pgsql/pgsql.php"/>
+        <file name="build/psalm/stubs/redis/redis.php"/>
         <file name="build/psalm/stubs/sqlite3/sqlite3.php"/>
     </stubs>
 </psalm>
diff --git a/tests/cache/cache_memory.php b/tests/cache/cache_memory.php
index 1f7b31a86b..9d94c080f2 100644
--- a/tests/cache/cache_memory.php
+++ b/tests/cache/cache_memory.php
@@ -23,40 +23,26 @@ class phpbb_cache_memory extends \phpbb\cache\driver\memory
 	}
 
 	/**
-	* Fetch an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return mixed Cached data
-	*/
-	function _read($var)
+	 * {@inheritDoc}
+	 */
+	protected function _read(string $var)
 	{
 		return $this->data[$var] ?? false;
 	}
 
 	/**
-	* Store data in the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @param mixed $data Data to store
-	* @param int $ttl Time-to-live of cached data
-	* @return bool True if the operation succeeded
+	* {@inheritDoc}
 	*/
-	function _write($var, $data, $ttl = 2592000)
+	protected function _write(string $var, $data, int $ttl = 2592000): bool
 	{
 		$this->data[$var] = $data;
 		return true;
 	}
 
 	/**
-	* Remove an item from the cache
-	*
-	* @access protected
-	* @param string $var Cache key
-	* @return bool True if the operation succeeded
-	*/
-	function _delete($var)
+	 * {@inheritDoc}
+	 */
+	protected function _delete(string $var): bool
 	{
 		unset($this->data[$var]);
 		return true;