PHPLIB-518: Provide MongoDB\Collection::rename() method to rename a collection

docs/includes/apiargs-MongoDBCollection-method-rename-option.yaml

@@ -0,0 +1,27 @@
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: typeMap
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: session
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+---
+arg_name: option
+name: dropTarget
+type: boolean
+description: |
+  If ``true``, MongoDB will drop the target before renaming the collection. The
+  default value is ``false``.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-MongoDBCollection-method-rename-param.yaml

@@ -0,0 +1,25 @@
+arg_name: param
+name: $toCollectionName
+type: string
+description: |
+  The new name of the collection.
+interface: phpmethod
+operation: ~
+optional: false
+---
+arg_name: param
+name: $toDatabaseName
+type: string
+description: |
+  The new database name of the collection. If a new database name is not
+  specified, the database of the original collection will be used. If the new
+  name specifies a different database, the command copies the collection
+  to the new database and drops the source collection.
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/includes/apiargs-MongoDBDatabase-method-renameCollection-option.yaml

@@ -0,0 +1,27 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: session
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: typeMap
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: writeConcern
+post: |
+  This is not supported for server versions prior to 3.4 and will result in an
+  exception at execution time if used.
+---
+arg_name: option
+name: dropTarget
+type: boolean
+description: |
+  If ``true``, MongoDB will drop the target before renaming the collection. The
+  default value is ``false``.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-MongoDBDatabase-method-renameCollection-param.yaml

@@ -0,0 +1,34 @@
+arg_name: param
+name: $fromCollectionName
+type: string
+description: |
+  The name of the collection to rename.
+interface: phpmethod
+operation: ~
+optional: false
+---
+arg_name: param
+name: $toCollectionName
+type: string
+description: |
+  The new name of the collection.
+interface: phpmethod
+operation: ~
+optional: false
+---
+arg_name: param
+name: $toDatabaseName
+type: string
+description: |
+  The new database name of the collection. If a new database name is not
+  specified, the current database will be used. If the new name specifies a
+  different database, the command copies the collection to the new database
+  and drops the source collection.
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/reference/class/MongoDBCollection.txt

@@ -91,6 +91,7 @@ Methods
    /reference/method/MongoDBCollection-insertOne
    /reference/method/MongoDBCollection-listIndexes
    /reference/method/MongoDBCollection-mapReduce
+   /reference/method/MongoDBCollection-rename
    /reference/method/MongoDBCollection-replaceOne
    /reference/method/MongoDBCollection-updateMany
    /reference/method/MongoDBCollection-updateOne

docs/reference/class/MongoDBDatabase.txt

@@ -59,6 +59,7 @@ Methods
    /reference/method/MongoDBDatabase-listCollectionNames
    /reference/method/MongoDBDatabase-listCollections
    /reference/method/MongoDBDatabase-modifyCollection
+   /reference/method/MongoDBDatabase-renameCollection
    /reference/method/MongoDBDatabase-selectCollection
    /reference/method/MongoDBDatabase-selectGridFSBucket
    /reference/method/MongoDBDatabase-watch

docs/reference/method/MongoDBCollection-rename.txt

