Skip to content

Commit 383e1ab

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 64ad932 commit 383e1ab

8 files changed

+273
-0
lines changed

‎source/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+
...

‎source/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+
...

‎source/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+
...

‎source/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+
...

‎source/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

‎source/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

‎source/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

‎source/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

0 commit comments

Comments
 (0)