[HttpFoundation] deprecate using with the legacy mongo extension; use it with the mongodb/mongodb package and ext-mongodb instead

Author: Tobion

UPGRADE-3.4.md

@@ -234,6 +234,9 @@ HttpFoundation
  * `NativeSessionStorage::setSaveHandler()` now takes an instance of `\SessionHandlerInterface` as argument.
    Not passing it is deprecated and will throw a `TypeError` in 4.0.
 
+ * Using `Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler` with the legacy mongo extension
+   has been deprecated and will be removed in 4.0. Use it with the mongodb/mongodb package and ext-mongodb instead.
+
 HttpKernel
 ----------
 

UPGRADE-4.0.md

@@ -540,6 +540,9 @@ HttpFoundation
 
  * `NativeSessionStorage::setSaveHandler()` now requires an instance of `\SessionHandlerInterface` as argument.
 
+ * The `Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler` does not work with the legacy
+   mongo extension anymore. It requires mongodb/mongodb package and ext-mongodb.
+
 HttpKernel
 ----------
 

src/Symfony/Component/HttpFoundation/CHANGELOG.md

@@ -7,6 +7,7 @@ CHANGELOG
  * deprecated the `NativeSessionHandler` class,
  * deprecated the `AbstractProxy`, `NativeProxy` and `SessionHandlerProxy` classes,
  * deprecated setting session save handlers that do not implement `\SessionHandlerInterface` in `NativeSessionStorage::setSaveHandler()`
+ * deprecated using `MongoDbSessionHandler` with the legacy mongo extension; use it with the mongodb/mongodb package and ext-mongodb instead
 
 3.3.0
 -----

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

@@ -12,7 +12,12 @@
 namespace Symfony\Component\HttpFoundation\Session\Storage\Handler;
 
 /**
+ * Session handler using the mongodb/mongodb package and MongoDB driver extension.
+ *
  * @author Markus Bachmann <[email protected]>
+ *
+ * @see https://packagist.org/packages/mongodb/mongodb
+ * @see http://php.net/manual/en/set.mongodb.php
  */
 class MongoDbSessionHandler implements \SessionHandlerInterface
 {
@@ -57,14 +62,18 @@ class MongoDbSessionHandler implements \SessionHandlerInterface
      * If you use such an index, you can drop `gc_probability` to 0 since
      * no garbage-collection is required.
      *
-     * @param \Mongo|\MongoClient|\MongoDB\Client $mongo   A MongoDB\Client, MongoClient or Mongo instance
-     * @param array                               $options An associative array of field options
+     * @param \MongoDB\Client $mongo   A MongoDB\Client instance
+     * @param array           $options An associative array of field options
      *
      * @throws \InvalidArgumentException When MongoClient or Mongo instance not provided
      * @throws \InvalidArgumentException When "database" or "collection" not provided
      */
     public function __construct($mongo, array $options)
     {
+        if ($mongo instanceof \MongoClient || $mongo instanceof \Mongo) {
+            @trigger_error(sprintf('Using %s with the legacy mongo extension is deprecated as of 3.4 and will be removed in 4.0. Use it with the mongodb/mongodb package and ext-mongodb instead.', __CLASS__), E_USER_DEPRECATED);
+        }
+
         if (!($mongo instanceof \MongoDB\Client || $mongo instanceof \MongoClient || $mongo instanceof \Mongo)) {
             throw new \InvalidArgumentException('MongoClient or Mongo instance required');
         }