[HttpFoundation] Deprecate compatibility with PHP <5.4 sessions

Author: Alexandru Furculita

UPGRADE-3.4.md

@@ -205,6 +205,24 @@ 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 your `\SessionHandlerInterface` implementation directly.
+
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Proxy\NativeProxy` class has been
+   deprecated and will be removed in 4.0. Use your `\SessionHandlerInterface` implementation directly.
+
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy` class has been
+   deprecated and will be removed in 4.0. Use your `\SessionHandlerInterface` implementation directly.
+
+ * `NativeSessionStorage::setSaveHandler()` now takes an instance of `\SessionHandlerInterface` as argument.
+   Not passing it is deprecated and will throw a `TypeError` in 4.0.
+
 HttpKernel
 ----------
 

UPGRADE-4.0.md

@@ -524,6 +524,13 @@ 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`,
+   `Symfony\Component\HttpFoundation\Session\Storage\Proxy\NativeProxy` and 
+   `Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy` classes have been removed.
+
+ * `NativeSessionStorage::setSaveHandler()` now requires an instance of `\SessionHandlerInterface` as argument.
+
 HttpKernel
 ----------
 

src/Symfony/Bridge/Twig/Tests/AppVariableTest.php

@@ -47,8 +47,9 @@ public function testEnvironment()
 
     public function testGetSession()
     {
+        $session = $this->getMockBuilder(Session::class)->disableOriginalConstructor()->getMock();
         $request = $this->getMockBuilder('Symfony\Component\HttpFoundation\Request')->getMock();
-        $request->method('getSession')->willReturn($session = new Session());
+        $request->method('getSession')->willReturn($session);
 
         $this->setRequestStack($request);
 
@@ -167,8 +168,9 @@ public function testGetFlashesWithNoRequest()
 
     public function testGetFlashesWithNoSessionStarted()
     {
+        $session = $this->getMockBuilder(Session::class)->disableOriginalConstructor()->getMock();
         $request = $this->getMockBuilder('Symfony\Component\HttpFoundation\Request')->getMock();
-        $request->method('getSession')->willReturn(new Session());
+        $request->method('getSession')->willReturn($session);
 
         $this->setRequestStack($request);
 
@@ -257,7 +259,7 @@ private function setFlashMessages()
         $flashBag = new FlashBag();
         $flashBag->initialize($flashMessages);
 
-        $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\Session')->getMock();
+        $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\Session')->disableOriginalConstructor()->getMock();
         $session->method('isStarted')->willReturn(true);
         $session->method('getFlashBag')->willReturn($flashBag);
 

src/Symfony/Bundle/FrameworkBundle/Tests/Controller/ControllerTraitTest.php

@@ -376,7 +376,7 @@ public function testRedirectToRoute()
     public function testAddFlash()
     {
         $flashBag = new FlashBag();
-        $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\Session')->getMock();
+        $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\Session')->disableOriginalConstructor()->getMock();
         $session->expects($this->once())->method('getFlashBag')->willReturn($flashBag);
 
         $container = new Container();

src/Symfony/Component/HttpFoundation/CHANGELOG.md

@@ -1,6 +1,13 @@
 CHANGELOG
 =========
 
+3.4.0
+-----
+
+ * deprecated the `NativeSessionHandler` class,
+ * deprecated the `AbstractProxy`, `NativeProxy` and `SessionHandlerProxy` classes,
+ * deprecated setting session save handlers that do not implement `\SessionHandlerInterface` in `NativeSessionStorage::setSaveHandler()`
+
 3.3.0
 -----
 

src/Symfony/Component/HttpFoundation/Session/Storage/Handler/MemcacheSessionHandler.php

@@ -12,8 +12,6 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;
 
 /**
- * MemcacheSessionHandler.
- *
  * @author Drak <[email protected]>
  */
 class MemcacheSessionHandler implements \SessionHandlerInterface

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.
  *

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 <[email protected]>
  */
 class MongoDbSessionHandler implements \SessionHandlerInterface

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 <[email protected]>
  */
 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)
     {

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

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 <[email protected]>

src/Symfony/Component/HttpFoundation/Session/Storage/MetadataBag.php

@@ -54,8 +54,6 @@ class MetadataBag implements SessionBagInterface
     private $updateThreshold;
 
     /**
-     * Constructor.
-     *
      * @param string $storageKey      The key used to store bag in the session
      * @param int    $updateThreshold The time to wait between two UPDATED updates
      */

src/Symfony/Component/HttpFoundation/Session/Storage/MockArraySessionStorage.php

@@ -63,8 +63,6 @@ class MockArraySessionStorage implements SessionStorageInterface
     protected $bags = array();
 
     /**
-     * Constructor.
-     *
      * @param string      $name    Session name
      * @param MetadataBag $metaBag MetadataBag instance
      */

src/Symfony/Component/HttpFoundation/Session/Storage/MockFileSessionStorage.php

@@ -30,8 +30,6 @@ class MockFileSessionStorage extends MockArraySessionStorage
     private $savePath;
 
     /**
-     * Constructor.
-     *
      * @param string      $savePath Path of directory to save session files
      * @param string      $name     Session name
      * @param MetadataBag $metaBag  MetadataBag instance

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;
 
@@ -25,8 +24,6 @@
 class NativeSessionStorage implements SessionStorageInterface
 {
     /**
-     * Array of SessionBagInterface.
-     *
      * @var SessionBagInterface[]
      */
     protected $bags;
@@ -42,7 +39,7 @@ class NativeSessionStorage implements SessionStorageInterface
     protected $closed = false;
 
     /**
-     * @var AbstractProxy
+     * @var AbstractProxy|\SessionHandlerInterface
      */
     protected $saveHandler;
 
@@ -52,8 +49,6 @@ class NativeSessionStorage implements SessionStorageInterface
     protected $metadataBag;
 
     /**
-     * Constructor.
-     *
      * Depending on how you want the storage driver to behave you probably
      * want to override this constructor entirely.
      *
@@ -97,9 +92,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 \SessionHandlerInterface|null $handler
+     * @param MetadataBag                   $metaBag MetadataBag
      */
     public function __construct(array $options = array(), $handler = null, MetadataBag $metaBag = null)
     {
@@ -116,7 +111,7 @@ public function __construct(array $options = array(), $handler = null, MetadataB
     /**
      * Gets the save handler instance.
      *
-     * @return AbstractProxy
+     * @return AbstractProxy|\SessionHandlerInterface
      */
     public function getSaveHandler()
     {
@@ -276,7 +271,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 +353,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 +362,23 @@ public function setOptions(array $options)
      * @see http://php.net/sessionhandler
      * @see http://github.com/drak/NativeSession
      *
-     * @param AbstractProxy|NativeSessionHandler|\SessionHandlerInterface|null $saveHandler
+     * @param \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.');
+        }
+
+        if ($saveHandler instanceof AbstractProxy) {
+            @trigger_error(
+                'Using session save handlers that are instances of AbstractProxy is deprecated since version 3.4 and will be removed in 4.0.',
+                E_USER_DEPRECATED
+            );
         }
 
         // Wrap $saveHandler in proxy and prevent double wrapping of proxy

src/Symfony/Component/HttpFoundation/Session/Storage/PhpBridgeSessionStorage.php

@@ -11,9 +11,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.
  *
@@ -22,10 +19,8 @@
 class PhpBridgeSessionStorage extends NativeSessionStorage
 {
     /**
-     * Constructor.
-     *
-     * @param AbstractProxy|NativeSessionHandler|\SessionHandlerInterface|null $handler
-     * @param MetadataBag                                                      $metaBag MetadataBag
+     * @param \SessionHandlerInterface|null $handler
+     * @param MetadataBag                   $metaBag MetadataBag
      */
     public function __construct($handler = null, MetadataBag $metaBag = null)
     {

src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/AbstractProxy.php

@@ -11,8 +11,10 @@
 
 namespace Symfony\Component\HttpFoundation\Session\Storage\Proxy;
 
+@trigger_error('The '.__NAMESPACE__.'\AbstractProxy class is deprecated since version 3.4 and will be removed in 4.0. Use your session handler implementation directly.', E_USER_DEPRECATED);
+
 /**
- * AbstractProxy.
+ * @deprecated since version 3.4, to be removed in 4.0. Use your session handler implementation directly.
  *
  * @author Drak <[email protected]>
  */

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 your session handler implementation directly.', 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 your session handler implementation directly.
  *
  * @author Drak <[email protected]>
  */

src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/SessionHandlerProxy.php

@@ -11,8 +11,10 @@
 
 namespace Symfony\Component\HttpFoundation\Session\Storage\Proxy;
 
+@trigger_error('The '.__NAMESPACE__.'\SessionHandlerProxy class is deprecated since version 3.4 and will be removed in 4.0. Use your session handler implementation directly.', E_USER_DEPRECATED);
+
 /**
- * SessionHandler proxy.
+ * @deprecated since version 3.4, to be removed in 4.0. Use your session handler implementation directly.
  *
  * @author Drak <[email protected]>
  */
@@ -23,11 +25,6 @@ class SessionHandlerProxy extends AbstractProxy implements \SessionHandlerInterf
      */
     protected $handler;
 
-    /**
-     * Constructor.
-     *
-     * @param \SessionHandlerInterface $handler
-     */
     public function __construct(\SessionHandlerInterface $handler)
     {
         $this->handler = $handler;

src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Handler/NativeSessionHandlerTest.php

@@ -21,6 +21,7 @@
  *
  * @runTestsInSeparateProcesses
  * @preserveGlobalState disabled
+ * @group legacy
  */
 class NativeSessionHandlerTest extends TestCase
 {