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;
 }