[HttpFoundation] Deprecate <5.4 session functionality

Signed-off-by: Alexandru Furculita <alex@furculita.net>
symfony · afurculita · Sep 17, 2017 · Sep 24, 2017 · Sep 25, 2017 · Sep 24, 2017
commit 73a1235c176ebb09e8f402343e90d5e6c9dff872
diff --git a/UPGRADE-3.4.md b/UPGRADE-3.4.md
@@ -205,6 +205,30 @@ FrameworkBundle
   `TranslationDebugCommand`, `TranslationUpdateCommand`, `XliffLintCommand`
    and `YamlLintCommand` classes have been marked as final

+HttpFoundation
+--------------
+
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Handler\NativeSessionHandler`
+   class has been deprecated and will be removed in 4.0. Use the `\SessionHandler` class instead.
+
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Proxy\AbstractProxy` class has been
+   deprecated and will be removed in 4.0. Use the `Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy`
+   class instead.
+
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Proxy\NativeProxy` class has been
+   deprecated and will be removed in 4.0. Use the `Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy`
+   class instead.
+
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy::isSessionHandlerInterface()`
+   method has been deprecated and will be removed in 4.0.
+
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy::isWrapper()`
+   method has been deprecated and will be removed in 4.0. You can check explicitly if the proxy wraps
+   a `\SessionHandler` instance.
+
+ * `NativeSessionStorage::setSaveHandler()` now takes an instance of `\SessionHandlerInterface` as argument.
+   Not passing it is deprecated and will throw a `TypeError` in 4.0.
+
 HttpKernel
 ----------


diff --git a/UPGRADE-4.0.md b/UPGRADE-4.0.md
@@ -524,6 +524,15 @@ HttpFoundation
 * The ability to check only for cacheable HTTP methods using `Request::isMethodSafe()` is
   not supported anymore, use `Request::isMethodCacheable()` instead.

+ * The `Symfony\Component\HttpFoundation\Session\Storage\Handler\NativeSessionHandler`, 
+   `Symfony\Component\HttpFoundation\Session\Storage\Proxy\AbstractProxy` and 
+   `Symfony\Component\HttpFoundation\Session\Storage\Proxy\NativeProxy` classes have been removed.
+
+ * The `SessionHandlerProxy::isSessionHandlerInterface()` and `SessionHandlerProxy::isWrapper()`
+   methods have been removed.
+
+ * `NativeSessionStorage::setSaveHandler()` now requires an instance of `\SessionHandlerInterface` as argument.
+
 HttpKernel
 ----------


diff --git a/src/Symfony/Component/HttpFoundation/CHANGELOG.md b/src/Symfony/Component/HttpFoundation/CHANGELOG.md
@@ -1,6 +1,14 @@
 CHANGELOG
 =========

+3.4.0
+-----
+
+ * deprecated the `NativeSessionHandler` class,
+ * deprecated the `AbstractProxy` and `NativeProxy` classes in favor of `SessionHandlerProxy` class,
+ * deprecated the `SessionHandlerProxy::isSessionHandlerInterface()` and `SessionHandlerProxy::isWrapper()` methods,
+ * deprecated setting session save handlers that do not implement `\SessionHandlerInterface` in `NativeSessionStorage::setSaveHandler()`
+
 3.3.0
 -----


diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MemcacheSessionHandler.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MemcacheSessionHandler.php
@@ -12,8 +12,6 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;

 /**
- * MemcacheSessionHandler.
- *
 * @author Drak <drak@zikula.org>
 */
 class MemcacheSessionHandler implements \SessionHandlerInterface

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MemcachedSessionHandler.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MemcachedSessionHandler.php
@@ -12,8 +12,6 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;

 /**
- * MemcachedSessionHandler.
- *
 * Memcached based session storage handler based on the Memcached class
 * provided by the PHP memcached extension.
 *

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MongoDbSessionHandler.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MongoDbSessionHandler.php
@@ -12,8 +12,6 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;

 /**
- * MongoDB session handler.
- *
 * @author Markus Bachmann <markus.bachmann@bachi.biz>
 */
 class MongoDbSessionHandler implements \SessionHandlerInterface

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NativeFileSessionHandler.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NativeFileSessionHandler.php
@@ -12,24 +12,21 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;

 /**
- * NativeFileSessionHandler.
- *
 * Native session handler using PHP's built in file storage.
 *
 * @author Drak <drak@zikula.org>
 */
 class NativeFileSessionHandler extends NativeSessionHandler
 {
    /**
-     * Constructor.
-     *
     * @param string $savePath Path of directory to save session files
     *                         Default null will leave setting as defined by PHP.
     *                         '/path', 'N;/path', or 'N;octal-mode;/path
     *
     * @see http://php.net/session.configuration.php#ini.session.save-path for further details.
     *
     * @throws \InvalidArgumentException On invalid $savePath
+     * @throws \RuntimeException         When failing to create the save directory
     */
    public function __construct($savePath = null)
    {

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NativeSessionHandler.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NativeSessionHandler.php
@@ -11,9 +11,10 @@

 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;

+@trigger_error('The '.__NAMESPACE__.'\NativeSessionHandler class is deprecated since version 3.4 and will be removed in 4.0. Use the \SessionHandler class instead.', E_USER_DEPRECATED);
+
 /**
- * Adds SessionHandler functionality if available.
- *
+ * @deprecated since version 3.4, to be removed in 4.0. Use \SessionHandler instead.
 * @see http://php.net/sessionhandler
 */
 class NativeSessionHandler extends \SessionHandler

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NullSessionHandler.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NullSessionHandler.php
@@ -12,8 +12,6 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;

 /**
- * NullSessionHandler.
- *
 * Can be used in unit testing or in a situations where persisted sessions are not desired.
 *
 * @author Drak <drak@zikula.org>

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/NativeSessionStorage.php b/src/Symfony/Component/HttpFoundation/Session/Storage/NativeSessionStorage.php
@@ -13,7 +13,6 @@

 use Symfony\Component\Debug\Exception\ContextErrorException;
 use Symfony\Component\HttpFoundation\Session\SessionBagInterface;
-use Symfony\Component\HttpFoundation\Session\Storage\Handler\NativeSessionHandler;
 use Symfony\Component\HttpFoundation\Session\Storage\Proxy\AbstractProxy;
 use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy;

@@ -97,9 +96,9 @@ class NativeSessionStorage implements SessionStorageInterface
     * trans_sid_hosts, $_SERVER['HTTP_HOST']
     * trans_sid_tags, "a=href,area=href,frame=src,form="
     *
-     * @param array                                                            $options Session configuration options
-     * @param AbstractProxy|NativeSessionHandler|\SessionHandlerInterface|null $handler
-     * @param MetadataBag                                                      $metaBag MetadataBag
+     * @param array                                       $options Session configuration options
+     * @param AbstractProxy|\SessionHandlerInterface|null $handler
+     * @param MetadataBag                                 $metaBag MetadataBag
     */
    public function __construct(array $options = array(), $handler = null, MetadataBag $metaBag = null)
    {
@@ -276,7 +275,7 @@ public function getBag($name)
            throw new \InvalidArgumentException(sprintf('The SessionBagInterface %s is not registered.', $name));
        }

-        if ($this->saveHandler->isActive() && !$this->started) {
+        if (!$this->started && $this->saveHandler->isActive()) {
            $this->loadSession();
        } elseif (!$this->started) {
            $this->start();
@@ -358,7 +357,7 @@ public function setOptions(array $options)
     *     ini_set('session.save_handler', 'files');
     *     ini_set('session.save_path', '/tmp');
     *
-     * or pass in a NativeSessionHandler instance which configures session.save_handler in the
+     * or pass in a \SessionHandler instance which configures session.save_handler in the
     * constructor, for a template see NativeFileSessionHandler or use handlers in
     * composer package drak/native-session
     *
@@ -367,17 +366,16 @@ public function setOptions(array $options)
     * @see http://php.net/sessionhandler
     * @see http://github.com/drak/NativeSession
     *
-     * @param AbstractProxy|NativeSessionHandler|\SessionHandlerInterface|null $saveHandler
+     * @param AbstractProxy|\SessionHandlerInterface|null $saveHandler
     *
     * @throws \InvalidArgumentException
     */
    public function setSaveHandler($saveHandler = null)
    {
        if (!$saveHandler instanceof AbstractProxy &&
-            !$saveHandler instanceof NativeSessionHandler &&
            !$saveHandler instanceof \SessionHandlerInterface &&
            null !== $saveHandler) {
-            throw new \InvalidArgumentException('Must be instance of AbstractProxy or NativeSessionHandler; implement \SessionHandlerInterface; or be null.');
+            throw new \InvalidArgumentException('Must be instance of AbstractProxy; implement \SessionHandlerInterface; or be null.');
        }

        // Wrap $saveHandler in proxy and prevent double wrapping of proxy
@@ -390,6 +388,8 @@ public function setSaveHandler($saveHandler = null)

        if ($this->saveHandler instanceof \SessionHandlerInterface) {
            session_set_save_handler($this->saveHandler, false);
+        } else {
+            @trigger_error('Using session save handlers that do not implement \SessionHandlerInterface is deprecated since version 3.4 and will be removed in 4.0.', E_USER_DEPRECATED);
        }
    }


diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/PhpBridgeSessionStorage.php b/src/Symfony/Component/HttpFoundation/Session/Storage/PhpBridgeSessionStorage.php
@@ -12,7 +12,6 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage;

 use Symfony\Component\HttpFoundation\Session\Storage\Proxy\AbstractProxy;
-use Symfony\Component\HttpFoundation\Session\Storage\Handler\NativeSessionHandler;

 /**
 * Allows session to be started by PHP and managed by Symfony.
@@ -24,8 +23,8 @@ class PhpBridgeSessionStorage extends NativeSessionStorage
    /**
     * Constructor.
     *
-     * @param AbstractProxy|NativeSessionHandler|\SessionHandlerInterface|null $handler
-     * @param MetadataBag                                                      $metaBag MetadataBag
+     * @param AbstractProxy|\SessionHandlerInterface|null $handler
+     * @param MetadataBag                                 $metaBag MetadataBag
     */
    public function __construct($handler = null, MetadataBag $metaBag = null)
    {

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/AbstractProxy.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/AbstractProxy.php
@@ -12,7 +12,7 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Proxy;

 /**
- * AbstractProxy.
+ * @deprecated since version 3.4, to be removed in 4.0. Use SessionHandlerProxy instead.
 *
 * @author Drak <drak@zikula.org>
 */
@@ -21,6 +21,8 @@ abstract class AbstractProxy
    /**
     * Flag if handler wraps an internal PHP session handler (using \SessionHandler).
     *
+     * @deprecated since version 3.4 and will be removed in 4.0.
+     *
     * @var bool
     */
    protected $wrapper = false;
@@ -43,20 +45,28 @@ public function getSaveHandlerName()
    /**
     * Is this proxy handler and instance of \SessionHandlerInterface.
     *
+     * @deprecated since version 3.4 and will be removed in 4.0.
+     *
     * @return bool
     */
    public function isSessionHandlerInterface()
    {
+        @trigger_error('isSessionHandlerInterface() is deprecated since version 3.4 and will be removed in 4.0. A session handler proxy should always implement \SessionHandlerInterface.', E_USER_DEPRECATED);
+
        return $this instanceof \SessionHandlerInterface;
    }

    /**
     * Returns true if this handler wraps an internal PHP session save handler using \SessionHandler.
     *
+     * @deprecated since version 3.4 and will be removed in 4.0.
+     *
     * @return bool
     */
    public function isWrapper()
    {
+        @trigger_error('isWrapper() is deprecated since version 3.4 and will be removed in 4.0. You should explicitly check if the handler proxy wraps a \SessionHandler instance.', E_USER_DEPRECATED);
+
        return $this->wrapper;
    }


diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/NativeProxy.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/NativeProxy.php
@@ -11,10 +11,12 @@

 namespace Symfony\Component\HttpFoundation\Session\Storage\Proxy;

+@trigger_error('The '.__NAMESPACE__.'\NativeProxy class is deprecated since version 3.4 and will be removed in 4.0. Use the Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy class instead.', E_USER_DEPRECATED);
+
 /**
- * NativeProxy.
+ * This proxy is built-in session handlers in PHP 5.3.x.
 *
- * This proxy is built-in session handlers in PHP 5.3.x
+ * @deprecated since version 3.4, to be removed in 4.0. Use SessionHandlerProxy instead.
 *
 * @author Drak <drak@zikula.org>
 */

diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/SessionHandlerProxy.php b/src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/SessionHandlerProxy.php
@@ -12,8 +12,6 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Proxy;

 /**
- * SessionHandler proxy.
- *
 * @author Drak <drak@zikula.org>
 */
 class SessionHandlerProxy extends AbstractProxy implements \SessionHandlerInterface
@@ -23,11 +21,6 @@ class SessionHandlerProxy extends AbstractProxy implements \SessionHandlerInterf
     */
    protected $handler;

-    /**
-     * Constructor.
-     *
-     * @param \SessionHandlerInterface $handler
-     */
    public function __construct(\SessionHandlerInterface $handler)
    {
        $this->handler = $handler;

diff --git a/...mfony/Component/HttpFoundation/Tests/Session/Storage/Handler/NativeSessionHandlerTest.php b/...mfony/Component/HttpFoundation/Tests/Session/Storage/Handler/NativeSessionHandlerTest.php
@@ -21,6 +21,7 @@
 *
 * @runTestsInSeparateProcesses
 * @preserveGlobalState disabled
+ * @group legacy
 */
 class NativeSessionHandlerTest extends TestCase
 {

diff --git a/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/AbstractProxyTest.php b/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/AbstractProxyTest.php
@@ -74,13 +74,19 @@ public function testGetSaveHandlerName()
        $this->assertNull($this->proxy->getSaveHandlerName());
    }

+    /**
+     * @group legacy
+     */
    public function testIsSessionHandlerInterface()
    {
        $this->assertFalse($this->proxy->isSessionHandlerInterface());
        $sh = new ConcreteSessionHandlerInterfaceProxy();
        $this->assertTrue($sh->isSessionHandlerInterface());
    }

+    /**
+     * @group legacy
+     */
    public function testIsWrapper()
    {
        $this->assertFalse($this->proxy->isWrapper());

diff --git a/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/NativeProxyTest.php b/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/NativeProxyTest.php
@@ -17,6 +17,8 @@
 /**
 * Test class for NativeProxy.
 *
+ * @group legacy
+ *
 * @author Drak <drak@zikula.org>
 */
 class NativeProxyTest extends TestCase
-Original file line number
+Diff line change
@@ -12,7 +12,6 @@
     namespace Symfony\Component\HttpFoundation\Session\Storage;
     use Symfony\Component\HttpFoundation\Session\Storage\Proxy\AbstractProxy;
-    use Symfony\Component\HttpFoundation\Session\Storage\Handler\NativeSessionHandler;
     /**
      * Allows session to be started by PHP and managed by Symfony.
@@ -24,8 +23,8 @@ class PhpBridgeSessionStorage extends NativeSessionStorage
         /**
          * Constructor.
          *
-         * @param AbstractProxy|NativeSessionHandler|\SessionHandlerInterface|null $handler
-         * @param MetadataBag                                                      $metaBag MetadataBag
+         * @param AbstractProxy|\SessionHandlerInterface|null $handler
             Copy link

  
      
    
  

  
      

  
    Contributor


      

  

  
    
      

      
            Tobion
  

      

      

      


        Sep 25, 2017


      
    

  


        
      
  
  
  
    

    There was a problem hiding this comment.


  

 
  
    

    Choose a reason for hiding this comment

    
      The reason will be displayed to describe this comment to others. Learn more.
    

    
      
      


  


  
    
      Argument types that are deprecated should be removed from the doc
    
  
  


    

        
      
  
  
    
  
  
  
    
    Sorry, something went wrong.
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.


  
  


          
      
  
    
    
      
        
            
    All reactions
+         * @param MetadataBag                                 $metaBag MetadataBag
          */
         public function __construct($handler = null, MetadataBag $metaBag = null)
         {
-          Expand Down