diff --git a/source/includes/databases-collections/databases-collections.php b/source/includes/databases-collections/databases-collections.php index eb4dde74..70215575 100644 --- a/source/includes/databases-collections/databases-collections.php +++ b/source/includes/databases-collections/databases-collections.php @@ -30,7 +30,7 @@ // Explicitly creates the "example_collection" collection // start-create-collection -$result = $client->test_database->createCollection('example_collection'); +$client->test_database->createCollection('example_collection'); // end-create-collection // Lists the collections in the "test_database" database diff --git a/source/includes/databases-collections/time-series.php b/source/includes/databases-collections/time-series.php index 35b005e2..f12104eb 100644 --- a/source/includes/databases-collections/time-series.php +++ b/source/includes/databases-collections/time-series.php @@ -16,7 +16,7 @@ ] ]; -$collection = $db->createCollection('sept2023', $options); +$db->createCollection('sept2023', $options); // end-create-ts // Lists the collections in the "precipitation" database diff --git a/source/includes/read/cursor.php b/source/includes/read/cursor.php index 7ea0648a..aff1b4ec 100644 --- a/source/includes/read/cursor.php +++ b/source/includes/read/cursor.php @@ -32,7 +32,7 @@ // Creates a collection with a maximum size and inserts documents representing vegetables // start-capped-coll $db = $client->db; -$create_coll = $db->createCollection( +$db->createCollection( 'vegetables', ['capped' => true, 'size' => 1024 * 1024] ); diff --git a/source/indexes/index-mgmt.txt b/source/indexes/index-mgmt.txt index b56b8fa2..dcec8993 100644 --- a/source/indexes/index-mgmt.txt +++ b/source/indexes/index-mgmt.txt @@ -127,9 +127,6 @@ You can delete all indexes by calling the :end-before: end-remove-all-indexes :dedent: -The ``dropIndexes()`` method returns information about the number of -indexes removed and a success message. - API Documentation ~~~~~~~~~~~~~~~~~ diff --git a/source/reference/method/MongoDBClient-dropDatabase.txt b/source/reference/method/MongoDBClient-dropDatabase.txt index 9545ed49..dc01eebe 100644 --- a/source/reference/method/MongoDBClient-dropDatabase.txt +++ b/source/reference/method/MongoDBClient-dropDatabase.txt @@ -2,8 +2,6 @@ MongoDB\\Client::dropDatabase() =============================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -19,7 +17,7 @@ Definition .. code-block:: php - function dropDatabase(string $databaseName, array $options = []): array|object + function dropDatabase(string $databaseName, array $options = []): void Parameters ---------- @@ -62,13 +60,6 @@ Parameters - :php:`MongoDB\Driver\WriteConcern ` - .. include:: /includes/extracts/client-option-writeConcern.rst -Return Values -------------- - -An array or object with the result document of the :manual:`dropDatabase -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -87,23 +78,7 @@ The following example drops the ``test`` database: $client = new MongoDB\Client; - $result = $client->dropDatabase('test'); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#8 (1) { - ["storage":"ArrayObject":private]=> - array(2) { - ["dropped"]=> - string(4) "test" - ["ok"]=> - float(1) - } - } + $client->dropDatabase('test'); See Also -------- diff --git a/source/reference/method/MongoDBCollection-drop.txt b/source/reference/method/MongoDBCollection-drop.txt index e220e076..b335c2c3 100644 --- a/source/reference/method/MongoDBCollection-drop.txt +++ b/source/reference/method/MongoDBCollection-drop.txt @@ -19,7 +19,7 @@ Definition .. code-block:: php - function drop(array $options = []): array|object + function drop(array $options = []): void Parameters ---------- @@ -79,15 +79,6 @@ Parameters .. include:: /includes/extracts/common-option-writeConcern-transaction.rst - - -Return Values -------------- - -An array or object with the result document of the :manual:`drop -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -107,25 +98,7 @@ database: $collection = (new MongoDB\Client)->test->restaurants; - $result = $collection->drop(); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#9 (1) { - ["storage":"ArrayObject":private]=> - array(3) { - ["ns"]=> - string(16) "test.restaurants" - ["nIndexesWas"]=> - int(3) - ["ok"]=> - float(1) - } - } + $collection->drop(); See Also -------- diff --git a/source/reference/method/MongoDBCollection-dropIndex.txt b/source/reference/method/MongoDBCollection-dropIndex.txt index c8c6e643..c6546655 100644 --- a/source/reference/method/MongoDBCollection-dropIndex.txt +++ b/source/reference/method/MongoDBCollection-dropIndex.txt @@ -2,8 +2,6 @@ MongoDB\\Collection::dropIndex() ================================ -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -22,7 +20,7 @@ Definition function dropIndex( string|MongoDB\Model\IndexInfo $indexName, array $options = [] - ): array|object + ): void Parameters ---------- @@ -74,13 +72,6 @@ Parameters .. include:: /includes/extracts/common-option-writeConcern-transaction.rst -Return Values -------------- - -An array or object with the result document of the :manual:`dropIndexes -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -100,23 +91,7 @@ collection in the ``test`` database: $collection = (new MongoDB\Client)->test->restaurants; - $result = $collection->dropIndex('borough_1'); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#9 (1) { - ["storage":"ArrayObject":private]=> - array(2) { - ["nIndexesWas"]=> - int(2) - ["ok"]=> - float(1) - } - } + $collection->dropIndex('borough_1'); See Also -------- diff --git a/source/reference/method/MongoDBCollection-dropIndexes.txt b/source/reference/method/MongoDBCollection-dropIndexes.txt index fc7bc1c2..8e544d8b 100644 --- a/source/reference/method/MongoDBCollection-dropIndexes.txt +++ b/source/reference/method/MongoDBCollection-dropIndexes.txt @@ -2,8 +2,6 @@ MongoDB\\Collection::dropIndexes() ================================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -20,7 +18,7 @@ Definition .. code-block:: php - function dropIndexes(array $options = []): array|object + function dropIndexes(array $options = []): void Parameters ---------- @@ -72,13 +70,6 @@ Parameters .. include:: /includes/extracts/common-option-writeConcern-transaction.rst -Return Values -------------- - -An array or object with the result document of the :manual:`dropIndexes -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -98,25 +89,7 @@ The following drops all indexes from the ``restaurants`` collection in the $collection = (new MongoDB\Client)->test->restaurants; - $result = $collection->dropIndexes(); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#9 (1) { - ["storage":"ArrayObject":private]=> - array(3) { - ["nIndexesWas"]=> - int(3) - ["msg"]=> - string(38) "non-_id indexes dropped for collection" - ["ok"]=> - float(1) - } - } + $collection->dropIndexes(); See Also -------- diff --git a/source/reference/method/MongoDBCollection-dropSearchIndex.txt b/source/reference/method/MongoDBCollection-dropSearchIndex.txt index fb6be0e0..43066312 100644 --- a/source/reference/method/MongoDBCollection-dropSearchIndex.txt +++ b/source/reference/method/MongoDBCollection-dropSearchIndex.txt @@ -4,8 +4,6 @@ MongoDB\\Collection::dropSearchIndex() .. versionadded:: 1.17 -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-rename.txt b/source/reference/method/MongoDBCollection-rename.txt index 347c205b..eaec8950 100644 --- a/source/reference/method/MongoDBCollection-rename.txt +++ b/source/reference/method/MongoDBCollection-rename.txt @@ -4,8 +4,6 @@ MongoDB\\Collection::rename() .. versionadded:: 1.10 -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -25,7 +23,7 @@ Definition string $toCollectionName, ?string $toDatabaseName = null, array $options = [] - ): array|object + ): void Parameters ---------- @@ -79,13 +77,6 @@ Parameters .. include:: /includes/extracts/common-option-writeConcern-transaction.rst -Return Values -------------- - -An array or object with the result document of the :manual:`renameCollection -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -105,21 +96,7 @@ database to ``places``: $collection = (new MongoDB\Client)->test->restaurants; - $result = $collection->rename('places'); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#9 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } + $collection->rename('places'); See Also -------- diff --git a/source/reference/method/MongoDBDatabase-createCollection.txt b/source/reference/method/MongoDBDatabase-createCollection.txt index 4becce8e..ebc4b732 100644 --- a/source/reference/method/MongoDBDatabase-createCollection.txt +++ b/source/reference/method/MongoDBDatabase-createCollection.txt @@ -2,8 +2,6 @@ MongoDB\\Database::createCollection() ===================================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -22,7 +20,7 @@ Definition function createCollection( string $collectionName, array $options = [] - ): array|object + ): void MongoDB creates collections implicitly when you first reference the collection in a command, such as when inserting a document into a new @@ -313,12 +311,6 @@ Parameters - :php:`MongoDB\Driver\WriteConcern ` - .. include:: /includes/extracts/database-option-writeConcern.rst -Return Values -------------- - -An array or object with the result document of the :manual:`create -` command. - Errors/Exceptions ----------------- @@ -338,27 +330,13 @@ database with document validation criteria: $db = (new MongoDB\Client)->test; - $result = $db->createCollection('users', [ + $db->createCollection('users', [ 'validator' => [ 'username' => ['$type' => 'string'], 'email' => ['$regex' => '@mongodb\.com$'], ], ]); - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#11 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } - See Also -------- diff --git a/source/reference/method/MongoDBDatabase-createEncryptedCollection.txt b/source/reference/method/MongoDBDatabase-createEncryptedCollection.txt index e6a266fb..dab09dc6 100644 --- a/source/reference/method/MongoDBDatabase-createEncryptedCollection.txt +++ b/source/reference/method/MongoDBDatabase-createEncryptedCollection.txt @@ -4,8 +4,6 @@ MongoDB\\Database::createEncryptedCollection() .. versionadded:: 1.16 -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -71,10 +69,7 @@ Parameters Return Values ------------- -A tuple (i.e. two-element array) containing the result document from the -:manual:`create ` command (an array or object -according to the ``typeMap`` option) and the modified ``encryptedFields`` -option. +An array containing the modified ``encryptedFields`` option. Errors/Exceptions ----------------- @@ -109,7 +104,7 @@ an encrypted string field. ], ); - [$result, $encryptedFields] = $client->test->createEncryptedCollection( + $encryptedFields = $client->test->createEncryptedCollection( 'users', $clientEncryption, 'local', @@ -123,11 +118,10 @@ an encrypted string field. ] ); -If the encrypted collection was successfully created, ``$result`` will contain -the response document from the ``create`` command and -``$encryptedFields['fields'][0]['keyId']`` will contain a -:php:`MongoDB\BSON\Binary ` object with subtype 4 -(i.e. UUID). +If the encrypted collection is successfully created, +``$encryptedFields['fields'][0]['keyId']`` contains a +:php:`MongoDB\BSON\Binary ` object with +subtype 4 (i.e. UUID). The modified ``encryptedFields`` option can then be used to construct a new :phpclass:`MongoDB\Client` with auto encryption enabled. diff --git a/source/reference/method/MongoDBDatabase-drop.txt b/source/reference/method/MongoDBDatabase-drop.txt index da1c8ba0..18ece835 100644 --- a/source/reference/method/MongoDBDatabase-drop.txt +++ b/source/reference/method/MongoDBDatabase-drop.txt @@ -2,8 +2,6 @@ MongoDB\\Database::drop() ========================= -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -19,7 +17,7 @@ Definition .. code-block:: php - function drop(array $options = []): array|object + function drop(array $options = []): void Parameters ---------- @@ -59,13 +57,6 @@ Parameters - :php:`MongoDB\Driver\WriteConcern ` - .. include:: /includes/extracts/database-option-writeConcern.rst -Return Values -------------- - -An array or object with the result document of the :manual:`dropDatabase -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -84,23 +75,7 @@ The following example drops the ``test`` database: $db = (new MongoDB\Client)->test; - $result = $db->drop(); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#8 (1) { - ["storage":"ArrayObject":private]=> - array(2) { - ["dropped"]=> - string(4) "test" - ["ok"]=> - float(1) - } - } + $db->drop(); See Also -------- diff --git a/source/reference/method/MongoDBDatabase-dropCollection.txt b/source/reference/method/MongoDBDatabase-dropCollection.txt index 5ecc8def..5721509e 100644 --- a/source/reference/method/MongoDBDatabase-dropCollection.txt +++ b/source/reference/method/MongoDBDatabase-dropCollection.txt @@ -2,8 +2,6 @@ MongoDB\\Database::dropCollection() =================================== -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -22,7 +20,7 @@ Definition function dropCollection( string $collectionName, array $options = [] - ): array|object + ): void Parameters ---------- @@ -83,13 +81,6 @@ Parameters - :php:`MongoDB\Driver\WriteConcern ` - .. include:: /includes/extracts/database-option-writeConcern.rst -Return Values -------------- - -An array or object with the result document of the :manual:`drop -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -108,25 +99,7 @@ The following example drops the ``users`` collection in the ``test`` database: $db = (new MongoDB\Client)->test; - $result = $db->dropCollection('users'); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#8 (1) { - ["storage":"ArrayObject":private]=> - array(3) { - ["ns"]=> - string(10) "test.users" - ["nIndexesWas"]=> - int(1) - ["ok"]=> - float(1) - } - } + $db->dropCollection('users'); See Also -------- diff --git a/source/reference/method/MongoDBDatabase-renameCollection.txt b/source/reference/method/MongoDBDatabase-renameCollection.txt index 8c07952d..87e38532 100644 --- a/source/reference/method/MongoDBDatabase-renameCollection.txt +++ b/source/reference/method/MongoDBDatabase-renameCollection.txt @@ -4,8 +4,6 @@ MongoDB\\Database::renameCollection() .. versionadded:: 1.10 -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none @@ -26,7 +24,7 @@ Definition string $toCollectionName, ?string $toDatabaseName = null, array $options = [] - ): array|object + ): void Parameters ---------- @@ -81,13 +79,6 @@ Parameters - :php:`MongoDB\Driver\WriteConcern ` - .. include:: /includes/extracts/database-option-writeConcern.rst -Return Values -------------- - -An array or object with the result document of the :manual:`renameCollection -` command. The return type will depend on the -``typeMap`` option. - Errors/Exceptions ----------------- @@ -107,21 +98,7 @@ database to ``places``: $db = (new MongoDB\Client)->test; - $result = $db->renameCollection('restaurants', 'places'); - - var_dump($result); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#8 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } + $db->renameCollection('restaurants', 'places'); See Also -------- diff --git a/source/upgrade.txt b/source/upgrade.txt index 2ea4cedf..b9d5c7ff 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -20,9 +20,9 @@ Upgrade Library Versions Overview -------- -On this page, you can learn about the changes you must make to your application -when you upgrade to a new version of the {+php-library+}. This page also includes -how to upgrade your PHP extension to a new version. +In this guide, you can learn about the changes you must make to your application +when you upgrade to a new version of the {+php-library+}. This page also describes +how to upgrade your {+extension-short+} to a new version. How to Upgrade -------------- @@ -74,16 +74,43 @@ Detailed installation instructions may be found in the Breaking Changes ---------------- -A breaking change is a change of a convention or a behavior starting in a specific -version of the library. This type of change may prevent your application from working -properly if not addressed before upgrading the library. +A breaking change is a change of a convention or a behavior starting in +a specific version of the library. This type of change may prevent your +application from working properly if not addressed before upgrading the +library. -The breaking changes in this section are categorized by the library version that introduced -them. When upgrading library versions, address all the breaking changes between the current -and upgrade versions. +The breaking changes in this section are categorized by the library +version that introduced them. When upgrading library versions, address +all the breaking changes between the current and upgrade versions. -For more information on release changes, see the release notes and associated -JIRA tickets for each release on `GitHub `__. +For more information on release changes, see the release notes and +associated JIRA tickets for each release on `GitHub +`__. + +.. _php-v2-breaking-changes: + +Version 2.0 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This library version introduces the following breaking changes: + +- The following methods return ``void`` instead of the raw command + response: + + - ``MongoDB\\Client``: ``dropDatabase()`` + - ``MongoDB\\Collection``: ``drop()``, ``dropIndex()``, + ``dropIndexes()``, ``dropSearchIndex()``, ``rename()`` + - ``MongoDB\\Database``: ``createCollection()``, ``drop()``, + ``dropCollection()``, ``renameCollection()`` + + The ``MongoDB\\Database::createEncryptedCollection()`` method returns + the list of encrypted fields instead of the raw command response. + + If there is an error, the methods throw an exception. + + If you must access the raw command response from the preceding + methods, you can register a :php:`CommandSubscriber + ` in your application. Version 1.20 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/whats-new.txt b/source/whats-new.txt index 1cde7a39..8f0dce30 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -39,6 +39,24 @@ following versions of the {+php-library+}: What's New in 2.0 ----------------- +.. important:: Breaking Changes + + The {+library-short+} v2.0 release introduces the following breaking + changes: + + - The following methods return ``void`` instead of the raw command + response: + + - ``MongoDB\\Client``: ``dropDatabase()`` + - ``MongoDB\\Collection``: ``drop()``, ``dropIndex()``, + ``dropIndexes()``, ``dropSearchIndex()``, ``rename()`` + - ``MongoDB\\Database``: ``createCollection()``, ``drop()``, + ``dropCollection()``, ``renameCollection()`` + + To learn more about breaking changes in this release, see the + :ref:`Version 2.0 Breaking Changes ` section + in the Upgrade Library Versions guide. + The {+library-short+} v2.0 release includes the following features, improvements, and fixes: