PHPC-2140: Make tentative return types definitive (#1658)

* PHPC-2140: Make tentative return types definitive

* Change return type of manager and server methods to CursorInterface

* Define return types for key() and current() in CursorInterface

* Add upgrade note

Author: alcaeus

UPGRADE-2.0.md

@@ -9,3 +9,9 @@ UPGRADE FROM 1.x to 2.0
  * The constants `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` and
    `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW` have been 
    removed. Use the `ALGORITHM_RANGE` and `QUERY_TYPE_RANGE` instead.
+ * All tentative return types defined in interface and non-final classes are now
+   fixed and are required in implementing or extending classes.
+ * `MongoDB\Driver\CursorInterface` now extends `Iterator`, requiring 
+   implementing classes to also implement iterator methods. The return types for
+   the `key` and `current` methods have been narrowed to the types returned by
+   cursor instances.

src/BSON/BinaryInterface.stub.php

@@ -9,10 +9,8 @@
 
 interface BinaryInterface
 {
-    /** @tentative-return-type */
     public function getData(): string;
 
-    /** @tentative-return-type */
     public function getType(): int;
 
     public function __toString(): string;

src/BSON/BinaryInterface_arginfo.h

@@ -9,6 +9,5 @@
 
 interface Decimal128Interface
 {
-    /** @tentative-return-type */
     public function __toString(): string;
 }

src/BSON/Decimal128Interface.stub.php

@@ -9,12 +9,9 @@
 
 interface JavascriptInterface
 {
-    /** @tentative-return-type */
     public function getCode(): string;
 
-    /** @tentative-return-type */
     public function getScope(): ?object;
 
-    /** @tentative-return-type */
     public function __toString(): string;
 }

src/BSON/Decimal128Interface_arginfo.h

@@ -9,9 +9,7 @@
 
 interface ObjectIdInterface
 {
-    /** @tentative-return-type */
     public function getTimestamp(): int;
 
-    /** @tentative-return-type */
     public function __toString(): string;
 }

src/BSON/JavascriptInterface.stub.php

@@ -9,6 +9,5 @@
 
 interface Persistable extends Serializable, Unserializable
 {
-    /** @tentative-return-type */
     public function bsonSerialize(): array|\stdClass|Document;
 }

src/BSON/JavascriptInterface_arginfo.h

@@ -9,12 +9,9 @@
 
 interface RegexInterface
 {
-    /** @tentative-return-type */
     public function getPattern(): string;
 
-    /** @tentative-return-type */
     public function getFlags(): string;
 
-    /** @tentative-return-type */
     public function __toString(): string;
 }

src/BSON/ObjectIdInterface.stub.php

@@ -9,6 +9,5 @@
 
 interface Serializable extends Type
 {
-    /** @tentative-return-type */
     public function bsonSerialize(): array|\stdClass|Document|PackedArray;
 }

src/BSON/ObjectIdInterface_arginfo.h

@@ -9,12 +9,9 @@
 
 interface TimestampInterface
 {
-    /** @tentative-return-type */
     public function getTimestamp(): int;
 
-    /** @tentative-return-type */
     public function getIncrement(): int;
 
-    /** @tentative-return-type */
     public function __toString(): string;
 }

src/BSON/Persistable.stub.php

@@ -9,9 +9,7 @@
 
 interface UTCDateTimeInterface
 {
-    /** @tentative-return-type */
     public function toDateTime(): \DateTime;
 
-    /** @tentative-return-type */
     public function __toString(): string;
 }

src/BSON/Persistable_arginfo.h

@@ -9,6 +9,5 @@
 
 interface Unserializable
 {
-    /** @tentative-return-type */
     public function bsonUnserialize(array $data): void;
 }

src/BSON/RegexInterface.stub.php

@@ -14,7 +14,6 @@ final private function __construct() {}
 
     public function current(): array|object|null {}
 
-    /** @tentative-return-type */
     final public function getId(bool $asInt64 = false): CursorId|\MongoDB\BSON\Int64 {}
 
     final public function getServer(): Server {}

src/BSON/RegexInterface_arginfo.h

@@ -9,18 +9,17 @@
 
 interface CursorInterface extends \Iterator
 {
-    /** @tentative-return-type */
+    public function current(): array|object|null {}
+
     public function getId(): CursorId|\MongoDB\BSON\Int64;
 
-    /** @tentative-return-type */
     public function getServer(): Server;
 
-    /** @tentative-return-type */
     public function isDead(): bool;
 
-    /** @tentative-return-type */
+    public function key(): ?int;
+
     public function setTypeMap(array $typemap): void;
 
-    /** @tentative-return-type */
     public function toArray(): array;
 }

src/BSON/Serializable.stub.php

@@ -18,15 +18,15 @@ final public function createClientEncryption(array $options): ClientEncryption {
 
     final public function executeBulkWrite(string $namespace, BulkWrite $bulk, array|WriteConcern|null $options = null): WriteResult {}
 
-    final public function executeCommand(string $db, Command $command, array|ReadPreference|null $options = null): Cursor {}
+    final public function executeCommand(string $db, Command $command, array|ReadPreference|null $options = null): CursorInterface {}
 
-    final public function executeQuery(string $namespace, Query $query, array|ReadPreference|null $options = null): Cursor {}
+    final public function executeQuery(string $namespace, Query $query, array|ReadPreference|null $options = null): CursorInterface {}
 
-    final public function executeReadCommand(string $db, Command $command, ?array $options = null): Cursor {}
+    final public function executeReadCommand(string $db, Command $command, ?array $options = null): CursorInterface {}
 
-    final public function executeReadWriteCommand(string $db, Command $command, ?array $options = null): Cursor {}
+    final public function executeReadWriteCommand(string $db, Command $command, ?array $options = null): CursorInterface {}
 
-    final public function executeWriteCommand(string $db, Command $command, ?array $options = null): Cursor {}
+    final public function executeWriteCommand(string $db, Command $command, ?array $options = null): CursorInterface {}
 
     final public function getEncryptedFieldsMap(): array|object|null {}
 

src/BSON/Serializable_arginfo.h

@@ -9,12 +9,9 @@
 
 interface CommandSubscriber extends Subscriber
 {
-    /** @tentative-return-type */
     public function commandStarted(CommandStartedEvent $event): void;
 
-    /** @tentative-return-type */
     public function commandSucceeded(CommandSucceededEvent $event): void;
 
-    /** @tentative-return-type */
     public function commandFailed(CommandFailedEvent $event): void;
 }