Skip to content

Commit 722679f

Browse files
tanlisutanlisu
authored
PHPLIB-518: RenameCollection operation (#840)
* PHPLIB-518: RenameCollection operation * Adds Database::renameCollection() and Collection::rename() methods. * Move assertCollectionDoesNotExist() and assertCollectionExists() to FunctionalTestCase
1 parent 105e728 commit 722679f

19 files changed

+897
-90
lines changed

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
source:
2+
file: apiargs-MongoDBCollection-common-option.yaml
3+
ref: typeMap
4+
post: |
5+
This will be used for the returned command result document.
6+
---
7+
source:
8+
file: apiargs-common-option.yaml
9+
ref: session
10+
---
11+
source:
12+
file: apiargs-MongoDBCollection-common-option.yaml
13+
ref: writeConcern
14+
post: |
15+
This is not supported for server versions prior to 3.4 and will result in an
16+
exception at execution time if used.
17+
---
18+
arg_name: option
19+
name: dropTarget
20+
type: boolean
21+
description: |
22+
If ``true``, MongoDB will drop the target before renaming the collection. The
23+
default value is ``false``.
24+
interface: phpmethod
25+
operation: ~
26+
optional: true
27+
...

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
arg_name: param
2+
name: $toCollectionName
3+
type: string
4+
description: |
5+
The new name of the collection.
6+
interface: phpmethod
7+
operation: ~
8+
optional: false
9+
---
10+
arg_name: param
11+
name: $toDatabaseName
12+
type: string
13+
description: |
14+
The new database name of the collection. If a new database name is not
15+
specified, the database of the original collection will be used. If the new
16+
name specifies a different database, the command copies the collection
17+
to the new database and drops the source collection.
18+
interface: phpmethod
19+
operation: ~
20+
optional: true
21+
---
22+
source:
23+
file: apiargs-common-param.yaml
24+
ref: $options
25+
...

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
source:
2+
file: apiargs-common-option.yaml
3+
ref: session
4+
---
5+
source:
6+
file: apiargs-MongoDBDatabase-common-option.yaml
7+
ref: typeMap
8+
post: |
9+
This will be used for the returned command result document.
10+
---
11+
source:
12+
file: apiargs-MongoDBDatabase-common-option.yaml
13+
ref: writeConcern
14+
post: |
15+
This is not supported for server versions prior to 3.4 and will result in an
16+
exception at execution time if used.
17+
---
18+
arg_name: option
19+
name: dropTarget
20+
type: boolean
21+
description: |
22+
If ``true``, MongoDB will drop the target before renaming the collection. The
23+
default value is ``false``.
24+
interface: phpmethod
25+
operation: ~
26+
optional: true
27+
...

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
arg_name: param
2+
name: $fromCollectionName
3+
type: string
4+
description: |
5+
The name of the collection to rename.
6+
interface: phpmethod
7+
operation: ~
8+
optional: false
9+
---
10+
arg_name: param
11+
name: $toCollectionName
12+
type: string
13+
description: |
14+
The new name of the collection.
15+
interface: phpmethod
16+
operation: ~
17+
optional: false
18+
---
19+
arg_name: param
20+
name: $toDatabaseName
21+
type: string
22+
description: |
23+
The new database name of the collection. If a new database name is not
24+
specified, the current database will be used. If the new name specifies a
25+
different database, the command copies the collection to the new database
26+
and drops the source collection.
27+
interface: phpmethod
28+
operation: ~
29+
optional: true
30+
---
31+
source:
32+
file: apiargs-common-param.yaml
33+
ref: $options
34+
...

‎docs/reference/class/MongoDBCollection.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ Methods
9191
/reference/method/MongoDBCollection-insertOne
9292
/reference/method/MongoDBCollection-listIndexes
9393
/reference/method/MongoDBCollection-mapReduce
94+
/reference/method/MongoDBCollection-rename
9495
/reference/method/MongoDBCollection-replaceOne
9596
/reference/method/MongoDBCollection-updateMany
9697
/reference/method/MongoDBCollection-updateOne

‎docs/reference/class/MongoDBDatabase.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ Methods
5959
/reference/method/MongoDBDatabase-listCollectionNames
6060
/reference/method/MongoDBDatabase-listCollections
6161
/reference/method/MongoDBDatabase-modifyCollection
62+
/reference/method/MongoDBDatabase-renameCollection
6263
/reference/method/MongoDBDatabase-selectCollection
6364
/reference/method/MongoDBDatabase-selectGridFSBucket
6465
/reference/method/MongoDBDatabase-watch

‎docs/reference/method/MongoDBCollection-rename.txt

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
=============================
2+
MongoDB\\Collection::rename()
3+
=============================
4+
5+
.. versionadded:: 1.10
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. phpmethod:: MongoDB\\Collection::rename()
19+
20+
Rename the collection.
21+
22+
.. code-block:: php
23+
24+
function rename(string $toCollectionName, ?string $toDatabaseName = null, array $options = []): array|object
25+
26+
This method has the following parameters:
27+
28+
.. include:: /includes/apiargs/MongoDBCollection-method-rename-param.rst
29+
30+
The ``$options`` parameter supports the following options:
31+
32+
.. include:: /includes/apiargs/MongoDBCollection-method-rename-option.rst
33+
34+
Return Values
35+
-------------
36+
37+
An array or object with the result document of the :manual:`renameCollection
38+
</reference/command/renameCollection>` command. The return type will depend on the
39+
``typeMap`` option.
40+
41+
Errors/Exceptions
42+
-----------------
43+
44+
.. include:: /includes/extracts/error-unsupportedexception.rst
45+
.. include:: /includes/extracts/error-invalidargumentexception.rst
46+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
47+
48+
Example
49+
-------
50+
51+
The following operation renames the ``restaurants`` collection in the ``test``
52+
database to ``places``:
53+
54+
.. code-block:: php
55+
56+
<?php
57+
58+
$collection = (new MongoDB\Client)->test->restaurants;
59+
60+
$result = $collection->rename('places');
61+
62+
var_dump($result);
63+
64+
The output would then resemble::
65+
66+
object(MongoDB\Model\BSONDocument)#9 (1) {
67+
["storage":"ArrayObject":private]=>
68+
array(1) {
69+
["ok"]=>
70+
float(1)
71+
}
72+
}
73+
74+
See Also
75+
--------
76+
77+
- :phpmethod:`MongoDB\\Database::renameCollection()`
78+
- :manual:`renameCollection </reference/command/renameCollection>` command reference in the MongoDB
79+
manual

