PHPLIB-1227 Use void return type for operations without meaningful re…

…sult document
mongodb · Sep 30, 2024 · 260c266 · 260c266
1 parent 3d46eaf
commit 260c266
Show file tree

Hide file tree

Showing 30 changed files with 129 additions and 322 deletions.
diff --git a/UPGRADE-2.0.md b/UPGRADE-2.0.md
@@ -23,6 +23,19 @@ UPGRADE FROM 1.x to 2.0
    * `MongoDB\Model\IndexInfoIteratorIterator`
    * `MongoDB\Operation\Executable`
 
+Operations with no result
+-------------------------
+
+The following operations no longer return the raw command result. The return
+type changed to `void`. In case of an error, an exception is thrown.
+
+ * `MongoDB\Client`: `dropDatabase`
+ * `MongoDB\Collection`: `drop`, `dropIndex`, `dropIndexes`, `dropSearchIndex`, `rename`
+ * `MongoDB\Database`: `createCollection`, `drop`, `dropCollection`, `modifyCollection`, `renameCollection`
+ * `MongoDB\Database::createEncryptedCollection()` returns the list of encrypted fields
+
+If you still need to access the raw command result, you can use a `CommandSubscriber`.
+
 GridFS
 ------
 

diff --git a/psalm-baseline.xml b/psalm-baseline.xml
@@ -519,9 +519,6 @@
     </MixedMethodCall>
   </file>
   <file src="src/Operation/CreateCollection.php">
-    <MixedArgument>
-      <code><![CDATA[$this->options['typeMap']]]></code>
-    </MixedArgument>
     <MixedAssignment>
       <code><![CDATA[$cmd[$option]]]></code>
       <code><![CDATA[$options['session']]]></code>
@@ -593,9 +590,6 @@
     </MixedMethodCall>
   </file>
   <file src="src/Operation/DropCollection.php">
-    <MixedArgument>
-      <code><![CDATA[$this->options['typeMap']]]></code>
-    </MixedArgument>
     <MixedAssignment>
       <code><![CDATA[$cmd['comment']]]></code>
       <code><![CDATA[$options['session']]]></code>
@@ -606,9 +600,6 @@
     </MixedMethodCall>
   </file>
   <file src="src/Operation/DropDatabase.php">
-    <MixedArgument>
-      <code><![CDATA[$this->options['typeMap']]]></code>
-    </MixedArgument>
     <MixedAssignment>
       <code><![CDATA[$cmd['comment']]]></code>
       <code><![CDATA[$options['session']]]></code>
@@ -621,9 +612,6 @@
     </MixedArgument>
   </file>
   <file src="src/Operation/DropIndexes.php">
-    <MixedArgument>
-      <code><![CDATA[$this->options['typeMap']]]></code>
-    </MixedArgument>
     <MixedAssignment>
       <code><![CDATA[$cmd[$option]]]></code>
       <code><![CDATA[$options['session']]]></code>
@@ -745,19 +733,13 @@
     </MixedAssignment>
   </file>
   <file src="src/Operation/ModifyCollection.php">
-    <MixedArgument>
-      <code><![CDATA[$this->options['typeMap']]]></code>
-    </MixedArgument>
     <MixedAssignment>
       <code><![CDATA[$cmd['comment']]]></code>
       <code><![CDATA[$options['session']]]></code>
       <code><![CDATA[$options['writeConcern']]]></code>
     </MixedAssignment>
   </file>
   <file src="src/Operation/RenameCollection.php">
-    <MixedArgument>
-      <code><![CDATA[$this->options['typeMap']]]></code>
-    </MixedArgument>
     <MixedAssignment>
       <code><![CDATA[$cmd[$option]]]></code>
       <code><![CDATA[$options['session']]]></code>

diff --git a/src/Client.php b/src/Client.php
@@ -49,10 +49,6 @@
 use function array_diff_key;
 use function is_array;
 use function is_string;
