Remove compatibility layer for CursorId deprecation

Squashed commit of the following:

commit b06bffe
Author: Andreas Braun <[email protected]>
Date:   Thu Sep 19 12:56:07 2024 +0200

    Update psalm baseline

commit bb4bb56
Author: Andreas Braun <[email protected]>
Date:   Thu Sep 19 12:55:52 2024 +0200

    Remove CursorInterface::getId compatibility layer

commit 00fa5e4
Author: Andreas Braun <[email protected]>
Date:   Thu Sep 19 12:55:32 2024 +0200

    Add temporary stubs for cursor classes in 2.x

Author: alcaeus

psalm-baseline.xml

@@ -5,11 +5,7 @@
       <code><![CDATA[$document['name']]]></code>
       <code><![CDATA[$index->name]]></code>
     </MixedArgument>
-    <MixedArrayAccess>
-      <code><![CDATA[$document['name']]]></code>
-    </MixedArrayAccess>
     <MixedAssignment>
-      <code><![CDATA[$document]]></code>
       <code><![CDATA[$index]]></code>
       <code><![CDATA[$index]]></code>
       <code><![CDATA[$index]]></code>
@@ -23,6 +19,9 @@
     <PossiblyFalseArgument>
       <code><![CDATA[$uri]]></code>
     </PossiblyFalseArgument>
+    <PossiblyInvalidArrayAccess>
+      <code><![CDATA[$document['name']]]></code>
+    </PossiblyInvalidArrayAccess>
   </file>
   <file src="examples/persistable.php">
     <LessSpecificReturnStatement>
@@ -184,9 +183,6 @@
     <DeprecatedConstant>
       <code><![CDATA[self::CURSOR_NOT_FOUND]]></code>
     </DeprecatedConstant>
-    <TooManyArguments>
-      <code><![CDATA[getId]]></code>
-    </TooManyArguments>
   </file>
   <file src="src/Client.php">
     <MixedArgument>
@@ -339,6 +335,15 @@
     </MixedArgument>
   </file>
   <file src="src/Model/ChangeStreamIterator.php">
+    <InvalidReturnStatement>
+      <code><![CDATA[$cursor]]></code>
+    </InvalidReturnStatement>
+    <InvalidReturnType>
+      <code><![CDATA[CursorInterface<TValue>]]></code>
+    </InvalidReturnType>
+    <LessSpecificImplementedReturnType>
+      <code><![CDATA[CursorInterface<TValue>]]></code>
+    </LessSpecificImplementedReturnType>
     <MixedArgument>
       <code><![CDATA[$reply->cursor->nextBatch]]></code>
     </MixedArgument>
@@ -354,11 +359,6 @@
       <code><![CDATA[$this->current()]]></code>
     </PossiblyNullArgument>
   </file>
-  <file src="src/Model/CodecCursor.php">
-    <TooManyArguments>
-      <code><![CDATA[getId]]></code>
-    </TooManyArguments>
-  </file>
   <file src="src/Model/CollectionInfoCommandIterator.php">
     <DeprecatedInterface>
       <code><![CDATA[CollectionInfoCommandIterator]]></code>
@@ -724,18 +724,6 @@
       <code><![CDATA[is_object($result) ? ($result->value ?? null) : null]]></code>
     </MixedReturnStatement>
   </file>
-  <file src="src/Operation/FindOne.php">
-    <MixedAssignment>
-      <code><![CDATA[$document]]></code>
-    </MixedAssignment>
-    <MixedInferredReturnType>
-      <code><![CDATA[array|object|null]]></code>
-    </MixedInferredReturnType>
-    <MixedReturnStatement>
-      <code><![CDATA[$document === false ? null : $document]]></code>
-      <code><![CDATA[$document === false ? null : $document]]></code>
-    </MixedReturnStatement>
-  </file>
   <file src="src/Operation/FindOneAndDelete.php">
     <MixedAssignment>
       <code><![CDATA[$options['fields']]]></code>

psalm.xml.dist