‎docs/reference/method/MongoDBDatabase-renameCollection.txt

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
=====================================
2+
MongoDB\\Database::renameCollection()
3+
=====================================
4+
5+
.. versionadded:: 1.10
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. phpmethod:: MongoDB\\Database::renameCollection()
19+
20+
Rename a collection within the current database.
21+
22+
.. code-block:: php
23+
24+
function renameCollection(string $fromCollectionName, string $toCollectionName, ?string $toDatabaseName = null, array $options = []): array|object
25+
26+
This method has the following parameters:
27+
28+
.. include:: /includes/apiargs/MongoDBDatabase-method-renameCollection-param.rst
29+
30+
The ``$options`` parameter supports the following options:
31+
32+
.. include:: /includes/apiargs/MongoDBDatabase-method-renameCollection-option.rst
33+
34+
Return Values
35+
-------------
36+
37+
An array or object with the result document of the :manual:`renameCollection
38+
</reference/command/renameCollection>` command. The return type will depend on the
39+
``typeMap`` option.
40+
41+
Errors/Exceptions
42+
-----------------
43+
44+
.. include:: /includes/extracts/error-unsupportedexception.rst
45+
.. include:: /includes/extracts/error-invalidargumentexception.rst
46+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
47+
48+
Example
49+
-------
50+
51+
The following example renames the ``restaurants`` collection in the ``test``
52+
database to ``places``:
53+
54+
.. code-block:: php
55+
56+
<?php
57+
58+
$db = (new MongoDB\Client)->test;
59+
60+
$result = $db->renameCollection('restaurants', 'places');
61+
62+
var_dump($result);
63+
64+
The output would then resemble::
65+
66+
object(MongoDB\Model\BSONDocument)#8 (1) {
67+
["storage":"ArrayObject":private]=>
68+
array(1) {
69+
["ok"]=>
70+
float(1)
71+
}
72+
}
73+
74+
See Also
75+
--------
76+
77+
- :phpmethod:`MongoDB\\Collection::rename()`
78+
- :manual:`renameCollection </reference/command/renameCollection>` command reference in the MongoDB
79+
manual

