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

[tanlisu]

https://jira.mongodb.org/browse/PHPLIB-518

[jmikola]

A few suggestions:

• $fromNamespace can be $collectionName. Since we already have the context of a database, it makes sense that only the collection name would be dynamic. Omitting a "from" prefix will allow us to re-use the same include as dropCollection()'s docs.
• $toNamespace can be $toCollectionNameOrNamespace. I'd propose we accept either as a convenience. If the argument doesn't include a dot, we can prefix the value with the current database name and a dot before passing it along to the RenameCollection operation. Docs for this param can be the same as the Collection::rename() suggestion I shared above.

This handles the general use case where someone may want to rename collections within the same database.

[tanlisu]

@jmikola I don't think it works to determine whether a collection name or namespace is being provided by checking whether the argument contains a dot, since the collection names used in the tests contain a dot as well. So I'm not sure how it would be possible to do this actually - any ideas?

[jmikola]

Very good point. This would work the other way around (e.g. $databaseNameOrNamespace) because database names cannot contain dots; however, it's ambiguous if we're trying to differentiate a namespace from a collection name.

In that case, I think it makes sense to leave $toNamespace as-is.

$fromNamespace can still be changed to $collectionName for consistency with Database::dropCollection(), and the helper method can build the namespace to send to the Operation internally.

[jmikola]

To add on to this, let's change the API of both the helpers and Operation class to no longer take namespace strings as paramaters:

$database->renameCollection($collectionName, $toDatabaseName, $toCollectionName);
$collection->rename($toDatabaseName, $toCollectionName);

The Operation class will then have four required parameters:

• fromDatabaseName
• fromCollectionName
• toDatabaseName
• toCollectionName

It can then build the namespace internally with string concatenation in the constructor (allowing you to keep the internal private properties that store namespaces).

For the Database helper, fromDatabaseName would be pulled from the database instance's own name. And for the Collection helper, both "from" parameters would be pulled from the collection instance.

[jmikola]

Reviewed the code files but skipped the docs on this round. I'll come back to those on Friday and do a local build to check for any RST errors.

[jmikola]

Built the documentation locally and didn't see any syntax errors. Left one suggestion to reword, and then some other suggestions for outstanding comments on code docs.

[jmikola]

Tests appear to be passing, which confirms that the earlier issue was unrelated.

LGTM after a few doc block suggestions.

[jmikola]

When squashing and merging this, I'd suggest the following description.

PHPLIB-518: RenameCollection operation

Adds Database::renameCollection() and Collection::rename() methods.

Move assertCollectionDoesNotExist() and assertCollectionExists() to FunctionalTestCase

Most of the other commit messages shouldn't be relevant, and this summarizes the actual changes we might want to look back on down the line. You can also rename the PR itself to "PHPLIB-518: RenameCollection operation", which should suggest that title when squashing.