PHPC-2412: Deprecate CursorId class

Author: alcaeus

php_phongo.c

@@ -253,8 +253,8 @@ PHP_MINIT_FUNCTION(mongodb) /* {{{ */
 	php_phongo_bulkwrite_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_clientencryption_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_command_init_ce(INIT_FUNC_ARGS_PASSTHRU);
-	php_phongo_cursor_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_cursorid_init_ce(INIT_FUNC_ARGS_PASSTHRU);
+	php_phongo_cursor_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_manager_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_query_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_readconcern_init_ce(INIT_FUNC_ARGS_PASSTHRU);

src/MongoDB/Cursor.c

@@ -143,12 +143,22 @@ static PHP_METHOD(MongoDB_Driver_Cursor, toArray)
 static PHP_METHOD(MongoDB_Driver_Cursor, getId)
 {
 	php_phongo_cursor_t* intern;
+	bool                 asInt64;
 
 	intern = Z_CURSOR_OBJ_P(getThis());
 
-	PHONGO_PARSE_PARAMETERS_NONE();
+	PHONGO_PARSE_PARAMETERS_START(0, 1)
+	Z_PARAM_OPTIONAL
+	Z_PARAM_BOOL(asInt64)
+	PHONGO_PARSE_PARAMETERS_END();
 
-	php_phongo_cursor_id_new_from_id(return_value, mongoc_cursor_get_id(intern->cursor));
+	if (asInt64) {
+		phongo_int64_new(return_value, mongoc_cursor_get_id(intern->cursor));
+	} else {
+		php_error_docref(NULL, E_DEPRECATED, "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.");
+
+		php_phongo_cursor_id_new_from_id(return_value, mongoc_cursor_get_id(intern->cursor));
+	}
 }
 
 /* Returns the Server object to which this cursor is attached */

src/MongoDB/Cursor.stub.php

@@ -18,7 +18,13 @@ public function current(): array|object|null {}
     public function current() {}
 #endif
 
-    final public function getId(): CursorId {}
+#if PHP_VERSION_ID >= 80000
+    /** @tentative-return-type */
+    final public function getId(bool $asInt64 = false): CursorId|\MongoDB\BSON\Int64 {}
+#else
+    /** @return CursorId|\MongoDB\BSON\Int64 */
+    final public function getId(bool $asInt64 = false) {}
+#endif
 
     final public function getServer(): Server {}
 

src/MongoDB/CursorId.stub.php

@@ -7,6 +7,7 @@
 
 namespace MongoDB\Driver;
 
+/** @deprecated deprecated without replacement */
 final class CursorId implements \Serializable
 {
     final private function __construct() {}

src/MongoDB/CursorId_arginfo.h

@@ -9,8 +9,13 @@
 
 interface CursorInterface extends \Traversable
 {
+#if PHP_VERSION_ID >= 80000
     /** @tentative-return-type */
-    public function getId(): CursorId;
+    public function getId(): CursorId|\MongoDB\BSON\Int64;
+#else
+    /** @return CursorId|\MongoDB\BSON\Int64 */
+    public function getId();
+#endif
 
     /** @tentative-return-type */
     public function getServer(): Server;

src/MongoDB/CursorInterface.stub.php

@@ -26,7 +26,7 @@ $iterator = new IteratorIterator($cursor);
 $iterator->rewind();
 $iterator->next();
 
-printf("Cursor ID is zero: %s\n", (string) $cursor->getId() === '0' ? 'yes' : 'no');
+printf("Cursor ID is zero: %s\n", (int) $cursor->getId(true) === 0 ? 'yes' : 'no');
 var_dump($cursor);
 
 $iterator->next();
@@ -35,7 +35,7 @@ $iterator->next();
  * is exhausted. While this is primarily done to ensure implicit sessions for
  * command cursors are returned to the pool ASAP, it also applies to explicit
  * sessions. */
-printf("\nCursor ID is zero: %s\n", (string) $cursor->getId() === '0' ? 'yes' : 'no');
+printf("\nCursor ID is zero: %s\n", (int) $cursor->getId(true) === 0 ? 'yes' : 'no');
 var_dump($cursor);
 
 ?>

src/MongoDB/CursorInterface_arginfo.h

@@ -28,12 +28,12 @@ $iterator->next();
 /* Implicit sessions for query cursors are never exposed to PHPC, as they are
  * handled internally by libmongoc. Cursor debug ouput should never report such
  * sessions. */
-printf("Cursor ID is zero: %s\n", (string) $cursor->getId() === '0' ? 'yes' : 'no');
+printf("Cursor ID is zero: %s\n", (int) $cursor->getId(true) === 0 ? 'yes' : 'no');
 var_dump($cursor);
 
 $iterator->next();
 
-printf("\nCursor ID is zero: %s\n", (string) $cursor->getId() === '0' ? 'yes' : 'no');
+printf("\nCursor ID is zero: %s\n", (int) $cursor->getId(true) === 0 ? 'yes' : 'no');
 var_dump($cursor);
 
 ?>