DOCSP-50294: V2.1 Release (#256)

* DOCSP-44581: v2 release (#234)

* DOCSP-44581: v2 release

* small fix

* Add missing meta descriptions (#235)

* Add missing meta descriptions

* Apply suggestions from code review

---------

Co-authored-by: Rachel Mackintosh <[email protected]>

* DOCSP-48761: docker note (#237)

* DOCSP-48100: Consolidate minor versions (#240)

* DOCSP-48100: Consolidate minor versions

* edits

* remove old redirects

* AB feedback

* edit

* DOCSP-48718-update-credentials (#247)

* update username and password

* misspelling

* redirects

* pre-standardization redirects

* upgrade composer package vs

* DOCSP-49150: bulkWrite docs + api (#250)

* DOCSP-49150: bulkWrite docs + api

* first pass fixes

* JT PR fixes 1

* upgrade composer package vs

* JT PR fixes 2

* small fix

* JT PR fixes 3

* remove reference to writeconcern option

* add return values sections

* object -> instance

* NR PR fixes 1

* returns -> throws

* DOCSP-50022: remove eol server version mentions (#253)

* DOCSP-50022: remove eol server version mentions

* consolidate compat table rows

* DOCSP-50155 - EOL MongoDB 4.0 (#252)

* eol v4.0

* update compat

* DOCSP-50294: v2.1 release (#255)

---------

Co-authored-by: Nick Larew <[email protected]>
Co-authored-by: Rachel Mackintosh <[email protected]>
Co-authored-by: Nora Reidy <[email protected]>
Co-authored-by: shuangela <[email protected]>
Co-authored-by: Mike Woofter <[email protected]>

Author: 6 people

composer/composer.json

@@ -2,8 +2,8 @@
   "name": "mongodb/docs-php-library",
   "description": "MongoDB PHP Library Documentation",
   "require": {
-    "ext-mongodb": "^1.20",
-    "mongodb/mongodb": "^1.20"
+    "ext-mongodb": "^2.1",
+    "mongodb/mongodb": "^2.1"
   },
   "require-dev": {
     "doctrine/coding-standard": "^12.0",

config/redirects

@@ -1,23 +1,29 @@
-define: base https://www.mongodb.com/docs/php-library
 define: prefix docs/php-library
-raw: ${prefix}/ -> ${base}/current
-define: versions v1.16 v1.17 v1.18 v1.19 v1.20 v1.21 v2.0 master
+define: base https://www.mongodb.com/${prefix}
+define: versions v1.16 v1.17 v1.18 v1.19 v1.20 v1.21 v1.x v2.0 v2.x master
 
 symlink: upcoming -> master
-symlink: current -> v2.0
+symlink: current -> v2.x
+
+raw: ${prefix}/ -> ${base}/current/
+raw: ${prefix}/stable -> ${base}/current/
+
+# consolidation redirects
+[*-v1.21]: ${prefix}/${version}/ -> ${base}/v1.x/
+[v2.0]: ${prefix}/${version}/ -> ${base}/v2.x/
 
 # general redirects
-[v1.17-v1.19]: ${prefix}/${version}/tutorial/client-side-encryption/ -> ${base}/${version}/tutorial/encryption/
-[v1.16]: ${prefix}/${version}/tutorial/encryption/ -> ${base}/${version}/
-[v1.20-*]: ${prefix}/${version}/get-started/connect-to-mongodb -> ${base}/${version}/get-started/run-sample-query/
+[v1.17-v1.19]: ${prefix}/${version}/tutorial/client-side-encryption/ -> ${base}/${version}/security/in-use-encryption/
+[v1.16]: ${prefix}/${version}/tutorial/encryption/ -> ${base}/${version}/security/in-use-encryption/
+[v1.20-*]: ${prefix}/${version}/get-started/connect-to-mongodb -> ${base}/${version}/get-started/#run-a-sample-query/
 [*-v1.20]: ${prefix}/${version}/aggregation/atlas-search -> ${base}/${version}/aggregation/
 [*-v1.20]: ${prefix}/${version}/aggregation/vector-search -> ${base}/${version}/aggregation/
 [*-v1.20]: ${prefix}/${version}/builders -> ${base}/${version}/
 
 # standardization redirects
 
 # redirects in standardized docs
-[v1.20-*]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/${version}/get-started/download-and-install/
+[v1.20-*]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/${version}/get-started/
 [v1.20-*]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/${version}/connect/
 [v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/monitoring/cluster-monitoring/
 [v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/
@@ -37,20 +43,20 @@ symlink: current -> v2.0
 
 # redirects in old docs
 # note: this mapping does not account for all of the new pages
-[*-v1.19]: ${prefix}/${version}/get-started/download-and-install/ -> ${base}/${version}/tutorial/install-php-library/
-[*-v1.19]: ${prefix}/${version}/connect/ -> ${base}/${version}/tutorial/connecting/
-[*-v1.19]: ${prefix}/${version}/monitoring/cluster-monitoring/ -> ${base}/${version}/tutorial/server-selection/
-[*-v1.19]: ${prefix}/${version}/read/ -> ${base}/${version}/tutorial/crud/
-[*-v1.19]: ${prefix}/${version}/data-formats/codecs/ -> ${base}/${version}/tutorial/codecs/
-[*-v1.19]: ${prefix}/${version}/run-command/ -> ${base}/${version}/tutorial/commands/
-[*-v1.19]: ${prefix}/${version}/data-formats/custom-types/ -> ${base}/${version}/tutorial/custom-types/
-[*-v1.19]: ${prefix}/${version}/data-formats/decimal128/ -> ${base}/${version}/tutorial/decimal128/
-[*-v1.19]: ${prefix}/${version}/security/in-use-encryption/ -> ${base}/${version}/tutorial/encryption/
-[*-v1.19]: ${prefix}/${version}/write/gridfs/ -> ${base}/${version}/tutorial/gridfs/
-[*-v1.19]: ${prefix}/${version}/indexes/ -> ${base}/${version}/tutorial/indexes/
-[*-v1.19]: ${prefix}/${version}/read/cursor/ -> ${base}/${version}/tutorial/tailable-cursor/
-[*-v1.19]: ${prefix}/${version}/data-formats/modeling-bson-data/ -> ${base}/${version}/tutorial/modeling-bson-data/
-[*-v1.19]: ${prefix}/${version}/stable-api/ -> ${base}/${version}/tutorial/stable-api/
-[*-v1.19]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/
-[*-v1.19]: ${prefix}/${version}/aws-lambda/ -> ${base}/${version}/tutorial/aws-lambda/
-
+[*-v1.19]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/v1.x/get-started/
+[*-v1.19]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/v1.x/connect/
+[*-v1.19]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/v1.x/monitoring/cluster-monitoring/
+[*-v1.19]: ${prefix}/${version}/tutorial/crud/ -> ${base}/v1.x/read/
+[*-v1.19]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/v1.x/data-formats/codecs/
+[*-v1.19]: ${prefix}/${version}/tutorial/collation/ -> ${base}/v1.x/
+[*-v1.19]: ${prefix}/${version}/tutorial/commands/ -> ${base}/v1.x/run-command/
+[*-v1.19]: ${prefix}/${version}/tutorial/custom-types/ -> ${base}/v1.x/data-formats/custom-types/
+[*-v1.19]: ${prefix}/${version}/tutorial/decimal128/ -> ${base}/v1.x/data-formats/decimal128/
+[*-v1.19]: ${prefix}/${version}/tutorial/encryption/ -> ${base}/v1.x/security/in-use-encryption/
+[*-v1.19]: ${prefix}/${version}/tutorial/gridfs/ -> ${base}/v1.x/write/gridfs/
+[*-v1.19]: ${prefix}/${version}/tutorial/indexes/ -> ${base}/v1.x/indexes/
+[*-v1.19]: ${prefix}/${version}/tutorial/tailable-cursor/ -> ${base}/v1.x/read/cursor/
+[*-v1.19]: ${prefix}/${version}/tutorial/example-data/ -> ${base}/v1.x/
+[*-v1.19]: ${prefix}/${version}/tutorial/modeling-bson-data/ -> ${base}/v1.x/data-formats/modeling-bson-data/
+[*-v1.19]: ${prefix}/${version}/tutorial/stable-api/ -> ${base}/v1.x/stable-api/
+[*-v1.19]: ${prefix}/${version}/tutorial/aws-lambda/ -> ${base}/v1.x/aws-lambda/

snooty.toml

@@ -9,6 +9,7 @@ intersphinx = [
 
 toc_landing_pages = [
     "/reference/class/MongoDBClient",
+    "/reference/class/MongoDBClientBulkWrite",
     "/reference/class/MongoDBCollection",
     "/reference/class/MongoDBDatabase",
     "/reference/class/MongoDBGridFSBucket",
@@ -38,7 +39,7 @@ php-library = "MongoDB PHP Library"
 
 [constants]
 php-library = "MongoDB PHP Library"
-version = "2.0"
+version = "2.1"
 source-gh-branch = "v2.x"
 full-version = "{+version+}.0"
 extension-short = "PHP extension"

source/includes/extracts-bulkwriteexception.yaml

@@ -1,8 +1,8 @@
 ref: bulkwriteexception-result
 content: |
   If a :php:`MongoDB\Driver\Exception\BulkWriteException
-  <mongodb-driver-exception-bulkwriteexception>` is thrown, users should call
-  :php:`getWriteResult() <mongodb-driver-writeexception.getwriteresult>` and
+  <mongodb-driver-exception-bulkwriteexception>` is thrown, you can call
+  :php:`getWriteResult() <mongodb-driver-bulkwriteexception.getwriteresult>` and
   inspect the returned :php:`MongoDB\Driver\WriteResult
   <mongodb-driver-writeresult>` object to determine the nature of the error.
 
@@ -11,11 +11,22 @@ content: |
   too long). Alternatively, a write operation may have failed outright (e.g.
   unique key violation).
 ---
+ref: bulkwriteexception-client-result
+content: |
+  If a :php:`MongoDB\Driver\Exception\BulkWriteCommandException
+  <mongodb-driver-exception-bulkwritecommandexception>` is thrown, you can call
+  :php:`getWriteErrors() <mongodb-driver-bulkwritecommandexception.getwriteerrors>` and
+  inspect the information in the returned array to determine the nature of the error.
+
+  For example, a write operation may have been successfully applied to the
+  primary server but failed to satisfy the write concern. Alternatively, a
+  write operation may have failed outright, for example for violating the
+  unique key constraint.
+---
 ref: bulkwriteexception-ordered
 content: |
-  In the case of a bulk write, the result may indicate multiple successful write
+  In the case of a bulk write, the result might indicate multiple successful write
   operations and/or errors. If the ``ordered`` option is ``true``, some
   operations may have succeeded before the first error was encountered and the
   exception thrown. If the ``ordered`` option is ``false``, multiple errors may
   have been encountered.
-...

source/includes/extracts-error.yaml

@@ -2,8 +2,16 @@ ref: error-driver-bulkwriteexception
 content: |
   :php:`MongoDB\Driver\Exception\BulkWriteException
   <mongodb-driver-exception-bulkwriteexception>` for errors related to the write
-  operation. Users should inspect the value returned by :php:`getWriteResult()
-  <mongodb-driver-writeexception.getwriteresult>` to determine the nature of the
+  operation. You can inspect the value returned by :php:`getWriteResult()
+  <mongodb-driver-bulkwriteexception.getwriteresult>` to determine the nature of the
+  error.
+---
+ref: error-driver-client-bulkwriteexception
+content: |
+  :php:`MongoDB\Driver\Exception\BulkWriteCommandException
+  <mongodb-driver-exception-bulkwritecommandexception>` for errors related to the write
+  operation. You can inspect the value returned by :php:`getWriteErrors()
+  <mongodb-driver-bulkwritecommandexception.getwriteerrors>` to determine the nature of the
   error.
 ---
 ref: error-driver-invalidargumentexception
@@ -49,4 +57,3 @@ ref: error-gridfs-corruptfileexception
 content: |
   :phpclass:`MongoDB\GridFS\Exception\CorruptFileException` if the file's
   metadata or chunk documents contain unexpected or invalid data.
-...

source/includes/language-compatibility-table-php.rst

@@ -13,7 +13,7 @@
      - PHP 7.3
      - PHP 7.2
 
-   * - ext + lib 1.21 to 2.0
+   * - ext + lib 1.21 to 2.1
      - ✓
      - ✓
      - ✓

source/includes/mongodb-compatibility-table-php.rst

@@ -8,7 +8,7 @@
      - MongoDB 7.0
      - MongoDB 6.0
 
-   * - ext + lib 1.20 to 2.0
+   * - ext + lib 1.20 to 2.1
      - ✓
      - ✓
      - ✓

source/includes/write/bulk-write.php

@@ -5,24 +5,22 @@
 $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
 $client = new MongoDB\Client($uri);
 
-// start-db-coll
-$collection = $client->sample_restaurants->restaurants;
-// end-db-coll
-
 // start-run-bulk
-$result = $collection->bulkWrite(
+$restaurantCollection = $client->sample_restaurants->restaurants;
+
+$result = $restaurantCollection->bulkWrite(
     [
         [
             'insertOne' => [
-                ['name' => 'Mongo\'s Deli'], 
-                ['cuisine' => 'Sandwiches'], 
-                ['borough' => 'Manhattan'], 
-                ['restaurant_id' => '1234'], 
+                ['name' => 'Mongo\'s Deli'],
+                ['cuisine' => 'Sandwiches'],
+                ['borough' => 'Manhattan'],
+                ['restaurant_id' => '1234'],
             ],
         ],
         [
             'updateOne' => [
-                ['name' => 'Mongo\'s Deli'], 
+                ['name' => 'Mongo\'s Deli'],
                 ['$set' => ['cuisine' => 'Sandwiches and Salads']],
             ],
         ],
@@ -36,14 +34,14 @@
 // end-run-bulk
 
 // start-bulk-options
-$result = $collection->bulkWrite(
+$result = $restaurantCollection->bulkWrite(
     [
         [
             'insertOne' => [
-                ['name' => 'Mongo\'s Pizza'], 
-                ['cuisine' => 'Italian'], 
-                ['borough' => 'Queens'], 
-                ['restaurant_id' => '5678'], 
+                ['name' => 'Mongo\'s Pizza'],
+                ['cuisine' => 'Italian'],
+                ['borough' => 'Queens'],
+                ['restaurant_id' => '5678'],
             ],
         ],
         [
@@ -55,3 +53,112 @@
     ['ordered' => false]
 );
 // end-bulk-options
+
+// start-bulk-client-insert-one
+$restaurantCollection = $client->sample_restaurants->restaurants;
+$movieCollection = $client->sample_mflix->movies;
+
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
+$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
+
+$bulkWrite = $bulkWrite->withCollection($movieCollection);
+$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);
+// end-bulk-client-insert-one
+
+// start-bulk-client-update-one
+$restaurantCollection = $client->sample_restaurants->restaurants;
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
+
+$bulkWrite->updateOne(
+    ['name' => 'Dandelion Bakery'],
+    ['$set' => ['grade' => 'B+']],
+    ['upsert' => true],
+);
+// end-bulk-client-update-one
+
+// start-bulk-client-update-many
+$restaurantCollection = $client->sample_restaurants->restaurants;
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
+
+$bulkWrite->updateMany(
+    ['name' => 'Starbucks'],
+    ['$set' => ['cuisine' => 'Coffee (Chain)']],
+);
+// end-bulk-client-update-many
+
+// start-bulk-client-replace-one
+$restaurantCollection = $client->sample_restaurants->restaurants;
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
+
+$bulkWrite->replaceOne(
+    ['name' => 'Dandelion Bakery'],
+    ['name' => 'Flower Patisserie', 'cuisine' => 'Bakery & Cafe'],
+);
+// end-bulk-client-replace-one
+
+// start-bulk-client-delete-one
+$restaurantCollection = $client->sample_restaurants->restaurants;
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
+
+$bulkWrite->deleteOne(
+    ['borough' => 'Queens'],
+);
+// end-bulk-client-delete-one
+
+// start-bulk-client-delete-many
+$restaurantCollection = $client->sample_restaurants->restaurants;
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
+
+$bulkWrite->deleteMany(
+    ['name' => ['$regex' => 'p{2,}']],
+);
+// end-bulk-client-delete-many
+
+// start-bulk-client
+$restaurantCollection = $client->sample_restaurants->restaurants;
+$movieCollection = $client->sample_mflix->movies;
+// Creates the bulk write command and sets the target namespace.
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
+// Specifies insertion of one document.
+$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
+// Specifies a `$set` update to one document with the upsert option
+// enabled.
+$bulkWrite->updateOne(
+    ['name' => 'Dandelion Bakery'],
+    ['$set' => ['grade' => 'B+']],
+    ['upsert' => true],
+);
+// Changes the target namespace.
+$bulkWrite = $bulkWrite->withCollection($movieCollection);
+// Specifies insertion of one document.
+$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);
+// Specifies deletion of documents in which `title` has two consective
+// 'd' characters.
+$bulkWrite->deleteMany(
+    ['title' => ['$regex' => 'd{2,}']],
+);
+// Specifies replacement of one document.
+$bulkWrite->replaceOne(
+    ['runtime' => ['$gte' => 200]],
+    ['title' => 'Seven Samurai', 'runtime' => 203],
+);
+
+// Performs the bulk write operation.
+$result = $client->bulkWrite($bulkWrite);
+// Prints a summary of results.
+echo 'Inserted documents: ', $result->getInsertedCount(), PHP_EOL;
+echo 'Modified documents: ', $result->getModifiedCount(), PHP_EOL;
+echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;
+// end-bulk-client
+
+// start-bulk-client-options
+$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection(
+    $restaurantCollection,
+    ['ordered' => false]
+);
+// end-bulk-client-options
+
+// start-bulk-client-unordered-behavior
+$bulkWrite->insertOne(['_id' => 4045, 'title' => 'The Green Ray']);
+$bulkWrite->deleteOne(['_id' => 4045]);
+// end-bulk-client-unordered-behavior

source/reference.txt

@@ -11,6 +11,7 @@ API Documentation
 
    BSON </reference/bson>
    MongoDB\Client </reference/class/MongoDBClient>
+   MongoDB\ClientBulkWrite </reference/class/MongoDBClientBulkWrite>
    MongoDB\Database </reference/class/MongoDBDatabase>
    MongoDB\Collection </reference/class/MongoDBCollection>
    MongoDB\GridFS\Bucket </reference/class/MongoDBGridFSBucket>