‎src/Collection.php

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@
5353
use MongoDB\Operation\InsertOne;
5454
use MongoDB\Operation\ListIndexes;
5555
use MongoDB\Operation\MapReduce;
56+
use MongoDB\Operation\RenameCollection;
5657
use MongoDB\Operation\ReplaceOne;
5758
use MongoDB\Operation\UpdateMany;
5859
use MongoDB\Operation\UpdateOne;
@@ -1004,6 +1005,39 @@ public function mapReduce(JavascriptInterface $map, JavascriptInterface $reduce,
10041005
return $operation->execute($server);
10051006
}
10061007

1008+
/**
1009+
* Renames the collection.
1010+
*
1011+
* @see RenameCollection::__construct() for supported options
1012+
* @param string $toCollectionName New name of the collection
1013+
* @param ?string $toDatabaseName New database name of the collection. Defaults to the original database.
1014+
* @param array $options Additional options
1015+
* @return array|object Command result document
1016+
* @throws UnsupportedException if options are not supported by the selected server
1017+
* @throws InvalidArgumentException for parameter/option parsing errors
1018+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
1019+
*/
1020+
public function rename(string $toCollectionName, ?string $toDatabaseName = null, array $options = [])
1021+
{
1022+
if (! isset($toDatabaseName)) {
1023+
$toDatabaseName = $this->databaseName;
1024+
}
1025+
1026+
if (! isset($options['typeMap'])) {
1027+
$options['typeMap'] = $this->typeMap;
1028+
}
1029+
1030+
$server = select_server($this->manager, $options);
1031+
1032+
if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
1033+
$options['writeConcern'] = $this->writeConcern;
1034+
}
1035+
1036+
$operation = new RenameCollection($this->databaseName, $this->collectionName, $toDatabaseName, $toCollectionName, $options);
1037+
1038+
return $operation->execute($server);
1039+
}
1040+
10071041
/**
10081042
* Replaces at most one document matching the filter.
10091043
*

‎src/Database.php

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
use MongoDB\Operation\ListCollectionNames;
4040
use MongoDB\Operation\ListCollections;
4141
use MongoDB\Operation\ModifyCollection;
42+
use MongoDB\Operation\RenameCollection;
4243
use MongoDB\Operation\Watch;
4344
use Traversable;
4445

@@ -470,6 +471,40 @@ public function modifyCollection($collectionName, array $collectionOptions, arra
470471
return $operation->execute($server);
471472
}
472473

474+
/**
475+
* Rename a collection within this database.
476+
*
477+
* @see RenameCollection::__construct() for supported options
478+
* @param string $fromCollectionName Collection name
479+
* @param string $toCollectionName New name of the collection
480+
* @param ?string $toDatabaseName New database name of the collection. Defaults to the original database.
481+
* @param array $options Additional options
482+
* @return array|object Command result document
483+
* @throws UnsupportedException if options are unsupported on the selected server
484+
* @throws InvalidArgumentException for parameter/option parsing errors
485+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
486+
*/
487+
public function renameCollection(string $fromCollectionName, string $toCollectionName, ?string $toDatabaseName = null, array $options = [])
488+
{
489+
if (! isset($toDatabaseName)) {
490+
$toDatabaseName = $this->databaseName;
491+
}
492+
493+
if (! isset($options['typeMap'])) {
494+
$options['typeMap'] = $this->typeMap;
495+
}
496+
497+
$server = select_server($this->manager, $options);
498+
499+
if (! isset($options['writeConcern']) && server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern) && ! is_in_transaction($options)) {
500+
$options['writeConcern'] = $this->writeConcern;
501+
}
502+
503+
$operation = new RenameCollection($this->databaseName, $fromCollectionName, $toDatabaseName, $toCollectionName, $options);
504+
505+
return $operation->execute($server);
506+
}
507+
473508
/**
474509
* Select a collection within this database.
475510
*

0 commit comments

Comments
 (0)