Cache.php deprecations & v3 migration guide update

docs/book/v2/migration/preparing-for-v3.md

@@ -3,6 +3,29 @@
 Version 3 will introduce a number of backwards incompatible changes.
 This document is intended to help you prepare for these changes.
 
+## Upcoming Behaviour and Signature Changes
+
+### `laminas/laminas-cache` Replacement
+
+From version 3.0 onwards, `laminas-session` will remove the `laminas/laminas-cache`
+dependency and replace it with `psr/simple-cache` to adhere to PSR-16.
+
+The `Laminas\Session\SaveHandler\Cache.php` class will be updated to reflect this change.
+Starting from version 3.0 the class will be made `final` and has been marked as such in the current version.
+The following properties have been marked as deprecated and will be removed in version 3.0:
+
+- `sessionSavePath`
+- `sessionName`
+
+The following methods will also be removed and have been marked as deprecated in the current version:
+
+- `setCacheStorage`
+- `getCacheStorage`
+- `getCacheStorge`
+
+Going forward, you may move `laminas/laminas-cache` to your application's direct requirements to keep using it,
+or find a PSR-16 implementation in the `psr/simple-cache-implementation` virtual repository.
+
 ## Removed Features
 
 ### `laminas/laminas-db` Removal

psalm-baseline.xml

@@ -439,6 +439,19 @@
     </PossiblyUnusedReturnValue>
   </file>
   <file src="src/SaveHandler/Cache.php">
+    <DeprecatedMethod>
+      <code><![CDATA[getCacheStorage]]></code>
+      <code><![CDATA[getCacheStorage]]></code>
+      <code><![CDATA[getCacheStorage]]></code>
+      <code><![CDATA[getCacheStorage]]></code>
+      <code><![CDATA[getCacheStorage]]></code>
+      <code><![CDATA[getCacheStorage]]></code>
+      <code><![CDATA[setCacheStorage]]></code>
+    </DeprecatedMethod>
+    <DeprecatedProperty>
+      <code><![CDATA[$this->sessionName]]></code>
+      <code><![CDATA[$this->sessionSavePath]]></code>
+    </DeprecatedProperty>
     <ImplementedReturnTypeMismatch>
       <code><![CDATA[bool]]></code>
     </ImplementedReturnTypeMismatch>

src/SaveHandler/Cache.php

@@ -10,19 +10,25 @@
  * Cache session save handler
  *
  * @see ReturnTypeWillChange
+ *
+ * @final
  */
 class Cache implements SaveHandlerInterface
 {
     /**
      * Session Save Path
      *
+     * @deprecated This property will be removed in version 3.0.
+     *
      * @var string
      */
     protected $sessionSavePath;
 
     /**
      * Session Name
      *
+     * @deprecated This property will be removed in version 3.0.
+     *
      * @var string
      */
     protected $sessionName;
@@ -52,7 +58,6 @@ public function __construct(CacheStorage $cacheStorage)
     #[ReturnTypeWillChange]
     public function open($path, $name)
     {
-        // @todo figure out if we want to use these
         $this->sessionSavePath = $path;
         $this->sessionName     = $name;
 
@@ -131,6 +136,8 @@ public function gc($maxlifetime)
     /**
      * Set cache storage
      *
+     * @deprecated This method will be removed in version 3.0.
+     *
      * @return Cache
      */
     public function setCacheStorage(CacheStorage $cacheStorage)
@@ -142,6 +149,8 @@ public function setCacheStorage(CacheStorage $cacheStorage)
     /**
      * Get cache storage
      *
+     * @deprecated This method will be removed in version 3.0.
+     *
      * @return CacheStorage
      */
     public function getCacheStorage()