-use function sprintf;
-use function trigger_error;
-
-use const E_USER_DEPRECATED;
 
 class Client
 {
@@ -217,19 +213,12 @@ public function createClientEncryption(array $options): ClientEncryption
      * @see DropDatabase::__construct() for supported options
      * @param string $databaseName Database name
      * @param array  $options      Additional options
-     * @return array|object Command result document
      * @throws UnsupportedException if options are unsupported on the selected server
      * @throws InvalidArgumentException for parameter/option parsing errors
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
-    public function dropDatabase(string $databaseName, array $options = []): array|object
+    public function dropDatabase(string $databaseName, array $options = []): void
     {
-        if (! isset($options['typeMap'])) {
-            $options['typeMap'] = $this->typeMap;
-        } else {
-            @trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', __FUNCTION__), E_USER_DEPRECATED);
-        }
-
         $server = select_server_for_write($this->manager, $options);
 
         if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
@@ -238,7 +227,7 @@ public function dropDatabase(string $databaseName, array $options = []): array|o
 
         $operation = new DropDatabase($databaseName, $options);
 
-        return $operation->execute($server);
+        $operation->execute($server);
     }
 
     /**

diff --git a/src/Collection.php b/src/Collection.php
@@ -501,15 +501,13 @@ public function distinct(string $fieldName, array|object $filter = [], array $op
      *
      * @see DropCollection::__construct() for supported options
      * @param array $options Additional options
-     * @return array|object Command result document
      * @throws UnsupportedException if options are not supported by the selected server
      * @throws InvalidArgumentException for parameter/option parsing errors
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
-    public function drop(array $options = []): array|object
+    public function drop(array $options = []): void
     {
         $options = $this->inheritWriteOptions($options);
-        $options = $this->inheritTypeMap($options, __FUNCTION__);
 
         $server = select_server_for_write($this->manager, $options);
 
@@ -522,7 +520,7 @@ public function drop(array $options = []): array|object
             ? new DropEncryptedCollection($this->databaseName, $this->collectionName, $options)
             : new DropCollection($this->databaseName, $this->collectionName, $options);
 
-        return $operation->execute($server);
+        $operation->execute($server);
     }
 
     /**
@@ -531,12 +529,11 @@ public function drop(array $options = []): array|object
      * @see DropIndexes::__construct() for supported options
      * @param string|IndexInfo $indexName Index name or model object
      * @param array            $options   Additional options
-     * @return array|object Command result document
      * @throws UnsupportedException if options are not supported by the selected server
      * @throws InvalidArgumentException for parameter/option parsing errors
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
-    public function dropIndex(string|IndexInfo $indexName, array $options = []): array|object
+    public function dropIndex(string|IndexInfo $indexName, array $options = []): void
     {
         $indexName = (string) $indexName;
 
@@ -545,31 +542,28 @@ public function dropIndex(string|IndexInfo $indexName, array $options = []): arr
         }
 
         $options = $this->inheritWriteOptions($options);
-        $options = $this->inheritTypeMap($options, __FUNCTION__);
 
         $operation = new DropIndexes($this->databaseName, $this->collectionName, $indexName, $options);
 
-        return $operation->execute(select_server_for_write($this->manager, $options));
+        $operation->execute(select_server_for_write($this->manager, $options));
     }
 
     /**
      * Drop all indexes in the collection.
      *
      * @see DropIndexes::__construct() for supported options
      * @param array $options Additional options
-     * @return array|object Command result document
      * @throws UnsupportedException if options are not supported by the selected server
      * @throws InvalidArgumentException for parameter/option parsing errors
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
-    public function dropIndexes(array $options = []): array|object
+    public function dropIndexes(array $options = []): void
     {
         $options = $this->inheritWriteOptions($options);
-        $options = $this->inheritTypeMap($options, __FUNCTION__);
 
         $operation = new DropIndexes($this->databaseName, $this->collectionName, '*', $options);
 
-        return $operation->execute(select_server_for_write($this->manager, $options));
+        $operation->execute(select_server_for_write($this->manager, $options));
     }
 
     /**
@@ -909,23 +903,21 @@ public function listSearchIndexes(array $options = []): Iterator
      * @param string      $toCollectionName New name of the collection
      * @param string|null $toDatabaseName   New database name of the collection. Defaults to the original database.
      * @param array       $options          Additional options
-     * @return array|object Command result document
      * @throws UnsupportedException if options are not supported by the selected server
      * @throws InvalidArgumentException for parameter/option parsing errors
      * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
-    public function rename(string $toCollectionName, ?string $toDatabaseName = null, array $options = []): array|object
+    public function rename(string $toCollectionName, ?string $toDatabaseName = null, array $options = []): void
     {
         if (! isset($toDatabaseName)) {
             $toDatabaseName = $this->databaseName;
         }
 
         $options = $this->inheritWriteOptions($options);
-        $options = $this->inheritTypeMap($options);
 
         $operation = new RenameCollection($this->databaseName, $this->collectionName, $toDatabaseName, $toCollectionName, $options);
 
-        return $operation->execute(select_server_for_write($this->manager, $options));
+        $operation->execute(select_server_for_write($this->manager, $options));
     }
 
     /**
@@ -1127,12 +1119,8 @@ private function inheritReadPreference(array $options): array
         return $options;
     }
 
-    private function inheritTypeMap(array $options, ?string $deprecatedFunction = null): array
+    private function inheritTypeMap(array $options): array
     {
-        if ($deprecatedFunction !== null && isset($options['typeMap'])) {
-            @trigger_error(sprintf('The function %s() will return nothing in mongodb/mongodb v2.0, the "typeMap" option is deprecated', $deprecatedFunction), E_USER_DEPRECATED);
-        }
-
         // Only inherit the type map if no codec is used
         if (! isset($options['typeMap']) && ! isset($options['codec'])) {
             $options['typeMap'] = $this->typeMap;