@@ -21,6 +21,8 @@
         <file name="stubs/BSON/Document.stub.php"/>
         <file name="stubs/BSON/Iterator.stub.php"/>
         <file name="stubs/BSON/PackedArray.stub.php"/>
+        <file name="stubs/Driver/Cursor.stub.php"/>
+        <file name="stubs/Driver/CursorInterface.stub.php"/>
     </stubs>
 
     <issueHandlers>

src/ChangeStream.php

@@ -21,7 +21,6 @@
 use MongoDB\BSON\Document;
 use MongoDB\BSON\Int64;
 use MongoDB\Codec\DocumentCodec;
-use MongoDB\Driver\CursorId;
 use MongoDB\Driver\Exception\ConnectionException;
 use MongoDB\Driver\Exception\RuntimeException;
 use MongoDB\Driver\Exception\ServerException;
@@ -33,10 +32,6 @@
 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.
@@ -88,12 +83,8 @@ class ChangeStream implements Iterator
      */
     private bool $hasAdvanced = false;
 
-    /**
-     * @see https://php.net/iterator.current
-     * @return array|object|null
-     */
-    #[ReturnTypeWillChange]
-    public function current()
+    /** @see https://php.net/iterator.current */
+    public function current(): array|object|null
     {
         $value = $this->iterator->current();
 
@@ -106,26 +97,9 @@ public function current()
         return $this->codec->decode($value);
     }
 
-    /**
-     * @return CursorId|Int64
-     * @psalm-return ($asInt64 is true ? Int64 : CursorId)
-     */
-    #[ReturnTypeWillChange]
-    public function getCursorId(bool $asInt64 = false)
+    public function getCursorId(): Int64
     {
-        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);
+        return $this->iterator->getInnerIterator()->getId();
     }
 
     /**
@@ -255,7 +229,8 @@ private function onIteration(bool $incrementKey): void
          * have been received in the last response. Therefore, we can unset the
          * resumeCallable. This will free any reference to Watch as well as the
          * only reference to any implicit session created therein. */
