PHPLIB-1489: Handle CursorId deprecations

Author: alcaeus

src/ChangeStream.php

@@ -19,6 +19,7 @@
 
 use Iterator;
 use MongoDB\BSON\Document;
+use MongoDB\BSON\Int64;
 use MongoDB\Codec\DocumentCodec;
 use MongoDB\Driver\CursorId;
 use MongoDB\Driver\Exception\ConnectionException;
@@ -32,6 +33,10 @@
 use function assert;
 use function call_user_func;
 use function in_array;
+use function sprintf;
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
 
 /**
  * Iterator for a change stream.
@@ -105,10 +110,23 @@ public function current()
         return $this->codec->decode($value);
     }
 
-    /** @return CursorId */
-    public function getCursorId()
+    /** @return CursorId|Int64 */
+    #[ReturnTypeWillChange]
+    public function getCursorId(bool $asInt64 = false)
     {
-        return $this->iterator->getInnerIterator()->getId();
+        if (! $asInt64) {
+            @trigger_error(
+                sprintf(
+                    'The method "%s" will no longer return a "%s" instance in the future. Pass "true" as argument to change to the new behavior and receive a "%s" instance instead.',
+                    __METHOD__,
+                    CursorId::class,
+                    Int64::class,
+                ),
+                E_USER_DEPRECATED,
+            );
+        }
+
+        return $this->iterator->getInnerIterator()->getId($asInt64);
     }
 
     /**

src/Model/CodecCursor.php

@@ -19,17 +19,20 @@
 
 use Iterator;
 use MongoDB\BSON\Document;
+use MongoDB\BSON\Int64;
 use MongoDB\Codec\DocumentCodec;
 use MongoDB\Driver\Cursor;
 use MongoDB\Driver\CursorId;
 use MongoDB\Driver\CursorInterface;
 use MongoDB\Driver\Server;
+use ReturnTypeWillChange;
 
 use function assert;
 use function iterator_to_array;
 use function sprintf;
 use function trigger_error;
 
+use const E_USER_DEPRECATED;
 use const E_USER_WARNING;
 
 /**
@@ -73,9 +76,23 @@ public static function fromCursor(Cursor $cursor, DocumentCodec $codec): self
         return new self($cursor, $codec);
     }
 
-    public function getId(): CursorId
+    /** @return CursorId|Int64 */
+    #[ReturnTypeWillChange]
+    public function getId(bool $asInt64 = false)
     {
-        return $this->cursor->getId();
+        if (! $asInt64) {
+            @trigger_error(
+                sprintf(
+                    'The method "%s" will no longer return a "%s" instance in the future. Pass "true" as argument to change to the new behavior and receive a "%s" instance instead.',
+                    __METHOD__,
+                    CursorId::class,
+                    Int64::class,
+                ),
+                E_USER_DEPRECATED,
+            );
+        }
+
+        return $this->cursor->getId($asInt64);
     }
 
     public function getServer(): Server

tests/Model/CodecCursorFunctionalTest.php

@@ -2,10 +2,18 @@
 
 namespace MongoDB\Tests\Model;
 
+use MongoDB\BSON\Int64;
 use MongoDB\Codec\DocumentCodec;
+use MongoDB\Driver\CursorId;
 use MongoDB\Model\CodecCursor;
 use MongoDB\Tests\FunctionalTestCase;
 
+use function restore_error_handler;
+use function set_error_handler;
+
+use const E_DEPRECATED;
+use const E_USER_DEPRECATED;
+
 class CodecCursorFunctionalTest extends FunctionalTestCase
 {
     public function setUp(): void
@@ -27,4 +35,70 @@ public function testSetTypeMap(): void
 
         $codecCursor->setTypeMap(['root' => 'array']);
     }
+
+    public function testGetIdReturnTypeWithoutArgument(): void
+    {
+        $collection = self::createTestClient()->selectCollection($this->getDatabaseName(), $this->getCollectionName());
+        $cursor = $collection->find();
+
+        $codecCursor = CodecCursor::fromCursor($cursor, $this->createMock(DocumentCodec::class));
+
+        $deprecations = [];
+
+        try {
+            $previousErrorHandler = set_error_handler(
+                function (...$args) use (&$previousErrorHandler, &$deprecations) {
+                    $deprecations[] = $args;
+
+                    return true;
+                },
+                E_USER_DEPRECATED | E_DEPRECATED,
+            );
+
+            $cursorId = $codecCursor->getId();
+        } finally {
+            restore_error_handler();
+        }
+
+        self::assertInstanceOf(CursorId::class, $cursorId);
+
+        // Expect 2 deprecations: 1 from CodecCursor, one from Cursor
+        self::assertCount(2, $deprecations);
+        self::assertSame(
+            'The method "MongoDB\Model\CodecCursor::getId" will no longer return a "MongoDB\Driver\CursorId" instance in the future. Pass "true" as argument to change to the new behavior and receive a "MongoDB\BSON\Int64" instance instead.',
+            $deprecations[0][1],
+        );
+        self::assertSame(
+            'MongoDB\Driver\Cursor::getId(): The method "MongoDB\Driver\Cursor::getId" will no longer return a "MongoDB\Driver\CursorId" instance in the future. Pass "true" as argument to change to the new behavior and receive a "MongoDB\BSON\Int64" instance instead.',
+            $deprecations[1][1],
+        );
+    }
+
+    public function testGetIdReturnTypeWithArgument(): void
+    {
+        $collection = self::createTestClient()->selectCollection($this->getDatabaseName(), $this->getCollectionName());
+        $cursor = $collection->find();
+
+        $codecCursor = CodecCursor::fromCursor($cursor, $this->createMock(DocumentCodec::class));
+
+        $deprecations = [];
+
+        try {
+            $previousErrorHandler = set_error_handler(
+                function (...$args) use (&$previousErrorHandler, &$deprecations) {
+                    $deprecations[] = $args;
+
+                    return true;
+                },
+                E_USER_DEPRECATED | E_DEPRECATED,
+            );
+
+            $cursorId = $codecCursor->getId(true);
+        } finally {
+            restore_error_handler();
+        }
+
+        self::assertInstanceOf(Int64::class, $cursorId);
+        self::assertCount(0, $deprecations);
+    }
 }