@@ -0,0 +1,79 @@
+=============================
+MongoDB\\Collection::rename()
+=============================
+
+.. versionadded:: 1.10
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Collection::rename()
+
+   Rename the collection.
+
+   .. code-block:: php
+
+      function rename(string $toCollectionName, ?string $toDatabaseName = null, array $options = []): array|object
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-rename-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-rename-option.rst
+
+Return Values
+-------------
+
+An array or object with the result document of the :manual:`renameCollection
+</reference/command/renameCollection>` command. The return type will depend on the
+``typeMap`` option.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Example
+-------
+
+The following operation renames the ``restaurants`` collection in the ``test``
+database to ``places``:
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->restaurants;
+
+   $result = $collection->rename('places');
+
+   var_dump($result);
+
+The output would then resemble::
+
+   object(MongoDB\Model\BSONDocument)#9 (1) {
+     ["storage":"ArrayObject":private]=>
+     array(1) {
+       ["ok"]=>
+       float(1)
+     }
+   }
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Database::renameCollection()`
+- :manual:`renameCollection </reference/command/renameCollection>` command reference in the MongoDB
+  manual

docs/reference/method/MongoDBDatabase-renameCollection.txt

@@ -0,0 +1,79 @@
+=====================================
+MongoDB\\Database::renameCollection()
+=====================================
+
+.. versionadded:: 1.10
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Database::renameCollection()
+
+   Rename a collection within the current database.
+
+   .. code-block:: php
+
+      function renameCollection(string $fromCollectionName, string $toCollectionName, ?string $toDatabaseName = null, array $options = []): array|object
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-renameCollection-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-renameCollection-option.rst
+
+Return Values
+-------------
+
+An array or object with the result document of the :manual:`renameCollection
+</reference/command/renameCollection>` command. The return type will depend on the
+``typeMap`` option.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Example
+-------
+
+The following example renames the ``restaurants`` collection in the ``test``
+database to ``places``:
+
+.. code-block:: php
+
+   <?php
+
+   $db = (new MongoDB\Client)->test;
+
+   $result = $db->renameCollection('restaurants', 'places');
+
+   var_dump($result);
+
+The output would then resemble::
+
+   object(MongoDB\Model\BSONDocument)#8 (1) {
+     ["storage":"ArrayObject":private]=>
+     array(1) {
+       ["ok"]=>
+       float(1)
+     }
+   }
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::rename()`
+- :manual:`renameCollection </reference/command/renameCollection>` command reference in the MongoDB
+  manual

src/Collection.php

@@ -53,6 +53,7 @@
 use MongoDB\Operation\InsertOne;
 use MongoDB\Operation\ListIndexes;
 use MongoDB\Operation\MapReduce;
+use MongoDB\Operation\RenameCollection;
 use MongoDB\Operation\ReplaceOne;
 use MongoDB\Operation\UpdateMany;
 use MongoDB\Operation\UpdateOne;
@@ -1004,6 +1005,39 @@ public function mapReduce(JavascriptInterface $map, JavascriptInterface $reduce,
         return $operation->execute($server);
     }
 
+    /**
+     * Renames the collection.
+     *
+     * @see RenameCollection::__construct() for supported options
+     * @param string  $toCollectionName New name of the collection
+     * @param ?string $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 = [])
+    {
+        if (! isset($toDatabaseName)) {
+            $toDatabaseName = $this->databaseName;
+        }
+
+        if (! isset($options['typeMap'])) {
+            $options['typeMap'] = $this->typeMap;
+        }
+
+        $server = select_server($this->manager, $options);
+
+        if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
+            $options['writeConcern'] = $this->writeConcern;
+        }
+
+        $operation = new RenameCollection($this->databaseName, $this->collectionName, $toDatabaseName, $toCollectionName, $options);
+
+        return $operation->execute($server);
+    }
+
     /**
      * Replaces at most one document matching the filter.
      *

src/Database.php

@@ -39,6 +39,7 @@
 use MongoDB\Operation\ListCollectionNames;
 use MongoDB\Operation\ListCollections;
 use MongoDB\Operation\ModifyCollection;
+use MongoDB\Operation\RenameCollection;
 use MongoDB\Operation\Watch;
 use Traversable;
 
@@ -470,6 +471,40 @@ public function modifyCollection($collectionName, array $collectionOptions, arra
         return $operation->execute($server);
     }
 
+    /**
+     * Rename a collection within this database.
+     *
+     * @see RenameCollection::__construct() for supported options
+     * @param string  $fromCollectionName Collection name
+     * @param string  $toCollectionName   New name of the collection
+     * @param ?string $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 unsupported on the selected server
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
+     */
+    public function renameCollection(string $fromCollectionName, string $toCollectionName, ?string $toDatabaseName = null, array $options = [])
+    {
+        if (! isset($toDatabaseName)) {
+            $toDatabaseName = $this->databaseName;
+        }
+
+        if (! isset($options['typeMap'])) {
+            $options['typeMap'] = $this->typeMap;
+        }
+
+        $server = select_server($this->manager, $options);
+
+        if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
+            $options['writeConcern'] = $this->writeConcern;
+        }
+
+        $operation = new RenameCollection($this->databaseName, $fromCollectionName, $toDatabaseName, $toCollectionName, $options);
+
+        return $operation->execute($server);
+    }
+
     /**
      * Select a collection within this database.
      *