-        if ((string) $this->getCursorId(true) === '0') {
+        // Use a type-unsafe comparison to compare with Int64 instances
+        if ($this->getCursorId() == 0) {
             $this->resumeCallable = null;
         }
 

src/Model/ChangeStreamIterator.php

@@ -17,7 +17,6 @@
 
 namespace MongoDB\Model;
 
-use Iterator;
 use IteratorIterator;
 use MongoDB\BSON\Document;
 use MongoDB\BSON\Serializable;
@@ -49,7 +48,7 @@
  *
  * @internal
  * @template TValue of array|object
- * @template-extends IteratorIterator<int, TValue, CursorInterface<int, TValue>&Iterator<int, TValue>>
+ * @template-extends IteratorIterator<int, TValue, CursorInterface<TValue>>
  */
 final class ChangeStreamIterator extends IteratorIterator implements CommandSubscriber
 {
@@ -77,18 +76,17 @@ public function current()
     }
 
     /**
-     * Necessary to let psalm know that we're always expecting a cursor as inner
-     * iterator. This could be side-stepped due to the class not being final,
-     * but it's very much an invalid use-case. This method can be dropped in 2.0
-     * once the class is final.
+     * This method is necessary as psalm does not properly set the return type
+     * of IteratorIterator::getInnerIterator to the templated iterator
      *
-     * @return CursorInterface<int, TValue>&Iterator<int, TValue>
+     * @see https://github.com/vimeo/psalm/pull/11100.
+     *
+     * @return CursorInterface<TValue>
      */
-    final public function getInnerIterator(): Iterator
+    public function getInnerIterator(): CursorInterface
     {
         $cursor = parent::getInnerIterator();
         assert($cursor instanceof CursorInterface);
-        assert($cursor instanceof Iterator);
 
         return $cursor;
     }
@@ -173,18 +171,10 @@ public function valid(): bool
 
     /**
      * @internal
-     * @psalm-param CursorInterface<int, TValue>&Iterator<int, TValue> $cursor
+     * @psalm-param CursorInterface<TValue> $cursor
      */
     public function __construct(CursorInterface $cursor, int $firstBatchSize, array|object|null $initialResumeToken, private ?object $postBatchResumeToken = null)
     {
-        if (! $cursor instanceof Iterator) {
-            throw InvalidArgumentException::invalidType(
-                '$cursor',
-                $cursor,
-                CursorInterface::class . '&' . Iterator::class,
-            );
-        }
-
         if (isset($initialResumeToken) && ! is_document($initialResumeToken)) {
             throw InvalidArgumentException::expectedDocumentType('$initialResumeToken', $initialResumeToken);
         }

src/Model/CodecCursor.php

@@ -17,30 +17,24 @@
 
 namespace MongoDB\Model;
 
-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;
 
 /**
  * @template TValue of object
- * @template-implements CursorInterface<int, TValue>
- * @template-implements Iterator<int, TValue>
+ * @template-implements CursorInterface<TValue>
  */
-class CodecCursor implements CursorInterface, Iterator
+class CodecCursor implements CursorInterface
 {
     private const TYPEMAP = ['root' => 'bson'];
 
@@ -64,33 +58,16 @@ public function current(): ?object
      * @param DocumentCodec<NativeClass> $codec
      * @return self<NativeClass>
      */
-    public static function fromCursor(Cursor $cursor, DocumentCodec $codec): self
+    public static function fromCursor(CursorInterface $cursor, DocumentCodec $codec): self
     {
         $cursor->setTypeMap(self::TYPEMAP);
 
         return new self($cursor, $codec);
     }
 
-    /**
-     * @return CursorId|Int64
-     * @psalm-return ($asInt64 is true ? Int64 : CursorId)
-     */
-    #[ReturnTypeWillChange]
-    public function getId(bool $asInt64 = false)
+    public function getId(): Int64
     {
-        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);
+        return $this->cursor->getId();
     }
 
     public function getServer(): Server
@@ -138,7 +115,7 @@ public function valid(): bool
     }
 
     /** @param DocumentCodec<TValue> $codec */
-    private function __construct(private Cursor $cursor, private DocumentCodec $codec)
+    private function __construct(private CursorInterface $cursor, private DocumentCodec $codec)
     {
     }
 }

stubs/Driver/Cursor.stub.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace MongoDB\Driver;
+
+use MongoDB\BSON\Int64;
+
+/**
+ * @template-covariant TValue of array|object
+ *
+ * @template-implements CursorInterface<TValue>
+ */
+final class Cursor implements CursorInterface
+{
+    /**
+     * @return TValue|null
+     * @psalm-ignore-nullable-return
+     */
+    public function current(): array|object|null
+    {
+    }
+
+    public function next(): void
+    {
+    }
+
+    /** @psalm-ignore-nullable-return */
+    public function key(): ?int
+    {
+    }
+
+    public function valid(): bool
+    {
+    }
+
+    public function rewind(): void
+    {
+    }
+
+    /** @return array<TValue> */
+    public function toArray(): array
+    {
+    }
+
+    public function getId(): Int64
+    {
+    }
+
+    public function getServer(): Server
+    {
+    }
+
+    public function isDead(): bool
+    {
+    }
+
+    public function setTypeMap(array $typemap): void
+    {
+    }
+}

stubs/Driver/CursorInterface.stub.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace MongoDB\Driver;
+
+use Iterator;
+use MongoDB\BSON\Int64;
+
+/**
+ * @template TValue of array|object
+ * @template-implements Iterator<int, TValue>
+ */
+interface CursorInterface extends Iterator
+{
+    /**
+     * @return TValue|null
+     * @psalm-ignore-nullable-return
+     */
+    public function current(): array|object|null;
+
+    public function getId(): Int64;
+
+    public function getServer(): Server;
+
+    public function isDead(): bool;
+
+    /** @psalm-ignore-nullable-return */
+    public function key(): ?int;
+
+    public function setTypeMap(array $typemap): void;
+
+    /** @return array<TValue> */
+    public function toArray(): array;
+}