[HttpFoundation] Deprecate compatibility with PHP <5.4 sessions

Alexandru Furculita · Tobion · commit 3deb3940ab19 · 2017-09-26T14:23:43.000+02:00
diff --git a/UPGRADE-3.4.md b/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
 ----------
 
diff --git a/UPGRADE-4.0.md b/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
 ----------
 
diff --git a/src/Symfony/Bridge/Twig/Tests/AppVariableTest.php b/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);
 
diff --git a/src/Symfony/Bundle/FrameworkBundle/Tests/Controller/ControllerTraitTest.php b/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();
diff --git a/src/Symfony/Component/HttpFoundation/CHANGELOG.md b/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
 -----
 
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/MetadataBag.php b/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
      */
diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/MockArraySessionStorage.php b/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
      */
diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/MockFileSessionStorage.php b/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
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;
 
@@ -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
diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/PhpBridgeSessionStorage.php b/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)
     {
diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/Proxy/AbstractProxy.php b/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 <drak@zikula.org>
  */
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 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 <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
@@ -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 <drak@zikula.org>
  */
@@ -23,11 +25,6 @@ class SessionHandlerProxy extends AbstractProxy implements \SessionHandlerInterf
      */
     protected $handler;
 
-    /**
-     * Constructor.
-     *
-     * @param \SessionHandlerInterface $handler
-     */
     public function __construct(\SessionHandlerInterface $handler)
     {
         $this->handler = $handler;
diff --git a/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Handler/NativeSessionHandlerTest.php b/src/Symfony/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
diff --git a/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/NativeProxyTest.php b/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/NativeProxyTest.php
diff --git a/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/SessionHandlerProxyTest.php b/src/Symfony/Component/HttpFoundation/Tests/Session/Storage/Proxy/SessionHandlerProxyTest.php

Original file line number	Diff line number	Diff line change
`@@ -376,7 +376,7 @@ public function testRedirectToRoute()`
`376`	`376`	`public function testAddFlash()`
`377`	`377`	`{`
`378`	`378`	`$flashBag = new FlashBag();`
`379`		`- $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\Session')->getMock();`
	`379`	`+ $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\Session')->disableOriginalConstructor()->getMock();`
`380`	`380`	`$session->expects($this->once())->method('getFlashBag')->willReturn($flashBag);`
`381`	`381`
`382`	`382`	`$container = new Container();`
Original file line number	Diff line number	Diff line change
`@@ -12,8 +12,6 @@`
`12`	`12`	`namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;`
`13`	`13`
`14`	`14`	`/**`
`15`		`- * MemcachedSessionHandler.`
`16`		`- *`
`17`	`15`	`* Memcached based session storage handler based on the Memcached class`
`18`	`16`	`* provided by the PHP memcached extension.`
`19`	`17`	`*`
Original file line number	Diff line number	Diff line change
`@@ -12,24 +12,21 @@`
`12`	`12`	`namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;`
`13`	`13`
`14`	`14`	`/**`
`15`		`- * NativeFileSessionHandler.`
`16`		`- *`
`17`	`15`	`* Native session handler using PHP's built in file storage.`
`18`	`16`	`*`
`19`	`17`	`* @author Drak <[email protected]>`
`20`	`18`	`*/`
`21`	`19`	`class NativeFileSessionHandler extends NativeSessionHandler`
`22`	`20`	`{`
`23`	`21`	`/**`
`24`		`- * Constructor.`
`25`		`- *`
`26`	`22`	`* @param string $savePath Path of directory to save session files`
`27`	`23`	`* Default null will leave setting as defined by PHP.`
`28`	`24`	`* '/path', 'N;/path', or 'N;octal-mode;/path`
`29`	`25`	`*`
`30`	`26`	`* @see http://php.net/session.configuration.php#ini.session.save-path for further details.`
`31`	`27`	`*`
`32`	`28`	`* @throws \InvalidArgumentException On invalid $savePath`
	`29`	`+ * @throws \RuntimeException When failing to create the save directory`
`33`	`30`	`*/`
`34`	`31`	`public function __construct($savePath = null)`
`35`	`32`	`{`