From 14380e9a7215b7fd303b61f587387046ec924ddd Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 11 Apr 2025 09:11:41 -0400 Subject: [PATCH 01/12] DOCSP-44581: v2 release (#234) * DOCSP-44581: v2 release * small fix --- config/redirects | 5 +++-- snooty.toml | 4 ++-- .../includes/language-compatibility-table-php.rst | 2 +- .../includes/mongodb-compatibility-table-php.rst | 14 +++++++++++++- source/whats-new.txt | 3 +++ 5 files changed, 22 insertions(+), 6 deletions(-) diff --git a/config/redirects b/config/redirects index 79959d8a..d437be97 100644 --- a/config/redirects +++ b/config/redirects @@ -1,9 +1,10 @@ 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 master +define: versions v1.16 v1.17 v1.18 v1.19 v1.20 v1.21 v2.0 master + symlink: upcoming -> master -symlink: current -> v1.21 +symlink: current -> v2.0 # general redirects [v1.17-v1.19]: ${prefix}/${version}/tutorial/client-side-encryption/ -> ${base}/${version}/tutorial/encryption/ diff --git a/snooty.toml b/snooty.toml index f8653240..50630236 100644 --- a/snooty.toml +++ b/snooty.toml @@ -38,8 +38,8 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" -version = "1.21" -source-gh-branch = "v1.x" +version = "2.0" +source-gh-branch = "v2.x" full-version = "{+version+}.0" extension-short = "PHP extension" mdb-server = "MongoDB Server" diff --git a/source/includes/language-compatibility-table-php.rst b/source/includes/language-compatibility-table-php.rst index d8826b58..2c6432b4 100644 --- a/source/includes/language-compatibility-table-php.rst +++ b/source/includes/language-compatibility-table-php.rst @@ -13,7 +13,7 @@ - PHP 7.3 - PHP 7.2 - * - ext + lib 1.21 + * - ext + lib 1.21 to 2.0 - ✓ - ✓ - ✓ diff --git a/source/includes/mongodb-compatibility-table-php.rst b/source/includes/mongodb-compatibility-table-php.rst index a815e328..cdcba413 100644 --- a/source/includes/mongodb-compatibility-table-php.rst +++ b/source/includes/mongodb-compatibility-table-php.rst @@ -13,7 +13,17 @@ - MongoDB 4.0 - MongoDB 3.6 - * - ext + lib 1.20 to 1.21 + * - ext + lib 1.21 to 2.0 + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ [#deprecation-note]_ + - + + * - ext + lib 1.20 - ✓ - ✓ - ✓ @@ -42,3 +52,5 @@ - ✓ - ✓ - ✓ + +.. [#deprecation-note] Support for this MongoDB version is deprecated and will be removed in a future release. diff --git a/source/whats-new.txt b/source/whats-new.txt index 3183d6a1..ad60d98c 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -70,6 +70,9 @@ and removals: examples that use this construction, see the :ref:`php-aggregation-builder-api` section of the Aggregation guide. +- Replaces ``Cursor`` type hints with ``CursorInterface`` for better + extensibility and compatibility. + - Removes deprecated fields in GridFS types. - The library does not calculate the ``md5`` field when a file is From 8374053711dfea0eb972fd67cd777094a6f393c5 Mon Sep 17 00:00:00 2001 From: Nick Larew Date: Tue, 15 Apr 2025 08:40:03 -0500 Subject: [PATCH 02/12] Add missing meta descriptions (#235) * Add missing meta descriptions * Apply suggestions from code review --------- Co-authored-by: Rachel Mackintosh <148898879+rachel-mack@users.noreply.github.com> --- source/faq.txt | 3 +++ source/index.txt | 3 +++ source/reference.txt | 3 +++ source/reference/bson.txt | 3 +++ source/reference/class/MongoDBClient.txt | 3 +++ source/reference/class/MongoDBCollection.txt | 3 +++ source/reference/class/MongoDBDatabase.txt | 3 +++ source/reference/class/MongoDBGridFSBucket.txt | 3 +++ source/reference/exception-classes.txt | 3 +++ source/reference/method/MongoDBClient-addSubscriber.txt | 3 +++ .../reference/method/MongoDBClient-createClientEncryption.txt | 3 +++ source/reference/method/MongoDBClient-dropDatabase.txt | 3 +++ source/reference/method/MongoDBClient-getManager.txt | 3 +++ source/reference/method/MongoDBClient-getReadConcern.txt | 3 +++ source/reference/method/MongoDBClient-getReadPreference.txt | 3 +++ source/reference/method/MongoDBClient-getTypeMap.txt | 3 +++ source/reference/method/MongoDBClient-getWriteConcern.txt | 3 +++ source/reference/method/MongoDBClient-listDatabaseNames.txt | 3 +++ source/reference/method/MongoDBClient-listDatabases.txt | 3 +++ source/reference/method/MongoDBClient-removeSubscriber.txt | 3 +++ source/reference/method/MongoDBClient-selectCollection.txt | 3 +++ source/reference/method/MongoDBClient-selectDatabase.txt | 3 +++ source/reference/method/MongoDBClient-startSession.txt | 3 +++ source/reference/method/MongoDBClient-watch.txt | 3 +++ source/reference/method/MongoDBClient__construct.txt | 3 +++ source/reference/method/MongoDBClient__get.txt | 3 +++ source/reference/method/MongoDBCollection-aggregate.txt | 3 +++ source/reference/method/MongoDBCollection-bulkWrite.txt | 3 +++ source/reference/method/MongoDBCollection-count.txt | 3 +++ source/reference/method/MongoDBCollection-countDocuments.txt | 3 +++ source/reference/method/MongoDBCollection-createIndex.txt | 3 +++ source/reference/method/MongoDBCollection-createIndexes.txt | 3 +++ .../reference/method/MongoDBCollection-createSearchIndex.txt | 3 +++ .../reference/method/MongoDBCollection-createSearchIndexes.txt | 3 +++ source/reference/method/MongoDBCollection-deleteMany.txt | 3 +++ source/reference/method/MongoDBCollection-deleteOne.txt | 3 +++ source/reference/method/MongoDBCollection-distinct.txt | 3 +++ source/reference/method/MongoDBCollection-drop.txt | 3 +++ source/reference/method/MongoDBCollection-dropIndex.txt | 3 +++ source/reference/method/MongoDBCollection-dropIndexes.txt | 3 +++ source/reference/method/MongoDBCollection-dropSearchIndex.txt | 3 +++ .../method/MongoDBCollection-estimatedDocumentCount.txt | 3 +++ source/reference/method/MongoDBCollection-explain.txt | 3 +++ source/reference/method/MongoDBCollection-find.txt | 3 +++ source/reference/method/MongoDBCollection-findOne.txt | 3 +++ source/reference/method/MongoDBCollection-findOneAndDelete.txt | 3 +++ .../reference/method/MongoDBCollection-findOneAndReplace.txt | 3 +++ source/reference/method/MongoDBCollection-findOneAndUpdate.txt | 3 +++ .../reference/method/MongoDBCollection-getCollectionName.txt | 3 +++ source/reference/method/MongoDBCollection-getDatabaseName.txt | 3 +++ source/reference/method/MongoDBCollection-getManager.txt | 3 +++ source/reference/method/MongoDBCollection-getNamespace.txt | 3 +++ source/reference/method/MongoDBCollection-getReadConcern.txt | 3 +++ .../reference/method/MongoDBCollection-getReadPreference.txt | 3 +++ source/reference/method/MongoDBCollection-getTypeMap.txt | 3 +++ source/reference/method/MongoDBCollection-getWriteConcern.txt | 3 +++ source/reference/method/MongoDBCollection-insertMany.txt | 3 +++ source/reference/method/MongoDBCollection-insertOne.txt | 3 +++ source/reference/method/MongoDBCollection-listIndexes.txt | 3 +++ .../reference/method/MongoDBCollection-listSearchIndexes.txt | 3 +++ source/reference/method/MongoDBCollection-rename.txt | 3 +++ source/reference/method/MongoDBCollection-replaceOne.txt | 3 +++ source/reference/method/MongoDBCollection-updateMany.txt | 3 +++ source/reference/method/MongoDBCollection-updateOne.txt | 3 +++ .../reference/method/MongoDBCollection-updateSearchIndex.txt | 3 +++ source/reference/method/MongoDBCollection-watch.txt | 3 +++ source/reference/method/MongoDBCollection-withOptions.txt | 3 +++ source/reference/method/MongoDBCollection__construct.txt | 3 +++ source/reference/method/MongoDBDatabase-selectGridFSBucket.txt | 3 +++ .../method/MongoDBGridFSBucket-downloadToStreamByName.txt | 3 +++ source/reference/method/MongoDBGridFSBucket-find.txt | 3 +++ .../method/MongoDBGridFSBucket-getFileDocumentForStream.txt | 3 +++ .../method/MongoDBGridFSBucket-getFileIdForStream.txt | 3 +++ .../method/MongoDBGridFSBucket-openDownloadStreamByName.txt | 3 +++ source/tutorial.txt | 3 +++ source/tutorial/collation.txt | 3 +++ source/tutorial/commands.txt | 3 +++ source/tutorial/encryption.txt | 3 +++ source/tutorial/server-selection.txt | 3 +++ source/upgrade.txt | 1 + 80 files changed, 238 insertions(+) diff --git a/source/faq.txt b/source/faq.txt index 3e6c03d5..3b7a6edf 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -4,6 +4,9 @@ Frequently Asked Questions ========================== +.. meta:: + :description: Find solutions to common PHP extension installation errors, connection handling, and server selection failures when using the MongoDB PHP library. + .. contents:: On this page :local: diff --git a/source/index.txt b/source/index.txt index 6d456d74..53398b22 100644 --- a/source/index.txt +++ b/source/index.txt @@ -2,6 +2,9 @@ MongoDB PHP Library =================== +.. meta:: + :description: Explore the MongoDB PHP Library for high-level database operations, including installation, connection, data manipulation, and deployment on AWS Lambda. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference.txt b/source/reference.txt index 7127505b..d987e7c8 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -2,6 +2,9 @@ API Documentation ================= +.. meta:: + :description: Explore the MongoDB PHP library API reference for detailed information on available methods and classes. + .. toctree:: :titlesonly: diff --git a/source/reference/bson.txt b/source/reference/bson.txt index 8d5b1393..8b2948a3 100644 --- a/source/reference/bson.txt +++ b/source/reference/bson.txt @@ -2,6 +2,9 @@ BSON ==== +.. meta:: + :description: Understand how BSON documents and arrays are represented and serialized in the MongoDB PHP Library using BSONDocument and BSONArray classes. + .. contents:: On this page :local: diff --git a/source/reference/class/MongoDBClient.txt b/source/reference/class/MongoDBClient.txt index 27125c62..36b3cea6 100644 --- a/source/reference/class/MongoDBClient.txt +++ b/source/reference/class/MongoDBClient.txt @@ -2,6 +2,9 @@ MongoDB\\Client Class ===================== +.. meta:: + :description: Explore the MongoDB\Client class, which serves as the entry point for connecting to MongoDB servers and accessing databases and collections in the MongoDB PHP Library. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/class/MongoDBCollection.txt b/source/reference/class/MongoDBCollection.txt index 33e3e7e3..29501088 100644 --- a/source/reference/class/MongoDBCollection.txt +++ b/source/reference/class/MongoDBCollection.txt @@ -2,6 +2,9 @@ MongoDB\\Collection Class ========================= +.. meta:: + :description: Explore methods for performing CRUD operations and index management with the MongoDB\Collection class in the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/class/MongoDBDatabase.txt b/source/reference/class/MongoDBDatabase.txt index 9db6317f..713db8c5 100644 --- a/source/reference/class/MongoDBDatabase.txt +++ b/source/reference/class/MongoDBDatabase.txt @@ -2,6 +2,9 @@ MongoDB\\Database Class ======================= +.. meta:: + :description: Explore methods for database operations and collection management using the MongoDB\Database class in the MongoDB PHP Library. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/class/MongoDBGridFSBucket.txt b/source/reference/class/MongoDBGridFSBucket.txt index ab7f42b4..eb574d32 100644 --- a/source/reference/class/MongoDBGridFSBucket.txt +++ b/source/reference/class/MongoDBGridFSBucket.txt @@ -2,6 +2,9 @@ MongoDB\\GridFS\\Bucket Class ============================= +.. meta:: + :description: Explore the MongoDB\GridFS\Bucket class for managing file storage and retrieval in the MongoDB PHP Library using PHP Streams. + .. contents:: On this page :local: diff --git a/source/reference/exception-classes.txt b/source/reference/exception-classes.txt index d862eb7d..aed23515 100644 --- a/source/reference/exception-classes.txt +++ b/source/reference/exception-classes.txt @@ -2,6 +2,9 @@ Exception Classes ================= +.. meta:: + :description: Explore MongoDB\Exception classes in the MongoDB PHP Library, detailing their usage and inheritance. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBClient-addSubscriber.txt b/source/reference/method/MongoDBClient-addSubscriber.txt index 74b19d70..a51263a7 100644 --- a/source/reference/method/MongoDBClient-addSubscriber.txt +++ b/source/reference/method/MongoDBClient-addSubscriber.txt @@ -2,6 +2,9 @@ MongoDB\\Client::addSubscriber() ================================ +.. meta:: + :description: Register a monitoring event subscriber with a MongoDB Client to receive notifications of all events for that Client. + .. versionadded:: 1.18 diff --git a/source/reference/method/MongoDBClient-createClientEncryption.txt b/source/reference/method/MongoDBClient-createClientEncryption.txt index b791d681..ac458644 100644 --- a/source/reference/method/MongoDBClient-createClientEncryption.txt +++ b/source/reference/method/MongoDBClient-createClientEncryption.txt @@ -2,6 +2,9 @@ MongoDB\\Client::createClientEncryption() ========================================= +.. meta:: + :description: Create a ClientEncryption object in PHP for manual encryption and decryption of values with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBClient-dropDatabase.txt b/source/reference/method/MongoDBClient-dropDatabase.txt index dc01eebe..d5420e3b 100644 --- a/source/reference/method/MongoDBClient-dropDatabase.txt +++ b/source/reference/method/MongoDBClient-dropDatabase.txt @@ -2,6 +2,9 @@ MongoDB\\Client::dropDatabase() =============================== +.. meta:: + :description: Drop a database on the server with options for comments, sessions, type maps, and write concerns with the MongoDB PHP Library. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBClient-getManager.txt b/source/reference/method/MongoDBClient-getManager.txt index 4aa73cea..e3d72282 100644 --- a/source/reference/method/MongoDBClient-getManager.txt +++ b/source/reference/method/MongoDBClient-getManager.txt @@ -2,6 +2,9 @@ MongoDB\\Client::getManager() ============================= +.. meta:: + :description: Access the MongoDB\Driver\Manager used by a Client with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBClient-getReadConcern.txt b/source/reference/method/MongoDBClient-getReadConcern.txt index 77026f76..7e8ec896 100644 --- a/source/reference/method/MongoDBClient-getReadConcern.txt +++ b/source/reference/method/MongoDBClient-getReadConcern.txt @@ -2,6 +2,9 @@ MongoDB\\Client::getReadConcern() ================================= +.. meta:: + :description: Retrieve the read concern level set for a Client with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBClient-getReadPreference.txt b/source/reference/method/MongoDBClient-getReadPreference.txt index 3ffd3240..4a7b2a2d 100644 --- a/source/reference/method/MongoDBClient-getReadPreference.txt +++ b/source/reference/method/MongoDBClient-getReadPreference.txt @@ -2,6 +2,9 @@ MongoDB\\Client::getReadPreference() ==================================== +.. meta:: + :description: Retrieve the read preference setting for a Client with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBClient-getTypeMap.txt b/source/reference/method/MongoDBClient-getTypeMap.txt index 57cae044..632933cd 100644 --- a/source/reference/method/MongoDBClient-getTypeMap.txt +++ b/source/reference/method/MongoDBClient-getTypeMap.txt @@ -2,6 +2,9 @@ MongoDB\\Client::getTypeMap() ============================= +.. meta:: + :description: Retrieve the type map for a Client with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBClient-getWriteConcern.txt b/source/reference/method/MongoDBClient-getWriteConcern.txt index d2a566de..19cb5cb1 100644 --- a/source/reference/method/MongoDBClient-getWriteConcern.txt +++ b/source/reference/method/MongoDBClient-getWriteConcern.txt @@ -2,6 +2,9 @@ MongoDB\\Client::getWriteConcern() ================================== +.. meta:: + :description: Retrieve the write concern for a Client with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBClient-listDatabaseNames.txt b/source/reference/method/MongoDBClient-listDatabaseNames.txt index 4f12d628..47ba4978 100644 --- a/source/reference/method/MongoDBClient-listDatabaseNames.txt +++ b/source/reference/method/MongoDBClient-listDatabaseNames.txt @@ -2,6 +2,9 @@ MongoDB\\Client::listDatabaseNames() ==================================== +.. meta:: + :description: Retrieve database names from a MongoDB server with the MongoDB PHP Library, with optional parameters for filtering and session management. + .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBClient-listDatabases.txt b/source/reference/method/MongoDBClient-listDatabases.txt index 718e3717..baada43b 100644 --- a/source/reference/method/MongoDBClient-listDatabases.txt +++ b/source/reference/method/MongoDBClient-listDatabases.txt @@ -2,6 +2,9 @@ MongoDB\\Client::listDatabases() ================================ +.. meta:: + :description: Retrieve information for all databases on the server with the MongoDB PHP Library, with optional parameters for filtering and session association. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBClient-removeSubscriber.txt b/source/reference/method/MongoDBClient-removeSubscriber.txt index 9c43f8b2..9d66b90d 100644 --- a/source/reference/method/MongoDBClient-removeSubscriber.txt +++ b/source/reference/method/MongoDBClient-removeSubscriber.txt @@ -2,6 +2,9 @@ MongoDB\\Client::removeSubscriber() =================================== +.. meta:: + :description: Unregister a monitoring event subscriber from a Client with the MongoDB PHP Library. + .. versionadded:: 1.18 diff --git a/source/reference/method/MongoDBClient-selectCollection.txt b/source/reference/method/MongoDBClient-selectCollection.txt index 0ca80161..aa2fdb29 100644 --- a/source/reference/method/MongoDBClient-selectCollection.txt +++ b/source/reference/method/MongoDBClient-selectCollection.txt @@ -2,6 +2,9 @@ MongoDB\\Client::selectCollection() =================================== +.. meta:: + :description: Select a collection on the server with the MongoDB PHP Library, with customizable options for read and write concerns. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBClient-selectDatabase.txt b/source/reference/method/MongoDBClient-selectDatabase.txt index 0c1913de..5f270aee 100644 --- a/source/reference/method/MongoDBClient-selectDatabase.txt +++ b/source/reference/method/MongoDBClient-selectDatabase.txt @@ -2,6 +2,9 @@ MongoDB\\Client::selectDatabase() ================================= +.. meta:: + :description: Select a database on the server with the MongoDB PHP Library, with options for read and write concerns, read preference, and type mapping. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBClient-startSession.txt b/source/reference/method/MongoDBClient-startSession.txt index 32a1ec0f..0c9c42a8 100644 --- a/source/reference/method/MongoDBClient-startSession.txt +++ b/source/reference/method/MongoDBClient-startSession.txt @@ -2,6 +2,9 @@ MongoDB\\Client::startSession() =============================== +.. meta:: + :description: Start a new client session with the MongoDB PHP Library and handle potential exceptions. + .. versionadded:: 1.3 diff --git a/source/reference/method/MongoDBClient-watch.txt b/source/reference/method/MongoDBClient-watch.txt index c097f4bf..8bf455d2 100644 --- a/source/reference/method/MongoDBClient-watch.txt +++ b/source/reference/method/MongoDBClient-watch.txt @@ -2,6 +2,9 @@ MongoDB\\Client::watch() ======================== +.. meta:: + :description: Execute a change stream operation on the Client to monitor cluster-level changes with the MongoDB PHP Library. + .. versionadded:: 1.4 diff --git a/source/reference/method/MongoDBClient__construct.txt b/source/reference/method/MongoDBClient__construct.txt index 6b052161..50214f2a 100644 --- a/source/reference/method/MongoDBClient__construct.txt +++ b/source/reference/method/MongoDBClient__construct.txt @@ -2,6 +2,9 @@ MongoDB\\Client::__construct() ============================== +.. meta:: + :description: Learn how to construct a new MongoDB Client instance with the MongoDB PHP Library, including options for connection strings, authentication, SSL, and custom type maps. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBClient__get.txt b/source/reference/method/MongoDBClient__get.txt index 82c1016a..153eb8c9 100644 --- a/source/reference/method/MongoDBClient__get.txt +++ b/source/reference/method/MongoDBClient__get.txt @@ -2,6 +2,9 @@ MongoDB\\Client::__get() ======================== +.. meta:: + :description: Access a database on the server with the MongoDB PHP Library, which acts as an alias for the selectDatabase() method. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-aggregate.txt b/source/reference/method/MongoDBCollection-aggregate.txt index 7f459acb..24080b45 100644 --- a/source/reference/method/MongoDBCollection-aggregate.txt +++ b/source/reference/method/MongoDBCollection-aggregate.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::aggregate() ================================ +.. meta:: + :description: Execute an aggregation framework pipeline operation on a collection with the MongoDB PHP Library, with various customizable options. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-bulkWrite.txt b/source/reference/method/MongoDBCollection-bulkWrite.txt index 0e5f9a97..4a85ab91 100644 --- a/source/reference/method/MongoDBCollection-bulkWrite.txt +++ b/source/reference/method/MongoDBCollection-bulkWrite.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::bulkWrite() ================================ +.. meta:: + :description: Execute multiple write operations with the MongoDB PHP Library, with options for write concern, session, and more. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-count.txt b/source/reference/method/MongoDBCollection-count.txt index 1419f55d..5e0d3112 100644 --- a/source/reference/method/MongoDBCollection-count.txt +++ b/source/reference/method/MongoDBCollection-count.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::count() ============================ +.. meta:: + :description: Count documents matching a filter criteria with the MongoDB PHP Library, with options for collation, hint, limit, and more. + .. deprecated:: 1.4 diff --git a/source/reference/method/MongoDBCollection-countDocuments.txt b/source/reference/method/MongoDBCollection-countDocuments.txt index e4ef152a..dc882777 100644 --- a/source/reference/method/MongoDBCollection-countDocuments.txt +++ b/source/reference/method/MongoDBCollection-countDocuments.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::countDocuments() ===================================== +.. meta:: + :description: Count documents in a collection matching a filter criteria with the MongoDB PHP Library, with various options for customization. + .. versionadded:: 1.4 diff --git a/source/reference/method/MongoDBCollection-createIndex.txt b/source/reference/method/MongoDBCollection-createIndex.txt index aabb5679..e99712f6 100644 --- a/source/reference/method/MongoDBCollection-createIndex.txt +++ b/source/reference/method/MongoDBCollection-createIndex.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::createIndex() ================================== +.. meta:: + :description: Create an index in a MongoDB collection with the MongoDB PHP Library, with options for collation, TTL, uniqueness, and more. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-createIndexes.txt b/source/reference/method/MongoDBCollection-createIndexes.txt index 244b3bec..dc6d2f5a 100644 --- a/source/reference/method/MongoDBCollection-createIndexes.txt +++ b/source/reference/method/MongoDBCollection-createIndexes.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::createIndexes() ==================================== +.. meta:: + :description: Create one or more indexes for a collection with the MongoDB PHP Library, with options for unique, compound, and 2dsphere indexes. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-createSearchIndex.txt b/source/reference/method/MongoDBCollection-createSearchIndex.txt index a229a153..5666c5c9 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndex.txt +++ b/source/reference/method/MongoDBCollection-createSearchIndex.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::createSearchIndex() ======================================== +.. meta:: + :description: Create an Atlas Search or Vector Search index for a collection with the MongoDB PHP Library, specifying index type and options. + .. versionadded:: 1.17 .. contents:: On this page diff --git a/source/reference/method/MongoDBCollection-createSearchIndexes.txt b/source/reference/method/MongoDBCollection-createSearchIndexes.txt index 6c1b4981..e96d1a5d 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndexes.txt +++ b/source/reference/method/MongoDBCollection-createSearchIndexes.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::createSearchIndexes() ========================================== +.. meta:: + :description: Create Atlas Search or Vector Search indexes for a collection with the MongoDB PHP Library, specifying index definitions and options. + .. versionadded:: 1.17 diff --git a/source/reference/method/MongoDBCollection-deleteMany.txt b/source/reference/method/MongoDBCollection-deleteMany.txt index 756f8da8..0f38e058 100644 --- a/source/reference/method/MongoDBCollection-deleteMany.txt +++ b/source/reference/method/MongoDBCollection-deleteMany.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::deleteMany() ================================= +.. meta:: + :description: Delete multiple documents in a collection with the MongoDB PHP Library, with options for collation, hint, and write concern. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-deleteOne.txt b/source/reference/method/MongoDBCollection-deleteOne.txt index 40204c82..a479f237 100644 --- a/source/reference/method/MongoDBCollection-deleteOne.txt +++ b/source/reference/method/MongoDBCollection-deleteOne.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::deleteOne() ================================ +.. meta:: + :description: Delete a single document matching a filter criteria with the MongoDB PHP Library, with options for collation, hint, and write concern. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-distinct.txt b/source/reference/method/MongoDBCollection-distinct.txt index 2ca85299..045b3012 100644 --- a/source/reference/method/MongoDBCollection-distinct.txt +++ b/source/reference/method/MongoDBCollection-distinct.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::distinct() =============================== +.. meta:: + :description: Find distinct values for a specified field in a collection with the MongoDB PHP Library, with options for filtering and additional parameters. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-drop.txt b/source/reference/method/MongoDBCollection-drop.txt index cb0bae16..a7a9df1f 100644 --- a/source/reference/method/MongoDBCollection-drop.txt +++ b/source/reference/method/MongoDBCollection-drop.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::drop() =========================== +.. meta:: + :description: Remove a collection with the MongoDB PHP Library, including options for write concern and session management. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-dropIndex.txt b/source/reference/method/MongoDBCollection-dropIndex.txt index c6546655..bbbff49c 100644 --- a/source/reference/method/MongoDBCollection-dropIndex.txt +++ b/source/reference/method/MongoDBCollection-dropIndex.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::dropIndex() ================================ +.. meta:: + :description: Drop an index from a collection with the MongoDB PHP Library, with options for session, write concern, and more. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-dropIndexes.txt b/source/reference/method/MongoDBCollection-dropIndexes.txt index 8e544d8b..cad32dcc 100644 --- a/source/reference/method/MongoDBCollection-dropIndexes.txt +++ b/source/reference/method/MongoDBCollection-dropIndexes.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::dropIndexes() ================================== +.. meta:: + :description: Drop all indexes in a MongoDB collection except the `_id` index with the MongoDB PHP Library, with options for comments, time limits, and write concerns. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-dropSearchIndex.txt b/source/reference/method/MongoDBCollection-dropSearchIndex.txt index 43066312..15e0880b 100644 --- a/source/reference/method/MongoDBCollection-dropSearchIndex.txt +++ b/source/reference/method/MongoDBCollection-dropSearchIndex.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::dropSearchIndex() ====================================== +.. meta:: + :description: Drop an Atlas Search index from a collection with the MongoDB PHP Library, available for Atlas deployments with a minimum M10 cluster tier. + .. versionadded:: 1.17 .. contents:: On this page diff --git a/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt b/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt index efddeba7..542d8c2f 100644 --- a/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt +++ b/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::estimatedDocumentCount() ============================================= +.. meta:: + :description: Estimate the number of documents in a collection with the MongoDB PHP Library, with optional parameters for read concern, read preference, and more. + .. versionadded:: 1.4 diff --git a/source/reference/method/MongoDBCollection-explain.txt b/source/reference/method/MongoDBCollection-explain.txt index 6912556e..52c2520f 100644 --- a/source/reference/method/MongoDBCollection-explain.txt +++ b/source/reference/method/MongoDBCollection-explain.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::explain() ============================== +.. meta:: + :description: Analyze command execution details with the MongoDB PHP Library, including parameters and return values. + .. versionadded:: 1.4 diff --git a/source/reference/method/MongoDBCollection-find.txt b/source/reference/method/MongoDBCollection-find.txt index 484edb55..34cd979f 100644 --- a/source/reference/method/MongoDBCollection-find.txt +++ b/source/reference/method/MongoDBCollection-find.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::find() =========================== +.. meta:: + :description: Query documents with the MongoDB PHP Library, with various options like filters, projections, and sorting in PHP. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-findOne.txt b/source/reference/method/MongoDBCollection-findOne.txt index 8b880eeb..99aca91c 100644 --- a/source/reference/method/MongoDBCollection-findOne.txt +++ b/source/reference/method/MongoDBCollection-findOne.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::findOne() ============================== +.. meta:: + :description: Find a single document in a collection with the MongoDB PHP Library, with various query and option parameters. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-findOneAndDelete.txt b/source/reference/method/MongoDBCollection-findOneAndDelete.txt index 67fac4d7..a1eb75cb 100644 --- a/source/reference/method/MongoDBCollection-findOneAndDelete.txt +++ b/source/reference/method/MongoDBCollection-findOneAndDelete.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::findOneAndDelete() ======================================= +.. meta:: + :description: Find and delete a single document in a collection with the MongoDB PHP Library, with options for collation, projection, and more. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-findOneAndReplace.txt b/source/reference/method/MongoDBCollection-findOneAndReplace.txt index 0edf7d68..68c862a4 100644 --- a/source/reference/method/MongoDBCollection-findOneAndReplace.txt +++ b/source/reference/method/MongoDBCollection-findOneAndReplace.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::findOneAndReplace() ======================================== +.. meta:: + :description: Find and replace a document in a collection with the MongoDB PHP Library, with various options and return the modified document. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-findOneAndUpdate.txt b/source/reference/method/MongoDBCollection-findOneAndUpdate.txt index be372645..c48db888 100644 --- a/source/reference/method/MongoDBCollection-findOneAndUpdate.txt +++ b/source/reference/method/MongoDBCollection-findOneAndUpdate.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::findOneAndUpdate() ======================================= +.. meta:: + :description: Find and update a single document in a collection with the MongoDB PHP Library, with options for projection, sorting, and more. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-getCollectionName.txt b/source/reference/method/MongoDBCollection-getCollectionName.txt index dd551923..f2af9daf 100644 --- a/source/reference/method/MongoDBCollection-getCollectionName.txt +++ b/source/reference/method/MongoDBCollection-getCollectionName.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getCollectionName() ======================================== +.. meta:: + :description: Retrieve the name of a collection with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-getDatabaseName.txt b/source/reference/method/MongoDBCollection-getDatabaseName.txt index 1c983c49..89450447 100644 --- a/source/reference/method/MongoDBCollection-getDatabaseName.txt +++ b/source/reference/method/MongoDBCollection-getDatabaseName.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getDatabaseName() ====================================== +.. meta:: + :description: Retrieve the name of the database containing a specific collection with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-getManager.txt b/source/reference/method/MongoDBCollection-getManager.txt index 5f927a2f..42ee0a59 100644 --- a/source/reference/method/MongoDBCollection-getManager.txt +++ b/source/reference/method/MongoDBCollection-getManager.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getManager() ================================= +.. meta:: + :description: Access the MongoDB\Driver\Manager used by a collection with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-getNamespace.txt b/source/reference/method/MongoDBCollection-getNamespace.txt index 09bc7f66..f8f5921e 100644 --- a/source/reference/method/MongoDBCollection-getNamespace.txt +++ b/source/reference/method/MongoDBCollection-getNamespace.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getNamespace() =================================== +.. meta:: + :description: Retrieve the namespace of a collection with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-getReadConcern.txt b/source/reference/method/MongoDBCollection-getReadConcern.txt index fd51e3db..014da099 100644 --- a/source/reference/method/MongoDBCollection-getReadConcern.txt +++ b/source/reference/method/MongoDBCollection-getReadConcern.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getReadConcern() ===================================== +.. meta:: + :description: Retrieve the read concern of a collection with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBCollection-getReadPreference.txt b/source/reference/method/MongoDBCollection-getReadPreference.txt index 8bbb22e7..88a11e03 100644 --- a/source/reference/method/MongoDBCollection-getReadPreference.txt +++ b/source/reference/method/MongoDBCollection-getReadPreference.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getReadPreference() ======================================== +.. meta:: + :description: Retrieve the read preference of a collection with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBCollection-getTypeMap.txt b/source/reference/method/MongoDBCollection-getTypeMap.txt index 02ac773d..63255778 100644 --- a/source/reference/method/MongoDBCollection-getTypeMap.txt +++ b/source/reference/method/MongoDBCollection-getTypeMap.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getTypeMap() ================================= +.. meta:: + :description: Retrieve the type map for a collection with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBCollection-getWriteConcern.txt b/source/reference/method/MongoDBCollection-getWriteConcern.txt index aaf867eb..35af5c1d 100644 --- a/source/reference/method/MongoDBCollection-getWriteConcern.txt +++ b/source/reference/method/MongoDBCollection-getWriteConcern.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::getWriteConcern() ====================================== +.. meta:: + :description: Retrieve the write concern of a collection with the MongoDB PHP Library. + .. versionadded:: 1.2 diff --git a/source/reference/method/MongoDBCollection-insertMany.txt b/source/reference/method/MongoDBCollection-insertMany.txt index 31c4ca82..85875ca5 100644 --- a/source/reference/method/MongoDBCollection-insertMany.txt +++ b/source/reference/method/MongoDBCollection-insertMany.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::insertMany() ================================= +.. meta:: + :description: Insert multiple documents into a collection with the MongoDB PHP Library, with options for validation, write concern, and session management. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-insertOne.txt b/source/reference/method/MongoDBCollection-insertOne.txt index dea76a90..aa92ba9f 100644 --- a/source/reference/method/MongoDBCollection-insertOne.txt +++ b/source/reference/method/MongoDBCollection-insertOne.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::insertOne() ================================ +.. meta:: + :description: Insert a single document into a collection with the MongoDB PHP Library, with options for validation, codec, session, and write concern. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-listIndexes.txt b/source/reference/method/MongoDBCollection-listIndexes.txt index 7281cf1e..de289989 100644 --- a/source/reference/method/MongoDBCollection-listIndexes.txt +++ b/source/reference/method/MongoDBCollection-listIndexes.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::listIndexes() ================================== +.. meta:: + :description: Retrieve information about all indexes in a collection with the MongoDB PHP Library. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-listSearchIndexes.txt b/source/reference/method/MongoDBCollection-listSearchIndexes.txt index f6a5b550..e08469f7 100644 --- a/source/reference/method/MongoDBCollection-listSearchIndexes.txt +++ b/source/reference/method/MongoDBCollection-listSearchIndexes.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::listSearchIndexes() ======================================== +.. meta:: + :description: Retrieve index information for all search indexes in a collection with the MongoDB PHP Library, with various customizable options. + .. versionadded:: 1.17 diff --git a/source/reference/method/MongoDBCollection-rename.txt b/source/reference/method/MongoDBCollection-rename.txt index eaec8950..720c4d34 100644 --- a/source/reference/method/MongoDBCollection-rename.txt +++ b/source/reference/method/MongoDBCollection-rename.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::rename() ============================= +.. meta:: + :description: Rename a collection with the MongoDB PHP Library, with options for database name, drop target, and write concern. + .. versionadded:: 1.10 .. contents:: On this page diff --git a/source/reference/method/MongoDBCollection-replaceOne.txt b/source/reference/method/MongoDBCollection-replaceOne.txt index b9cf0fc1..13797018 100644 --- a/source/reference/method/MongoDBCollection-replaceOne.txt +++ b/source/reference/method/MongoDBCollection-replaceOne.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::replaceOne() ================================= +.. meta:: + :description: Replace a single document in a collection based on filter criteria with the MongoDB PHP Library, with options for upsert, collation, and more. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-updateMany.txt b/source/reference/method/MongoDBCollection-updateMany.txt index a5c6b141..86d1d2a2 100644 --- a/source/reference/method/MongoDBCollection-updateMany.txt +++ b/source/reference/method/MongoDBCollection-updateMany.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::updateMany() ================================= +.. meta:: + :description: Update multiple documents in a collection with the MongoDB PHP Library, with various options like filters, collation, and upsert. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection-updateOne.txt b/source/reference/method/MongoDBCollection-updateOne.txt index 4ad2588b..131ac036 100644 --- a/source/reference/method/MongoDBCollection-updateOne.txt +++ b/source/reference/method/MongoDBCollection-updateOne.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::updateOne() ================================ +.. meta:: + :description: Update a single document in a collection with the MongoDB PHP Library, with various options like filters, collation, and upsert, and handle potential exceptions. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-updateSearchIndex.txt b/source/reference/method/MongoDBCollection-updateSearchIndex.txt index fb31d073..a08cf305 100644 --- a/source/reference/method/MongoDBCollection-updateSearchIndex.txt +++ b/source/reference/method/MongoDBCollection-updateSearchIndex.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::updateSearchIndex() ======================================== +.. meta:: + :description: Update an Atlas Search index for a collection with the MongoDB PHP Library, requiring an Atlas cluster tier of at least M10. + .. versionadded:: 1.17 diff --git a/source/reference/method/MongoDBCollection-watch.txt b/source/reference/method/MongoDBCollection-watch.txt index d02ba299..6510930b 100644 --- a/source/reference/method/MongoDBCollection-watch.txt +++ b/source/reference/method/MongoDBCollection-watch.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::watch() ============================ +.. meta:: + :description: Execute a change stream operation on a collection to monitor collection-level changes with the MongoDB PHP Library. + .. versionadded:: 1.3 diff --git a/source/reference/method/MongoDBCollection-withOptions.txt b/source/reference/method/MongoDBCollection-withOptions.txt index f7077e03..a320aa22 100644 --- a/source/reference/method/MongoDBCollection-withOptions.txt +++ b/source/reference/method/MongoDBCollection-withOptions.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::withOptions() ================================== +.. meta:: + :description: Clone a Collection object with different options with the MongoDB PHP Library, specifying parameters like codec, read concern, and write concern. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBCollection__construct.txt b/source/reference/method/MongoDBCollection__construct.txt index 250f07bf..35fdf3df 100644 --- a/source/reference/method/MongoDBCollection__construct.txt +++ b/source/reference/method/MongoDBCollection__construct.txt @@ -2,6 +2,9 @@ MongoDB\\Collection::__construct() ================================== +.. meta:: + :description: Construct a new Collection instance with the MongoDB PHP Library, with options for read and write concerns, type mapping, and more. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt b/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt index fe988ebf..174c0d31 100644 --- a/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt +++ b/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt @@ -2,6 +2,9 @@ MongoDB\\Database::selectGridFSBucket() ======================================= +.. meta:: + :description: Select a GridFS bucket in a MongoDB database with the MongoDB PHP Library, with customizable options for bucket name, chunk size, and more. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt b/source/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt index 420cf6ca..8580397b 100644 --- a/source/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt +++ b/source/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt @@ -2,6 +2,9 @@ MongoDB\\GridFS\\Bucket::downloadToStreamByName() ================================================= +.. meta:: + :description: Select a GridFS file by filename and copy its contents to a writable stream with the MongoDB PHP Library, with options for file revision. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBGridFSBucket-find.txt b/source/reference/method/MongoDBGridFSBucket-find.txt index f52538d0..3ceac0a9 100644 --- a/source/reference/method/MongoDBGridFSBucket-find.txt +++ b/source/reference/method/MongoDBGridFSBucket-find.txt @@ -2,6 +2,9 @@ MongoDB\\GridFS\\Bucket::find() =============================== +.. meta:: + :description: Query documents in a GridFS bucket's files collection with the MongoDB PHP Library, with various filter and option parameters. + .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt b/source/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt index 41062f29..25e0b87d 100644 --- a/source/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt +++ b/source/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt @@ -2,6 +2,9 @@ MongoDB\\GridFS\\Bucket::getFileDocumentForStream() =================================================== +.. meta:: + :description: Retrieve the file document of a GridFS file associated with a stream with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt b/source/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt index a047362f..22a6b45e 100644 --- a/source/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt +++ b/source/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt @@ -2,6 +2,9 @@ MongoDB\\GridFS\\Bucket::getFileIdForStream() ============================================= +.. meta:: + :description: Retrieve the file document ID for a GridFS file associated with a stream with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt b/source/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt index d853af80..90b4719f 100644 --- a/source/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt +++ b/source/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt @@ -2,6 +2,9 @@ MongoDB\\GridFS\\Bucket::openDownloadStreamByName() =================================================== +.. meta:: + :description: Access a GridFS file by its filename and open it as a readable stream with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/tutorial.txt b/source/tutorial.txt index a472adb9..4786bb9e 100644 --- a/source/tutorial.txt +++ b/source/tutorial.txt @@ -3,6 +3,9 @@ Tutorials ========= +.. meta:: + :description: Explore various tutorials for using the MongoDB PHP Library. + .. toctree:: diff --git a/source/tutorial/collation.txt b/source/tutorial/collation.txt index 0cd239b1..26bc2df0 100644 --- a/source/tutorial/collation.txt +++ b/source/tutorial/collation.txt @@ -4,6 +4,9 @@ Collation ========= +.. meta:: + :description: Learn how to use collations to apply language-specific rules for string comparison in collections, indexes, and various operations with the MongoDB PHP Library. + .. contents:: On this page :local: diff --git a/source/tutorial/commands.txt b/source/tutorial/commands.txt index b540cc9e..4305e07a 100644 --- a/source/tutorial/commands.txt +++ b/source/tutorial/commands.txt @@ -4,6 +4,9 @@ Execute Database Commands ========================= +.. meta:: + :description: Learn to execute database commands with the MongoDB PHP Library, including handling single and multiple result documents and setting custom read preferences. + .. contents:: On this page :local: diff --git a/source/tutorial/encryption.txt b/source/tutorial/encryption.txt index fb0085ac..70b99df3 100644 --- a/source/tutorial/encryption.txt +++ b/source/tutorial/encryption.txt @@ -4,6 +4,9 @@ In-Use Encryption ================= +.. meta:: + :description: Learn how to implement in-use encryption in PHP projects with the MongoDB PHP Library, including managing encryption keys and configuring client-side field level encryption. + .. contents:: On this page :local: diff --git a/source/tutorial/server-selection.txt b/source/tutorial/server-selection.txt index 0ef65206..62c20cae 100644 --- a/source/tutorial/server-selection.txt +++ b/source/tutorial/server-selection.txt @@ -4,6 +4,9 @@ Server Selection and Monitoring =============================== +.. meta:: + :description: Understand how the MongoDB PHP Library selects and monitors servers, including connection string options for server selection and monitoring. + .. contents:: On this page :local: diff --git a/source/upgrade.txt b/source/upgrade.txt index b9d5c7ff..c37fc106 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -16,6 +16,7 @@ Upgrade Library Versions .. meta:: :keywords: compatibility, backwards compatibility + :description: Learn how to upgrade the MongoDB PHP Library and PHP extension, ensuring compatibility and addressing breaking changes. Overview -------- From ffdd49c6a9c76ab0c768f47fee624f497a66dd47 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 16 Apr 2025 10:29:30 -0400 Subject: [PATCH 03/12] DOCSP-48761: docker note (#237) --- source/connect/connection-targets.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 59497bb0..003578f3 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -107,10 +107,14 @@ set this connection option: :language: php :copyable: true +.. note:: Replica Set in Docker + + .. sharedinclude:: dbx/docker-replica-set.rst + API Documentation ----------------- To learn more about using the ``MongoDB\Client`` class, see the following API documentation: -- :phpclass:`MongoDB\Client` \ No newline at end of file +- :phpclass:`MongoDB\Client` From d84ef0ac4a2edcaad127f2039cb30a9e829f3ee3 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Thu, 15 May 2025 10:51:19 -0400 Subject: [PATCH 04/12] DOCSP-48100: Consolidate minor versions (#240) * DOCSP-48100: Consolidate minor versions * edits * remove old redirects * AB feedback * edit --- config/redirects | 36 ++++++++++-------------------------- snooty.toml | 1 + source/upgrade.txt | 40 +++++++++++++++++++++++++--------------- 3 files changed, 36 insertions(+), 41 deletions(-) diff --git a/config/redirects b/config/redirects index d437be97..a747c57b 100644 --- a/config/redirects +++ b/config/redirects @@ -1,15 +1,19 @@ 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: 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 + +# 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}/ @@ -17,7 +21,7 @@ symlink: current -> v2.0 # 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/ @@ -34,23 +38,3 @@ symlink: current -> v2.0 [v1.20-*]: ${prefix}/${version}/tutorial/modeling-bson-data/ -> ${base}/${version}/data-formats/modeling-bson-data/ [v1.20-*]: ${prefix}/${version}/tutorial/stable-api/ -> ${base}/${version}/stable-api/ [v1.20-*]: ${prefix}/${version}/tutorial/aws-lambda/ -> ${base}/${version}/aws-lambda/ - -# 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/ - diff --git a/snooty.toml b/snooty.toml index 50630236..0d6dfcc0 100644 --- a/snooty.toml +++ b/snooty.toml @@ -50,3 +50,4 @@ api = "https://www.mongodb.com/docs/php-library/current/reference" string-data-type = "``string``" bool-data-type = "``bool``" int-data-type = "``int``" +language = "PHP" diff --git a/source/upgrade.txt b/source/upgrade.txt index c37fc106..5c0c8fe8 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -30,15 +30,16 @@ How to Upgrade Before you upgrade, perform the following actions: -- Ensure the new {+library-short+} version is compatible with the {+mdb-server+} versions - your application connects to and the PHP version your - application compiles with. For version compatibility information, see the - :ref:`{+php-library+} Compatibility ` - page. - Address any breaking changes between the library version your application is using and your planned upgrade version in the :ref:`Breaking Changes ` section. +- Ensure the new {+library-short+} version is compatible with the {+mdb-server+} versions + your application connects to and the PHP version your + application compiles with. For version compatibility information, see the + :ref:`Compatibility Changes ` section and the + :ref:`{+php-library+} Compatibility ` page. + .. tip:: To ensure compatibility across {+mdb-server+} versions when @@ -81,8 +82,9 @@ 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. +version that introduced them. Only major library versions introduce +breaking changes. When upgrading 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 @@ -113,15 +115,23 @@ This library version introduces the following breaking changes: methods, you can register a :php:`CommandSubscriber ` in your application. -Version 1.20 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _php-compat-changes: -This library version introduces the following breaking changes: +Compatibility Changes +--------------------- + +This section describes the {+mdb-server+} and {+language+} compatibility +changes introduced in {+php-library+} version releases. + +Version 1.x Compatibility Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This library version introduces the following compatibility changes: -- Drops support for {+mdb-server+} 3.6. +- Drops support for {+mdb-server+} 3.6 in {+php-library+} v1.20 -Version 1.19 and Earlier -~~~~~~~~~~~~~~~~~~~~~~~~ +.. tip:: Earlier Library Versions -For library versions 1.19 and earlier, see the release notes and associated -JIRA tickets for each release on `GitHub `__. + To view compatibility changes for {+php-library+} versions 1.19 and earlier, see the + release notes and associated JIRA tickets for each release on `GitHub + `__. From 7bc5a55ec4dd501dce23d632b12c3f997e152f03 Mon Sep 17 00:00:00 2001 From: shuangela Date: Thu, 15 May 2025 14:57:10 -0400 Subject: [PATCH 05/12] DOCSP-48718-update-credentials (#247) * update username and password * misspelling --- source/get-started.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/get-started.txt b/source/get-started.txt index f64c8ee4..45d7a3b3 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -163,8 +163,8 @@ your MongoDB database in the cloud. .. step:: Save your credentials - After you create your database user, save that user's - username and password to a safe location for use in an upcoming step. + After you create your database user, save that user's database + username and database password to a safe location for use in an upcoming step. After you complete these steps, you have a new free tier MongoDB deployment on Atlas, database user credentials, and sample data loaded From 2e04bdfb02a46be3ace2c934e1ef5bf788ce72c2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 May 2025 15:23:28 -0400 Subject: [PATCH 06/12] redirects --- config/redirects | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/config/redirects b/config/redirects index a747c57b..d4120164 100644 --- a/config/redirects +++ b/config/redirects @@ -1,11 +1,13 @@ -define: base https://www.mongodb.com/docs/php-library define: prefix docs/php-library -raw: ${prefix}/ -> ${base}/current +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.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/ From 9f93381150a90172adc769dccd7004a29d710c8d Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 May 2025 17:21:50 -0400 Subject: [PATCH 07/12] pre-standardization redirects --- config/redirects | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/config/redirects b/config/redirects index d4120164..4989d297 100644 --- a/config/redirects +++ b/config/redirects @@ -40,3 +40,23 @@ raw: ${prefix}/stable -> ${base}/current/ [v1.20-*]: ${prefix}/${version}/tutorial/modeling-bson-data/ -> ${base}/${version}/data-formats/modeling-bson-data/ [v1.20-*]: ${prefix}/${version}/tutorial/stable-api/ -> ${base}/${version}/stable-api/ [v1.20-*]: ${prefix}/${version}/tutorial/aws-lambda/ -> ${base}/${version}/aws-lambda/ + +# redirects in old docs +# note: this mapping does not account for all of the new pages +[*-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/ \ No newline at end of file From 05aad5c1f047a080c682d2d4ede4e1bdc8f0200f Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 20 May 2025 15:35:14 -0400 Subject: [PATCH 08/12] upgrade composer package vs --- composer/composer.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/composer/composer.json b/composer/composer.json index 8892815e..c85d1216 100644 --- a/composer/composer.json +++ b/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.0", + "mongodb/mongodb": "^2.0" }, "require-dev": { "doctrine/coding-standard": "^12.0", From c614e2463e24fa054dd5c2c18f3d057692d8dcc2 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Wed, 21 May 2025 16:19:01 -0400 Subject: [PATCH 09/12] 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 --- composer/composer.json | 4 +- snooty.toml | 1 + .../includes/extracts-bulkwriteexception.yaml | 19 +- source/includes/extracts-error.yaml | 13 +- source/includes/write/bulk-write.php | 137 +++++- source/reference.txt | 1 + .../class/MongoDBBulkWriteCommandResult.txt | 71 +++ .../class/MongoDBBulkWriteResult.txt | 4 +- source/reference/class/MongoDBClient.txt | 4 +- .../class/MongoDBClientBulkWrite.txt | 47 ++ .../method/MongoDBClient-bulkWrite.txt | 101 ++++ ...DBClientBulkWrite-createWithCollection.txt | 96 ++++ .../MongoDBClientBulkWrite-deleteMany.txt | 71 +++ .../MongoDBClientBulkWrite-deleteOne.txt | 71 +++ .../MongoDBClientBulkWrite-insertOne.txt | 53 +++ .../MongoDBClientBulkWrite-replaceOne.txt | 87 ++++ .../MongoDBClientBulkWrite-updateMany.txt | 93 ++++ .../MongoDBClientBulkWrite-updateOne.txt | 96 ++++ .../MongoDBClientBulkWrite-withCollection.txt | 62 +++ .../method/MongoDBCollection-bulkWrite.txt | 6 +- .../method/MongoDBCollection-insertMany.txt | 4 +- source/reference/result-classes.txt | 1 + source/whats-new.txt | 14 + source/write/bulk-write.txt | 434 ++++++++++++++++-- source/write/replace.txt | 3 +- source/write/transaction.txt | 8 + source/write/update.txt | 3 +- 27 files changed, 1421 insertions(+), 83 deletions(-) create mode 100644 source/reference/class/MongoDBBulkWriteCommandResult.txt create mode 100644 source/reference/class/MongoDBClientBulkWrite.txt create mode 100644 source/reference/method/MongoDBClient-bulkWrite.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-deleteMany.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-deleteOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-insertOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-replaceOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-updateMany.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-updateOne.txt create mode 100644 source/reference/method/MongoDBClientBulkWrite-withCollection.txt diff --git a/composer/composer.json b/composer/composer.json index c85d1216..a76d24ba 100644 --- a/composer/composer.json +++ b/composer/composer.json @@ -2,8 +2,8 @@ "name": "mongodb/docs-php-library", "description": "MongoDB PHP Library Documentation", "require": { - "ext-mongodb": "^2.0", - "mongodb/mongodb": "^2.0" + "ext-mongodb": "^2.1", + "mongodb/mongodb": "^2.1" }, "require-dev": { "doctrine/coding-standard": "^12.0", diff --git a/snooty.toml b/snooty.toml index 0d6dfcc0..24d9ed5e 100644 --- a/snooty.toml +++ b/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", diff --git a/source/includes/extracts-bulkwriteexception.yaml b/source/includes/extracts-bulkwriteexception.yaml index 6276458e..a19fce00 100644 --- a/source/includes/extracts-bulkwriteexception.yaml +++ b/source/includes/extracts-bulkwriteexception.yaml @@ -1,8 +1,8 @@ ref: bulkwriteexception-result content: | If a :php:`MongoDB\Driver\Exception\BulkWriteException - ` is thrown, users should call - :php:`getWriteResult() ` and + ` is thrown, you can call + :php:`getWriteResult() ` and inspect the returned :php:`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 + ` is thrown, you can call + :php:`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. -... diff --git a/source/includes/extracts-error.yaml b/source/includes/extracts-error.yaml index c4d8afa5..d829b0ec 100644 --- a/source/includes/extracts-error.yaml +++ b/source/includes/extracts-error.yaml @@ -2,8 +2,16 @@ ref: error-driver-bulkwriteexception content: | :php:`MongoDB\Driver\Exception\BulkWriteException ` for errors related to the write - operation. Users should inspect the value returned by :php:`getWriteResult() - ` to determine the nature of the + operation. You can inspect the value returned by :php:`getWriteResult() + ` to determine the nature of the + error. +--- +ref: error-driver-client-bulkwriteexception +content: | + :php:`MongoDB\Driver\Exception\BulkWriteCommandException + ` for errors related to the write + operation. You can inspect the value returned by :php:`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. -... diff --git a/source/includes/write/bulk-write.php b/source/includes/write/bulk-write.php index a3543a22..2e0f9612 100644 --- a/source/includes/write/bulk-write.php +++ b/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 diff --git a/source/reference.txt b/source/reference.txt index d987e7c8..b66b65c7 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -11,6 +11,7 @@ API Documentation BSON MongoDB\Client + MongoDB\ClientBulkWrite MongoDB\Database MongoDB\Collection MongoDB\GridFS\Bucket diff --git a/source/reference/class/MongoDBBulkWriteCommandResult.txt b/source/reference/class/MongoDBBulkWriteCommandResult.txt new file mode 100644 index 00000000..f92f04d2 --- /dev/null +++ b/source/reference/class/MongoDBBulkWriteCommandResult.txt @@ -0,0 +1,71 @@ +===================================== +MongoDB\\BulkWriteCommandResult Class +===================================== + +Definition +---------- + +.. phpclass:: MongoDB\BulkWriteCommandResult + + This class contains information about a completed client bulk write operation. It + is returned from :phpmethod:`MongoDB\Client::bulkWrite()`. + +Methods +------- + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getInsertedCount()`` + - | Returns the total number of documents inserted by all + insert operations in the bulk write command. + + * - ``getMatchedCount()`` + - | Returns the total number of documents matched by all + update and replace operations in the bulk write command. + + * - ``getModifiedCount()`` + - | Returns the total number of documents modified by all update + and replace operations in the bulk write command. + + * - ``getUpsertedCount()`` + - | Returns the total number of documents upserted by all update + and replace operations in the bulk write command. + + * - ``getDeletedCount()`` + - | Return the total number of documents deleted by all delete + operations in the bulk write command. + + * - ``getInsertResults()`` + - | Returns a map of results of each successful insert operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation such + as the inserted ``_id`` value. + + * - ``getUpdateResults()`` + - | Returns a map of results of each successful update operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation. + + * - ``getDeleteResults()`` + - | Returns a map of results of each successful delete operation. + Each operation is represented by an integer key, which contains + a document with information corresponding to the operation. + + * - ``isAcknowledged()`` + - | Returns a boolean indicating whether the server acknowledged + the bulk operation. + +To learn more about the information returned from the server when you +perform a client bulk write operation, see the :manual:`Output +` section of the +``Mongo.bulkWrite`` shell method reference. + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/class/MongoDBBulkWriteResult.txt b/source/reference/class/MongoDBBulkWriteResult.txt index 2e8c78cf..14c87c85 100644 --- a/source/reference/class/MongoDBBulkWriteResult.txt +++ b/source/reference/class/MongoDBBulkWriteResult.txt @@ -7,7 +7,7 @@ Definition .. phpclass:: MongoDB\BulkWriteResult - This class contains information about an executed bulk write operation. It + This class contains information about a completed bulk write operation. It encapsulates a :php:`MongoDB\Driver\WriteResult ` object and is returned from :phpmethod:`MongoDB\Collection::bulkWrite()`. @@ -33,4 +33,4 @@ Methods - :phpmethod:`MongoDB\BulkWriteResult::getModifiedCount()` - :phpmethod:`MongoDB\BulkWriteResult::getUpsertedCount()` - :phpmethod:`MongoDB\BulkWriteResult::getUpsertedIds()` -- :phpmethod:`MongoDB\BulkWriteResult::isAcknowledged()` \ No newline at end of file +- :phpmethod:`MongoDB\BulkWriteResult::isAcknowledged()` diff --git a/source/reference/class/MongoDBClient.txt b/source/reference/class/MongoDBClient.txt index 36b3cea6..0dc61e25 100644 --- a/source/reference/class/MongoDBClient.txt +++ b/source/reference/class/MongoDBClient.txt @@ -32,6 +32,7 @@ Methods __construct() __get() addSubscriber() + bulkWrite() createClientEncryption() dropDatabase() getCollection() @@ -52,6 +53,7 @@ Methods - :phpmethod:`MongoDB\Client::__construct()` - :phpmethod:`MongoDB\Client::__get()` - :phpmethod:`MongoDB\Client::addSubscriber()` +- :phpmethod:`MongoDB\Client::bulkWrite()` - :phpmethod:`MongoDB\Client::createClientEncryption()` - :phpmethod:`MongoDB\Client::dropDatabase()` - :phpmethod:`MongoDB\Client::getCollection()` @@ -67,4 +69,4 @@ Methods - :phpmethod:`MongoDB\Client::selectCollection()` - :phpmethod:`MongoDB\Client::selectDatabase()` - :phpmethod:`MongoDB\Client::startSession()` -- :phpmethod:`MongoDB\Client::watch()` \ No newline at end of file +- :phpmethod:`MongoDB\Client::watch()` diff --git a/source/reference/class/MongoDBClientBulkWrite.txt b/source/reference/class/MongoDBClientBulkWrite.txt new file mode 100644 index 00000000..b197a2f5 --- /dev/null +++ b/source/reference/class/MongoDBClientBulkWrite.txt @@ -0,0 +1,47 @@ +============================== +MongoDB\\ClientBulkWrite Class +============================== + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpclass:: MongoDB\ClientBulkWrite + + This class enables you to assemble a bulk write command that you + pass to :phpmethod:`MongoDB\Client::bulkWrite()` to perform write + operations across multiple namespaces. + + ``ClientBulkWrite`` is a builder class to create a :php:`BulkWriteCommand + ` instance that the library sends to the + server. + +Methods +------- + +.. toctree:: + :titlesonly: + + createWithCollection() + deleteMany() + deleteOne() + insertOne() + replaceOne() + updateMany() + updateOne() + withCollection() + +- :phpmethod:`MongoDB\ClientBulkWrite::createWithCollection()` +- :phpmethod:`MongoDB\ClientBulkWrite::deleteMany()` +- :phpmethod:`MongoDB\ClientBulkWrite::deleteOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::insertOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::replaceOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::updateMany()` +- :phpmethod:`MongoDB\ClientBulkWrite::updateOne()` +- :phpmethod:`MongoDB\ClientBulkWrite::withCollection()` + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClient-bulkWrite.txt b/source/reference/method/MongoDBClient-bulkWrite.txt new file mode 100644 index 00000000..6e3ab31b --- /dev/null +++ b/source/reference/method/MongoDBClient-bulkWrite.txt @@ -0,0 +1,101 @@ +============================ +MongoDB\\Client::bulkWrite() +============================ + +.. meta:: + :description: Perform write operations across multiple namespaces by using the MongoDB PHP Library. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\Client::bulkWrite() + + Perform multiple write operations across multiple namespaces. + + .. code-block:: php + + function bulkWrite( + BulkWriteCommand|ClientBulkWrite $bulk, + array $options = [] + ): MongoDB\BulkWriteCommandResult + +Parameters +---------- + +``$bulk`` : :phpclass:`MongoDB\ClientBulkWrite` or + :php:`BulkWriteCommand ` + + .. tip:: Prefer ClientBulkWrite API + + We recommend using the ``ClientBulkWrite`` builder class and + methods to specify write operations in a bulk write command instead + of using the ``BulkWriteCommand`` class. ``ClientBulkWrite`` + provides a fluent API with methods similar to CRUD methods from the + :phpclass:`MongoDB\Collection` class. + + Represents the assembled bulk write command or builder. + :phpmethod:`MongoDB\Client::bulkWrite()` supports + ``deleteMany()``, ``deleteOne()``, ``insertOne()``, + ``replaceOne()``, ``updateMany()``, and ``updateOne()`` + operations. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - session + - :php:`MongoDB\Driver\Session ` + - .. include:: /includes/extracts/common-option-session.rst + + * - writeConcern + - :php:`MongoDB\Driver\WriteConcern ` + - .. include:: /includes/extracts/collection-option-writeConcern.rst + + .. include:: /includes/extracts/common-option-writeConcern-transaction.rst + +Return Values +------------- + +A :phpclass:`MongoDB\BulkWriteCommandResult` object. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/bulkwriteexception-client-result.rst +.. include:: /includes/extracts/bulkwriteexception-ordered.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide +- :ref:`php-write` +- :phpmethod:`MongoDB\Collection::deleteMany()` +- :phpmethod:`MongoDB\Collection::deleteOne()` +- :phpmethod:`MongoDB\Collection::insertMany()` +- :phpmethod:`MongoDB\Collection::insertOne()` +- :phpmethod:`MongoDB\Collection::replaceOne()` +- :phpmethod:`MongoDB\Collection::updateMany()` +- :phpmethod:`MongoDB\Collection::updateOne()` diff --git a/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt new file mode 100644 index 00000000..44928fbb --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-createWithCollection.txt @@ -0,0 +1,96 @@ +================================================ +MongoDB\\ClientBulkWrite::createWithCollection() +================================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::createWithCollection() + + Create an instance of the :phpclass:`MongoDB\ClientBulkWrite` builder + from the provided :phpclass:`MongoDB\Collection` instance. You can + add write operations to the ``ClientBulkWrite`` to create a new + :php:`BulkWriteCommand ` that the + library sends to the server. + + .. code-block:: php + + function createWithCollection( + Collection $collection, + array $options = [] + ): self + +Parameters +---------- + +``$collection`` : :phpclass:`MongoDB\Collection` + The ``Collection`` instance to set as the target for bulk write + operations. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - bypassDocumentValidation + - boolean + - If ``true``: the write operation ignores document level + validation. + + The default is ``false``. + + * - comment + - mixed + - .. include:: /includes/extracts/common-option-comment.rst + + * - let + - array|object + - .. include:: /includes/extracts/common-option-let.rst + + * - ordered + - boolean + - If ``true``: When a single write fails, the operation stops without + performing the remaining writes and throws an exception. + + If ``false``: When a single write fails, the operation continues + with the remaining writes, if any, and throws an exception. + + The default is ``true``. + + * - verboseResults + - boolean + - Specifies whether to return verbose results. + + The default is ``false``. + +Return Values +------------- + +A new ``ClientBulkWrite`` instance with an empty ``BulkWriteCommand`` +specification. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt new file mode 100644 index 00000000..654d7c40 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-deleteMany.txt @@ -0,0 +1,71 @@ +====================================== +MongoDB\\ClientBulkWrite::deleteMany() +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::deleteMany() + + Specify a delete operation in the bulk write command for all + matching documents. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. + + .. code-block:: php + + function deleteMany( + array|object $filter, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to delete. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt new file mode 100644 index 00000000..0358af9f --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-deleteOne.txt @@ -0,0 +1,71 @@ +===================================== +MongoDB\\ClientBulkWrite::deleteOne() +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::deleteOne() + + Specify a delete operation in the bulk write command for the first + matching document. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. + + .. code-block:: php + + function deleteMany( + array|object $filter, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the document to delete. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-insertOne.txt b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt new file mode 100644 index 00000000..74ffa769 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-insertOne.txt @@ -0,0 +1,53 @@ +===================================== +MongoDB\\ClientBulkWrite::insertOne() +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::insertOne() + + Specify an insert operation in the bulk write command. This method + returns the :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. + + .. code-block:: php + + function insertOne( + array|object $document, + mixed &$id = null + ): self + +Parameters +---------- + +``$document`` : array|object + The document to insert into the collection. + +``$id`` : mixed + Captures the document's ``_id`` field value to store in an optional + output variable. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt new file mode 100644 index 00000000..dcf81e66 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-replaceOne.txt @@ -0,0 +1,87 @@ +====================================== +MongoDB\\ClientBulkWrite::replaceOne() +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::replaceOne() + + Specify a replace operation in the bulk write command for the first + matching document. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. + + .. code-block:: php + + function replaceOne( + array|object $filter, + array|object $replacement, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to replace. + +``$replacement`` : array|object + The replacement document. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + * - sort + - array|object + - The sort specification for the ordering of the matched + documents. Set this option to apply an order to matched + documents before the server performs the replace operation. + + * - upsert + - boolean + - If set to ``true``, creates a new document when no document matches the + query criteria. The default value is ``false``, which does not insert a + new document when no match is found. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-updateMany.txt b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt new file mode 100644 index 00000000..e4b1d637 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-updateMany.txt @@ -0,0 +1,93 @@ +====================================== +MongoDB\\ClientBulkWrite::updateMany() +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::updateMany() + + Specify an update operation in the bulk write command for all + matching documents. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. + + .. code-block:: php + + function updateMany( + array|object $filter, + array|object $update, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to update. + +``$update`` : array|object + The field and value combinations to update and any relevant update + operators. ``$update`` uses MongoDB's :manual:`update operators `. + You can pass an :manual:`aggregation pipeline + ` as this parameter. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - Name + - Type + - Description + + * - arrayFilters + - array + - An array of filter documents that determines which array elements to + modify for an update operation on an array field. + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + * - upsert + - boolean + - If set to ``true``, creates a new document when no document matches the + query criteria. The default value is ``false``, which does not insert a + new document when no match is found. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-updateOne.txt b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt new file mode 100644 index 00000000..88f542bf --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-updateOne.txt @@ -0,0 +1,96 @@ +===================================== +MongoDB\\ClientBulkWrite::updateOne() +===================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::updateOne() + + Specify an update operation in the bulk write command for the first + matching document. This method returns the + :phpclass:`MongoDB\ClientBulkWrite` instance on which it's called. + + .. code-block:: php + + function updateOne( + array|object $filter, + array|object $update, + array $options = [] + ): self + +Parameters +---------- + +``$filter`` : array|object + The filter criteria that specifies the documents to update. + +``$update`` : array|object + The field and value combinations to update and any relevant update + operators. ``$update`` uses MongoDB's :manual:`update operators + `. You can pass an :manual:`aggregation pipeline + ` as + this parameter. + +``$options`` : array + An array specifying the desired options. + + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Name + - Type + - Description + + * - arrayFilters + - array + - An array of filter documents that determines which array elements to modify + for an update operation on an array field. + + * - collation + - array|object + - .. include:: /includes/extracts/collection-option-collation.rst + + * - hint + - string|array|object + - .. include:: /includes/extracts/common-option-hint.rst + + * - sort + - array|object + - The sort specification for the ordering of the matched + documents. Set this option to apply an order to matched + documents before the server performs the update operation. + + * - upsert + - boolean + - If set to ``true``, creates a new document when no document matches the + query criteria. The default value is ``false``, which does not insert a + new document when no match is found. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-client-bulkwriteexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +Behavior +-------- + +.. include:: /includes/extracts/note-bson-comparison.rst +.. include:: /includes/extracts/bulkwriteexception-client-result.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBClientBulkWrite-withCollection.txt b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt new file mode 100644 index 00000000..0b329491 --- /dev/null +++ b/source/reference/method/MongoDBClientBulkWrite-withCollection.txt @@ -0,0 +1,62 @@ +========================================== +MongoDB\\ClientBulkWrite::withCollection() +========================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. versionadded:: 2.1 + +Definition +---------- + +.. phpmethod:: MongoDB\ClientBulkWrite::withCollection() + + Return an updated instance of :phpclass:`MongoDB\ClientBulkWrite` + from the provided :phpclass:`MongoDB\Collection` instance. This + method allows you to add subsequent write operations on a different + collection than that with which the ``ClientBulkWrite`` was created. + + This method does not build a new :php:`BulkWriteCommand + ` and does not edit the + ``ClientBulkWrite`` instance in place. + + .. code-block:: php + + function withCollection( + Collection $collection, + ): self + + You cannot mix ``Collection`` instances associated with different + ``Manager`` objects when calling this method on a ``ClientBulkWrite`` + instance. This is because the library sends the completed + ``BulkWriteCommand`` to a single server. + +Parameters +---------- + +``$collection`` : :phpclass:`MongoDB\Collection` + The ``Collection`` instance to set as the target for write operations + added to the ``ClientBulkWrite`` instance after calling + ``withCollection()``. + +Return Values +------------- + +A new ``ClientBulkWrite`` instance with the same ``BulkWriteCommand`` +specification but an updated target namespace. + +Errors/Exceptions +----------------- + +.. include:: /includes/extracts/error-unsupportedexception.rst +.. include:: /includes/extracts/error-invalidargumentexception.rst +.. include:: /includes/extracts/error-driver-runtimeexception.rst + +See Also +-------- + +- :ref:`php-client-bulk-write` section of the Bulk Write Operations guide diff --git a/source/reference/method/MongoDBCollection-bulkWrite.txt b/source/reference/method/MongoDBCollection-bulkWrite.txt index 4a85ab91..2f607ea4 100644 --- a/source/reference/method/MongoDBCollection-bulkWrite.txt +++ b/source/reference/method/MongoDBCollection-bulkWrite.txt @@ -104,10 +104,10 @@ Parameters * - ordered - boolean - - If ``true``: when a single write fails, the operation will stop without + - If ``true``: When a single write fails, the operation will stop without performing the remaining writes and throw an exception. - If ``false``: when a single write fails, the operation will continue + If ``false``: When a single write fails, the operation will continue with the remaining writes, if any, and throw an exception. The default is ``true``. @@ -147,7 +147,7 @@ Behavior See Also -------- -- :ref:`php-bulk-write` +- :ref:`php-coll-bulk-write` section of the Bulk Write Operations guide - :ref:`php-write` - :phpmethod:`MongoDB\Collection::deleteMany()` - :phpmethod:`MongoDB\Collection::deleteOne()` diff --git a/source/reference/method/MongoDBCollection-insertMany.txt b/source/reference/method/MongoDBCollection-insertMany.txt index 85875ca5..4e07aa0a 100644 --- a/source/reference/method/MongoDBCollection-insertMany.txt +++ b/source/reference/method/MongoDBCollection-insertMany.txt @@ -64,10 +64,10 @@ Parameters * - ordered - boolean - - If ``true``: when a single write fails, the operation will stop without + - If ``true``: When a single write fails, the operation will stop without performing the remaining writes and throw an exception. - If ``false``: when a single write fails, the operation will continue + If ``false``: When a single write fails, the operation will continue with the remaining writes, if any, and throw an exception. The default is ``true``. diff --git a/source/reference/result-classes.txt b/source/reference/result-classes.txt index db2a1b66..a6aa9455 100644 --- a/source/reference/result-classes.txt +++ b/source/reference/result-classes.txt @@ -5,6 +5,7 @@ Result Classes .. toctree:: :titlesonly: + BulkWriteCommandResult BulkWriteResult DeleteResult InsertManyResult diff --git a/source/whats-new.txt b/source/whats-new.txt index ad60d98c..e7421ddd 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -20,6 +20,7 @@ What's New Learn about new features, improvements, and fixes introduced in the following versions of the {+php-library+}: +* :ref:`Version 2.1 ` * :ref:`Version 2.0 ` * :ref:`Version 1.21 ` * :ref:`Version 1.20 ` @@ -27,6 +28,19 @@ following versions of the {+php-library+}: * :ref:`Version 1.18 ` * :ref:`Version 1.17 ` +.. _php-lib-version-2.1: + +What's New in 2.1 +----------------- + +The {+library-short+} v2.1 release includes the following features, +improvements, and fixes: + +- Adds a *client* bulk write API to perform write + operations on multiple databases and collections in the same call. To learn + more about this feature, see the :ref:`php-client-bulk-write` + section of the Bulk Write Operations guide. + .. _php-lib-version-2.0: What's New in 2.0 diff --git a/source/write/bulk-write.txt b/source/write/bulk-write.txt index bf9abcec..9b6d40b4 100644 --- a/source/write/bulk-write.txt +++ b/source/write/bulk-write.txt @@ -15,43 +15,357 @@ Bulk Write Operations :values: reference .. meta:: - :keywords: insert, update, replace, code example + :keywords: insert, update, replace, code example, multiple changes Overview -------- -In this guide, you can learn how to perform multiple write operations -in a single database call by using **bulk write operations**. +In this guide, you can learn how to perform multiple write operations in +a single database call by using **bulk write operations**. -Consider a scenario in which you want to insert a document into a collection, +Consider a scenario in which you want to insert a document, update multiple other documents, then delete a document. If you use -individual methods, each operation requires its own database call. Instead, -you can use a bulk operation to reduce the number of calls to the database. +individual methods, each operation requires its own database call. + +By using a bulk write operation, you can perform multiple write operations in +fewer database calls. You can perform bulk write operations at the following levels: + +- :ref:`Client `: If your application connects to + {+mdb-server+} version 8.0 or later, you can use the + ``MongoDB\Client::bulkWrite()`` method to perform bulk write + operations on multiple collections and databases in the same cluster. + This method performs all write operations in one database call. To + learn more about this feature, see the :manual:`Mongo.bulkWrite() + ` reference in the {+mdb-server+} + manual. + +- :ref:`Collection `: You can use the + ``MongoDB\Collection::bulkWrite()`` method to perform bulk write + operations on a single collection. This method makes a database call + for each type of write operation. For example, the method can perform + multiple update operations in one call, but makes two separate calls to + the database for an insert operation and a replace operation. Sample Data ~~~~~~~~~~~ -The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` -database from the :atlas:`Atlas sample datasets `. To access this collection -from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster -and assign the following value to your ``$collection`` variable: +The examples in this guide use the ``sample_restaurants.restaurants`` +and ``sample_mflix.movies`` collections from the :atlas:`Atlas sample +datasets `. To learn how to create a free MongoDB Atlas +cluster and load the sample datasets, see the :atlas:`Get Started with +Atlas ` guide. + +.. _php-client-bulk-write: + +Client Bulk Write +----------------- + +When using {+library-short+} v2.1 and connecting to a deployment +running {+mdb-server+} 8.0 or later, you can use the +:phpmethod:`MongoDB\Client::bulkWrite()` method to write to multiple databases +and collections in the same cluster. This method performs all write +operations in a single call. + +First, use the ``MongoDB\ClientBulkWrite`` builder to create a +:php:`BulkWriteCommand ` instance that +specifies the write operations to perform. The following code +demonstrates how to create a ``ClientBulkWrite`` instance from a +``MongoDB\Collection`` instance by using the ``createWithCollection()`` +method: + +.. code-block:: php + :emphasize-lines: 2 + + $restaurantCollection = $client->sample_restaurants->restaurants; + $bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection); + +Then, call one or more of the following write methods on the +``ClientBulkWrite`` instance to construct the bulk write operation: + +- ``deleteOne()`` +- ``deleteMany()`` +- ``insertOne()`` +- ``replaceOne()`` +- ``updateOne()`` +- ``updateMany()`` + +To select a different namespace for subsequent write operations, call +the ``withCollection()`` method on the ``ClientBulkWrite`` instance, as +shown in the following code: + +.. code-block:: php + :emphasize-lines: 2 + + $movieCollection = $client->sample_mflix->movies; + $bulkWrite = $bulkWrite->withCollection($movieCollection); + +The following sections show how to create and use the +``ClientBulkWrite`` class to specify write operations +in a bulk write. The :ref:`php-client-bulkwrite-method` section +demonstrates how to pass the ``ClientBulkWrite`` object to the +``bulkWrite()`` method to perform the bulk operation. + +Insert Operations +~~~~~~~~~~~~~~~~~ + +To specify an insert operation, call the ``insertOne()`` method on your +``ClientBulkWrite`` instance. + +The following example specifies the insertion of documents into the +``sample_restaurants.restaurants`` and ``sample_mflix.movies`` +collections: .. literalinclude:: /includes/write/bulk-write.php - :language: php - :dedent: - :start-after: start-db-coll - :end-before: end-db-coll + :start-after: start-bulk-client-insert-one + :end-before: end-bulk-client-insert-one + :language: php + :copyable: + :dedent: + +Update Operations +~~~~~~~~~~~~~~~~~ + +To specify an update operation on the first matching document, call the +``updateOne()`` method on your ``ClientBulkWrite`` instance. + +The following example specifies a ``$set`` update to the first document +in the ``sample_restaurants.restaurants`` collection that has a ``name`` +value of ``'Dandelion Bakery'``: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-update-one + :end-before: end-bulk-client-update-one + :language: php + :copyable: + :dedent: + +To update multiple documents, call the ``updateMany()`` method. The specified +operation updates *all documents* that match the query filter. -To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the -:atlas:`Get Started with Atlas ` guide. +The following example specifies a ``$set`` update to all matching documents +in the ``sample_restaurants.restaurants`` collection that have a ``name`` +value of ``'Starbucks'``: -.. _php-bulk-operations: +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-update-many + :end-before: end-bulk-client-update-many + :language: php + :copyable: + :dedent: -Bulk Operations ---------------- +Replace Operations +~~~~~~~~~~~~~~~~~~ + +To specify an replace operation on the first matching document, call the +``replaceOne()`` method on your ``ClientBulkWrite`` instance. + +The following example specifies a replace operation on the first document +in the ``sample_restaurants.restaurants`` collection that has a ``name`` +value of ``'Dandelion Bakery'``: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-replace-one + :end-before: end-bulk-client-replace-one + :language: php + :copyable: + :dedent: + +Delete Operations +~~~~~~~~~~~~~~~~~ + +To specify an delete operation on the first matching document, call the +``deleteOne()`` method on your ``ClientBulkWrite`` instance. + +The following example specifies the deletion of the first document +in the ``sample_restaurants.restaurants`` collection that has a ``borough`` +value of ``'Queens'``: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-delete-one + :end-before: end-bulk-client-delete-one + :language: php + :copyable: + :dedent: + +To delete multiple documents, call the ``deleteMany()`` method. The specified +operation deletes *all documents* that match the query filter. + +The following example specifies the deletion of all documents +in the ``sample_restaurants.restaurants`` collection that have a ``name`` +value that contains two consecutive ``'p'`` characters: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-delete-many + :end-before: end-bulk-client-delete-many + :language: php + :copyable: + :dedent: + +.. _php-client-bulkwrite-method: + +Perform the Bulk Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you construct the ``ClientBulkWrite`` instance to specify your +write operations, pass it to the ``MongoDB\Client::bulkWrite()`` method. +By default, these methods run the operations in the order you defined +when constructing ``ClientBulkWrite``. + +The following code demonstrates how to use the ``bulkWrite()`` method +to perform a bulk write operation on multiple namespaces: + +.. io-code-block:: + :copyable: + + .. input:: /includes/write/bulk-write.php + :start-after: start-bulk-client + :end-before: end-bulk-client + :language: php + :emphasize-lines: 30 + :dedent: + + .. output:: + :visible: false + + Inserted documents: 2 + Modified documents: 2 + Deleted documents: 200 + +.. _php-client-bulk-write-options: + +Customize Bulk Write +~~~~~~~~~~~~~~~~~~~~ + +You can modify the behavior of the client bulk write operation by +passing an array to the ``ClientBulkWrite`` constructor that specifies +option values as a parameter. The following table describes the options +you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``bypassDocumentValidation`` + - | Specifies whether the operation bypasses document validation. This lets you + modify documents that don't meet the schema validation requirements, if any + exist. For more information about schema validation, see :manual:`Schema + Validation ` in the {+mdb-server+} + manual. + | The default is ``false``. + + * - ``comment`` + - | Attaches a comment to the operation. For more information, see the :manual:`insert command + fields ` guide in the + {+mdb-server+} manual. + + * - ``let`` + - | Specifies a document with a list of values to improve operation readability. + Values must be constant or closed expressions that don't reference document + fields. For more information, see the :manual:`let statement + ` in the + {+mdb-server+} manual. + + * - ``ordered`` + - | If set to ``true``: When a single write fails, the operation stops without + performing the remaining writes and throws an exception. + | If set to ``false``: When a single write fails, the operation continues to + attempt the remaining write operations, if any, then throws an exception. + | The default is ``true``. + + * - ``verboseResults`` + - | Specifies whether to return verbose results. + | The default is ``false``. + +The following example creates a ``ClientBulkWrite`` instance and sets +the ``ordered`` option to ``false``: + +.. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-options + :end-before: end-bulk-client-options + :language: php + :dedent: + +.. note:: Unordered Behavior + + Unordered bulk operations do not guarantee order of execution. The order can + differ from the way you list them to optimize the runtime. Suppose + you specify the following write operations in an unordered bulk write: + + .. literalinclude:: /includes/write/bulk-write.php + :start-after: start-bulk-client-unordered-behavior + :end-before: end-bulk-client-unordered-behavior + :language: php + :dedent: + + Because the library might run either operation first, the result + can show one deleted document or no deleted documents. + +You can also pass options when calling the ``bulkWrite()`` method to specify +the client session or the write concern to use for the operation. + +Return Value +~~~~~~~~~~~~ + +The ``MongoDB\Client::bulkWrite()`` method returns a ``MongoDB\BulkWriteCommandResult`` +object. This class contains the following methods: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Method + - Description + + * - ``getInsertedCount()`` + - | Returns the total number of documents inserted by all + insert operations in the bulk write command. + + * - ``getMatchedCount()`` + - | Returns the total number of documents matched by all + update and replace operations in the bulk write command. + + * - ``getModifiedCount()`` + - | Returns the total number of documents modified by all update + and replace operations in the bulk write command. + + * - ``getUpsertedCount()`` + - | Returns the total number of documents upserted by all update + and replace operations in the bulk write command. + + * - ``getDeletedCount()`` + - | Return the total number of documents deleted by all delete + operations in the bulk write command. + + * - ``getInsertResults()`` + - | Returns a map of results of each successful insert operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation such + as the inserted ``_id`` value. + + * - ``getUpdateResults()`` + - | Returns a map of results of each successful update operation. Each + operation is represented by an integer key, which contains a + document with information corresponding to the operation. + + * - ``getDeleteResults()`` + - | Returns a map of results of each successful delete operation. + Each operation is represented by an integer key, which contains + a document with information corresponding to the operation. + + * - ``isAcknowledged()`` + - | Returns a boolean indicating whether the server acknowledged + the bulk operation. + +.. _php-coll-bulk-write: + +Collection Bulk Write +--------------------- To run a bulk write operation, pass an array of write operations to the -``MongoDB\Collection::bulkWrite()`` method. Use the following syntax to +:phpmethod:`MongoDB\Collection::bulkWrite()` method. Use the following syntax to specify the write operations: .. code-block:: php @@ -67,13 +381,13 @@ specify the write operations: .. tip:: - For more information about delete, insert, replace, and update - operations, see the :ref:`Write operation guides `. + To learn more about delete, insert, replace, and update + operations, see the guides in the :ref:`php-write` section. When you call the ``bulkWrite()`` method, the library automatically runs the -write operations in the order they're specified in the array. To learn how to +write operations in the order you specify in the array. To learn how to instruct ``bulkWrite()`` to run the write operations in an arbitrary order, -see the :ref:`php-bulk-modify` section. +see the :ref:`php-bulk-collection-modify` section. Example ~~~~~~~ @@ -96,10 +410,16 @@ collection: :language: php :dedent: -.. _php-bulk-modify: +.. note:: + + When the library runs a bulk operation, it uses the write concern of the + target collection. The driver reports all write concern errors after + attempting all operations, regardless of execution order. + +.. _php-bulk-collection-modify: -Modify Bulk Write Behavior --------------------------- +Customize Bulk Write Operation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can modify the behavior of the ``MongoDB\Collection::bulkWrite()`` method by passing an array that specifies option values as a parameter. The following table @@ -118,7 +438,7 @@ describes the options you can set in the array: exist. For more information about schema validation, see :manual:`Schema Validation ` in the {+mdb-server+} manual. - | Defaults to ``false``. + | The default is ``false``. * - ``codec`` - | Sets the codec to use for encoding or decoding documents. Bulk writes @@ -138,11 +458,11 @@ describes the options you can set in the array: {+mdb-server+} manual. * - ``ordered`` - - | If set to ``true``: when a single write fails, the operation stops without + - | If set to ``true``: When a single write fails, the operation stops without performing the remaining writes and throws an exception. - | If set to ``false``: when a single write fails, the operation continues to + | If set to ``false``: When a single write fails, the operation continues to attempt the remaining write operations, if any, then throws an exception. - | Defaults to ``true``. + | The default is ``true``. * - ``comment`` - | Attaches a comment to the operation. For more information, see the :manual:`insert command @@ -165,50 +485,58 @@ insert and delete operation and sets the ``ordered`` option to If the library runs the insert operation first, one document is deleted. If it runs the delete operation first, no documents are deleted. -.. note:: +.. note:: Unordered Behavior Unordered bulk operations do not guarantee order of execution. The order can differ from the way you list them to optimize the runtime. -.. _php-bulk-return-value: +.. _php-bulk-collection-return-value: Return Value ------------- +~~~~~~~~~~~~ The ``MongoDB\Collection::bulkWrite()`` method returns a ``MongoDB\BulkWriteResult`` -object. This class contains the following member functions: +object. This class contains the following methods: .. list-table:: :widths: 30 70 :header-rows: 1 - * - Function + * - Method - Description - * - ``getDeletedCount()`` - - | Returns the number of documents deleted, if any. - * - ``getInsertedCount()`` - - | Returns the number of documents inserted, if any. + - | Returns the total number of documents inserted by all + insert operations in the bulk write command. * - ``getInsertedIds()`` - - | Returns a map of ``_id`` field values for inserted documents, if any. + - | Returns a map of ``_id`` field values for documents + inserted by all insert operations in the bulk write command. * - ``getMatchedCount()`` - - | Returns the number of documents matched during update and replace - operations, if applicable. + - | Returns the total number of documents matched by all + update and replace operations in the bulk write command. * - ``getModifiedCount()`` - - | Returns the number of documents modified, if any. + - | Returns the total number of documents modified by all update + and replace operations in the bulk write command. * - ``getUpsertedCount()`` - - | Returns the number of documents upserted, if any. + - | Returns the total number of documents upserted by all update + and replace operations in the bulk write command. * - ``getUpsertedIds()`` - - | Returns a map of ``_id`` field values for upserted documents, if any. + - | Returns a map of ``_id`` field values for documents + upserted by all update and replace operations in the bulk write + command. + + * - ``getDeletedCount()`` + - | Return the total number of documents deleted by all delete + operations in the bulk write command. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the bulk operation was acknowledged. + - | Returns a boolean indicating whether the server acknowledged + the bulk operation. Additional Information ---------------------- @@ -226,5 +554,13 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- :phpmethod:`MongoDB\Collection::bulkWrite()` -- :phpclass:`MongoDB\BulkWriteResult` \ No newline at end of file +- Client Bulk Write + + - :phpclass:`MongoDB\ClientBulkWrite` + - :phpmethod:`MongoDB\Client::bulkWrite()` + - :phpclass:`MongoDB\BulkWriteCommandResult` + +- Collection Bulk Write + + - :phpmethod:`MongoDB\Collection::bulkWrite()` + - :phpclass:`MongoDB\BulkWriteResult` diff --git a/source/write/replace.txt b/source/write/replace.txt index 5c3ba370..60f60601 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -96,7 +96,8 @@ methods: performed an upsert. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the write operation was acknowledged. + - | Returns a boolean indicating whether the server acknowledged + the write operation. Example ~~~~~~~ diff --git a/source/write/transaction.txt b/source/write/transaction.txt index 5a929cc0..f789683e 100644 --- a/source/write/transaction.txt +++ b/source/write/transaction.txt @@ -163,6 +163,14 @@ completes the following actions: .. sharedinclude:: dbx/transactions-parallelism.rst + .. replacement:: driver-specific-content + + If you're using {+library-short+} v2.1 or later and {+mdb-server+} + v8.0 or later, you can perform write operations on multiple + namespaces within a single transaction by using the + :phpmethod:`MongoDB\Client::bulkWrite()` method. For more + information, see :ref:`php-bulk-write`. + Additional Information ---------------------- diff --git a/source/write/update.txt b/source/write/update.txt index b6e22d02..d70b6f5a 100644 --- a/source/write/update.txt +++ b/source/write/update.txt @@ -190,7 +190,8 @@ member functions: count. * - ``isAcknowledged()`` - - | Returns a boolean indicating whether the write operation was acknowledged. + - | Returns a boolean indicating whether the server acknowledged + the write operation. * - ``getUpsertedCount()`` - | Returns the number of document that were upserted into the database. From a15a2c945998901195a50fe221089f14ab84c5ea Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Thu, 22 May 2025 13:32:43 -0400 Subject: [PATCH 10/12] DOCSP-50022: remove eol server version mentions (#253) * DOCSP-50022: remove eol server version mentions * consolidate compat table rows --- source/connect/stable-api.txt | 4 +-- source/connect/tls.txt | 18 ++++------ source/databases-collections/time-series.txt | 2 +- source/includes/extracts-common-option.yaml | 9 +++-- source/includes/extracts-option-requires.yaml | 35 +++---------------- source/includes/extracts-watch-option.yaml | 20 +++++------ .../mongodb-compatibility-table-php.rst | 34 +----------------- .../method/MongoDBClient-dropDatabase.txt | 2 +- .../MongoDBClient-listDatabaseNames.txt | 10 +++--- .../method/MongoDBClient-listDatabases.txt | 10 +++--- .../reference/method/MongoDBClient-watch.txt | 2 +- .../method/MongoDBCollection-aggregate.txt | 3 +- .../method/MongoDBCollection-bulkWrite.txt | 2 +- .../method/MongoDBCollection-count.txt | 2 +- .../MongoDBCollection-countDocuments.txt | 2 +- .../method/MongoDBCollection-createIndex.txt | 5 ++- .../MongoDBCollection-createIndexes.txt | 5 ++- .../method/MongoDBCollection-deleteMany.txt | 4 +-- .../method/MongoDBCollection-deleteOne.txt | 4 +-- .../method/MongoDBCollection-distinct.txt | 2 +- .../method/MongoDBCollection-drop.txt | 2 +- .../method/MongoDBCollection-dropIndex.txt | 2 +- .../method/MongoDBCollection-dropIndexes.txt | 2 +- ...ngoDBCollection-estimatedDocumentCount.txt | 10 +++--- .../method/MongoDBCollection-explain.txt | 2 +- .../method/MongoDBCollection-find.txt | 2 +- .../method/MongoDBCollection-findOne.txt | 2 +- .../MongoDBCollection-findOneAndDelete.txt | 4 +-- .../MongoDBCollection-findOneAndReplace.txt | 4 +-- .../MongoDBCollection-findOneAndUpdate.txt | 8 ++--- .../method/MongoDBCollection-insertMany.txt | 2 +- .../method/MongoDBCollection-insertOne.txt | 2 +- .../method/MongoDBCollection-listIndexes.txt | 2 +- .../method/MongoDBCollection-rename.txt | 2 +- .../method/MongoDBCollection-replaceOne.txt | 4 +-- .../method/MongoDBCollection-updateMany.txt | 8 ++--- .../method/MongoDBCollection-updateOne.txt | 8 ++--- .../method/MongoDBCollection-watch.txt | 7 ++-- .../method/MongoDBDatabase-aggregate.txt | 3 +- .../MongoDBDatabase-createCollection.txt | 8 ++--- .../reference/method/MongoDBDatabase-drop.txt | 2 +- .../method/MongoDBDatabase-dropCollection.txt | 2 +- .../MongoDBDatabase-listCollectionNames.txt | 4 +-- .../MongoDBDatabase-listCollections.txt | 4 +-- .../MongoDBDatabase-modifyCollection.txt | 2 +- .../MongoDBDatabase-renameCollection.txt | 2 +- .../method/MongoDBDatabase-watch.txt | 2 +- .../method/MongoDBGridFSBucket-find.txt | 2 +- .../method/MongoDBGridFSBucket-findOne.txt | 2 +- source/security.txt | 29 --------------- source/security/authentication.txt | 28 +++------------ source/security/in-use-encryption.txt | 15 ++++---- source/tutorial/encryption.txt | 11 +++--- 53 files changed, 120 insertions(+), 244 deletions(-) diff --git a/source/connect/stable-api.txt b/source/connect/stable-api.txt index e00eeb55..6ce89a77 100644 --- a/source/connect/stable-api.txt +++ b/source/connect/stable-api.txt @@ -19,7 +19,7 @@ .. note:: - The {+stable-api+} feature requires {+mdb-server+} 5.0 or later. + The {+stable-api+} feature requires {+mdb-server+} 6.0 or later. Overview -------- @@ -116,4 +116,4 @@ API documentation: For more information about the ``MongoDB\Driver\ServerApi`` class, see the following {+extension-short+} API documentation: -- :php:`MongoDB\Driver\ServerApi ` \ No newline at end of file +- :php:`MongoDB\Driver\ServerApi ` diff --git a/source/connect/tls.txt b/source/connect/tls.txt index e8051122..3a7b0dca 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -127,17 +127,11 @@ to check whether a server's certificate has been revoked. OCSP ~~~~ -The Online Certificate Status Protocol (OCSP) process varies depending on the version of -{+mdb-server+} you're connecting to: - -- **MongoDB v4.4 or later:** The server staples a - time-stamped OCSP response to its certificate. The {+library-short+} validates the certificate - against the OCSP response. If the CA has revoked the certificate, or if the OCSP response - is otherwise invalid, the TLS handshake fails. -- **MongoDB v4.3 or earlier:** The server supplies an OCSP endpoint, which the {+library-short+} - contacts directly. The {+library-short+} then validates the certificate against the OCSP - response. If the CA hasn't revoked the certificate, the TLS handshake continues, even if - the OCSP response is invalid or malformed. +The Online Certificate Status Protocol (OCSP) process specifies that the +server staples a time-stamped OCSP response to its certificate. The +{+library-short+} validates the certificate against the OCSP response. +If the CA has revoked the certificate, or if the OCSP response is +otherwise invalid, the TLS handshake fails. To stop the {+library-short+} from contacting the OCSP endpoint, set the ``tlsDisableOCSPEndpointCheck`` connection option to ``true``. @@ -265,4 +259,4 @@ API Documentation To learn more about configuring TLS for the {+library-short+}, see the following API documentation: -- :phpclass:`MongoDB\Client` \ No newline at end of file +- :phpclass:`MongoDB\Client` diff --git a/source/databases-collections/time-series.txt b/source/databases-collections/time-series.txt index 9c21e2e3..69f923c4 100644 --- a/source/databases-collections/time-series.txt +++ b/source/databases-collections/time-series.txt @@ -60,7 +60,7 @@ Create a Time Series Collection .. important:: Server Version for Time Series Collections To create and interact with time series collections, you must be - connected to a deployment running {+mdb-server+} 5.0 or later. + connected to a deployment running {+mdb-server+} 6.0 or later. You can create a time series collection to store time series data. To create a time series collection, pass an options array to the diff --git a/source/includes/extracts-common-option.yaml b/source/includes/extracts-common-option.yaml index 68702d6e..f75bcd15 100644 --- a/source/includes/extracts-common-option.yaml +++ b/source/includes/extracts-common-option.yaml @@ -18,9 +18,9 @@ content: | :manual:`currentOp ` output, and :manual:`logs `. --- -ref: common-option-comment-string-before-4.4 +ref: common-option-comment-string-before-6.0 content: | - The comment can be any valid BSON type since MongoDB 4.4. Earlier server + The comment can be any valid BSON type starting in MongoDB 6.0. Earlier server versions only support string values. --- ref: common-option-hint @@ -35,8 +35,8 @@ content: | expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. ``$$var``). - This is not supported for server versions prior to 5.0 and will result in an - exception at execution time if used. + This feature is not supported for MongoDB server versions 6.0 and + earlier. If used, the server returns an exception at execution time. --- ref: common-option-maxTimeMS content: | @@ -88,4 +88,3 @@ content: | It is not possible to specify a write concern for individual operations as part of a transaction. Instead, set the ``writeConcern`` option when :php:`starting the transaction `. -... diff --git a/source/includes/extracts-option-requires.yaml b/source/includes/extracts-option-requires.yaml index 485ea899..7f0ab80b 100644 --- a/source/includes/extracts-option-requires.yaml +++ b/source/includes/extracts-option-requires.yaml @@ -1,35 +1,8 @@ ref: _option-requires-version content: | - This option is available since MongoDB {{version}} and will result in an - exception at execution time if specified for an older server version. ---- -ref: option-requires-4.2 -source: - file: extracts-option-requires.yaml - ref: _option-requires-version -replacement: - version: "4.2" ---- -ref: option-requires-4.4 -source: - file: extracts-option-requires.yaml - ref: _option-requires-version -replacement: - version: "4.4" ---- -ref: option-requires-5.0 -source: - file: extracts-option-requires.yaml - ref: _option-requires-version -replacement: - version: "5.0" ---- -ref: option-requires-5.3 -source: - file: extracts-option-requires.yaml - ref: _option-requires-version -replacement: - version: "5.3" + To use this option, you must connect to MongoDB {{version}} or later. + If you are connected to an earlier version, the server returns an + exception at execution time. --- ref: option-requires-6.0 source: @@ -44,5 +17,5 @@ source: ref: _option-requires-version replacement: version: "7.0" -... +--- diff --git a/source/includes/extracts-watch-option.yaml b/source/includes/extracts-watch-option.yaml index debf2014..0b38cc7b 100644 --- a/source/includes/extracts-watch-option.yaml +++ b/source/includes/extracts-watch-option.yaml @@ -24,9 +24,9 @@ content: | Specify "updateLookup" to return the current majority-committed version of the updated document. - MongoDB 6.0+ allows returning the post-image of the modified document if the + Starting in MongoDB 6.0, you can access the post-image of the modified document if the collection has ``changeStreamPreAndPostImages`` enabled. Specify - "whenAvailable" to return the post-image if available or a null value if not. + ``whenAvailable`` to return the post-image if available or a null value if not. Specify "required" to return the post-image if available or raise an error if not. @@ -105,8 +105,9 @@ content: | ``startAtOperationTime`` will result in a server error. The options are mutually exclusive. - This is not supported for server versions prior to 4.2 and will result in an - exception at execution time if used. + To use this option, you must connect to MongoDB 6.0 or later. + If you are connected to an earlier version, the server returns an + exception at execution time. This is an option of the ``$changeStream`` pipeline stage. @@ -115,15 +116,14 @@ content: | ref: watch-option-startAtOperationTime content: | If specified, the change stream will only provide changes that occurred at or - after the specified timestamp. Command responses from a MongoDB 4.0+ server - include an ``operationTime`` that can be used here. By default, the - ``operationTime`` returned by the initial ``aggregate`` command will be used - if available. + after the specified timestamp. By default, the ``operationTime`` + returned by the initial ``aggregate`` command will be used if available. Using this option in conjunction with ``resumeAfter`` and/or ``startAfter`` will result in a server error. The options are mutually exclusive. - This is not supported for server versions prior to 4.0 and will result in an - exception at execution time if used. + To use this option, you must connect to MongoDB 6.0 or later. + If you are connected to an earlier version, the server returns an + exception at execution time. This is an option of the ``$changeStream`` pipeline stage. diff --git a/source/includes/mongodb-compatibility-table-php.rst b/source/includes/mongodb-compatibility-table-php.rst index cdcba413..ae7fd69a 100644 --- a/source/includes/mongodb-compatibility-table-php.rst +++ b/source/includes/mongodb-compatibility-table-php.rst @@ -7,50 +7,18 @@ - MongoDB 8.0 - MongoDB 7.0 - MongoDB 6.0 - - MongoDB 5.0 - - MongoDB 4.4 - - MongoDB 4.2 - - MongoDB 4.0 - - MongoDB 3.6 - * - ext + lib 1.21 to 2.0 + * - ext + lib 1.20 to 2.0 - ✓ - ✓ - ✓ - - ✓ - - ✓ - - ✓ - - ✓ [#deprecation-note]_ - - - - * - ext + lib 1.20 - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - * - ext + lib 1.16 to 1.19 - ⊛ - ✓ - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ * - ext + lib 1.15 - ⊛ - ⊛ - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - - ✓ - -.. [#deprecation-note] Support for this MongoDB version is deprecated and will be removed in a future release. diff --git a/source/reference/method/MongoDBClient-dropDatabase.txt b/source/reference/method/MongoDBClient-dropDatabase.txt index d5420e3b..e37d0b7c 100644 --- a/source/reference/method/MongoDBClient-dropDatabase.txt +++ b/source/reference/method/MongoDBClient-dropDatabase.txt @@ -43,7 +43,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBClient-listDatabaseNames.txt b/source/reference/method/MongoDBClient-listDatabaseNames.txt index 47ba4978..89f32e23 100644 --- a/source/reference/method/MongoDBClient-listDatabaseNames.txt +++ b/source/reference/method/MongoDBClient-listDatabaseNames.txt @@ -42,10 +42,10 @@ Parameters * - authorizedDatabases - boolean - A flag that determines which databases are returned based on the user - privileges when access control is enabled. For more information, see the - `listDatabases command documentation `_. - - For servers < 4.0.5, this option is ignored. + privileges when access control is enabled. To learn more, see the + :manual:`listDatabases command + ` reference in the + {+mdb-server+} manual. .. versionadded:: 1.7 @@ -53,7 +53,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBClient-listDatabases.txt b/source/reference/method/MongoDBClient-listDatabases.txt index baada43b..12cb8eb1 100644 --- a/source/reference/method/MongoDBClient-listDatabases.txt +++ b/source/reference/method/MongoDBClient-listDatabases.txt @@ -39,10 +39,10 @@ Parameters * - authorizedDatabases - boolean - A flag that determines which databases are returned based on the user - privileges when access control is enabled. For more information, see the - `listDatabases command documentation `_. - - For servers < 4.0.5, this option is ignored. + privileges when access control is enabled. To learn more, see the + :manual:`listDatabases command + ` reference in the + {+mdb-server+} manual. .. versionadded:: 1.7 @@ -50,7 +50,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBClient-watch.txt b/source/reference/method/MongoDBClient-watch.txt index 8bf455d2..1aff1e71 100644 --- a/source/reference/method/MongoDBClient-watch.txt +++ b/source/reference/method/MongoDBClient-watch.txt @@ -64,7 +64,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-aggregate.txt b/source/reference/method/MongoDBCollection-aggregate.txt index 24080b45..c31065b5 100644 --- a/source/reference/method/MongoDBCollection-aggregate.txt +++ b/source/reference/method/MongoDBCollection-aggregate.txt @@ -87,8 +87,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - The comment can be any valid BSON type for server versions 4.4 and - above. Earlier server versions only support string values. + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst .. versionadded:: 1.3 diff --git a/source/reference/method/MongoDBCollection-bulkWrite.txt b/source/reference/method/MongoDBCollection-bulkWrite.txt index 2f607ea4..c4804568 100644 --- a/source/reference/method/MongoDBCollection-bulkWrite.txt +++ b/source/reference/method/MongoDBCollection-bulkWrite.txt @@ -92,7 +92,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-count.txt b/source/reference/method/MongoDBCollection-count.txt index 5e0d3112..763b86c7 100644 --- a/source/reference/method/MongoDBCollection-count.txt +++ b/source/reference/method/MongoDBCollection-count.txt @@ -53,7 +53,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-countDocuments.txt b/source/reference/method/MongoDBCollection-countDocuments.txt index dc882777..fceef0ef 100644 --- a/source/reference/method/MongoDBCollection-countDocuments.txt +++ b/source/reference/method/MongoDBCollection-countDocuments.txt @@ -50,7 +50,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst * - hint - string|array|object diff --git a/source/reference/method/MongoDBCollection-createIndex.txt b/source/reference/method/MongoDBCollection-createIndex.txt index e99712f6..94c71e01 100644 --- a/source/reference/method/MongoDBCollection-createIndex.txt +++ b/source/reference/method/MongoDBCollection-createIndex.txt @@ -93,7 +93,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -107,8 +107,7 @@ Parameters concern plus ``"votingMembers"``, which indicates all voting data-bearing nodes. - This is not supported for server versions prior to 4.4 and will result - in an exception at execution time if used. + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBCollection-createIndexes.txt b/source/reference/method/MongoDBCollection-createIndexes.txt index dc6d2f5a..e1256080 100644 --- a/source/reference/method/MongoDBCollection-createIndexes.txt +++ b/source/reference/method/MongoDBCollection-createIndexes.txt @@ -56,7 +56,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -70,8 +70,7 @@ Parameters concern plus ``"votingMembers"``, which indicates all voting data-bearing nodes. - This is not supported for server versions prior to 4.4 and will result - in an exception at execution time if used. + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBCollection-deleteMany.txt b/source/reference/method/MongoDBCollection-deleteMany.txt index 0f38e058..ebf33912 100644 --- a/source/reference/method/MongoDBCollection-deleteMany.txt +++ b/source/reference/method/MongoDBCollection-deleteMany.txt @@ -51,7 +51,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -59,7 +59,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBCollection-deleteOne.txt b/source/reference/method/MongoDBCollection-deleteOne.txt index a479f237..017abe0d 100644 --- a/source/reference/method/MongoDBCollection-deleteOne.txt +++ b/source/reference/method/MongoDBCollection-deleteOne.txt @@ -53,7 +53,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -61,7 +61,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBCollection-distinct.txt b/source/reference/method/MongoDBCollection-distinct.txt index 045b3012..abe63bf3 100644 --- a/source/reference/method/MongoDBCollection-distinct.txt +++ b/source/reference/method/MongoDBCollection-distinct.txt @@ -55,7 +55,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-drop.txt b/source/reference/method/MongoDBCollection-drop.txt index a7a9df1f..1834f367 100644 --- a/source/reference/method/MongoDBCollection-drop.txt +++ b/source/reference/method/MongoDBCollection-drop.txt @@ -41,7 +41,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-dropIndex.txt b/source/reference/method/MongoDBCollection-dropIndex.txt index bbbff49c..114a3502 100644 --- a/source/reference/method/MongoDBCollection-dropIndex.txt +++ b/source/reference/method/MongoDBCollection-dropIndex.txt @@ -47,7 +47,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-dropIndexes.txt b/source/reference/method/MongoDBCollection-dropIndexes.txt index cad32dcc..b8ed93e4 100644 --- a/source/reference/method/MongoDBCollection-dropIndexes.txt +++ b/source/reference/method/MongoDBCollection-dropIndexes.txt @@ -45,7 +45,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt b/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt index 542d8c2f..a86d873f 100644 --- a/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt +++ b/source/reference/method/MongoDBCollection-estimatedDocumentCount.txt @@ -43,7 +43,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -89,10 +89,10 @@ within a transaction. See in the MongoDB manual for more information. This method is implemented using the :manual:`count ` -command. Due to an oversight in versions 5.0.0-5.0.8 of MongoDB, the ``count`` -command was not included in version "1" of the Stable API. Applications using -this method with the Stable API are recommended to upgrade their server version -to 5.0.9+ or disable strict mode to avoid encountering errors. +command. The ``count`` command *is not* included in version ``1`` of the +{+stable-api+}. If you enable the {+stable-api+} and want to use this +method, upgrade your server version to MongoDB 6.0 or disable strict +mode to avoid encountering errors. See Also -------- diff --git a/source/reference/method/MongoDBCollection-explain.txt b/source/reference/method/MongoDBCollection-explain.txt index 52c2520f..da0fa69e 100644 --- a/source/reference/method/MongoDBCollection-explain.txt +++ b/source/reference/method/MongoDBCollection-explain.txt @@ -49,7 +49,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst Defaults to the ``comment`` of the explained operation (if any). diff --git a/source/reference/method/MongoDBCollection-find.txt b/source/reference/method/MongoDBCollection-find.txt index 34cd979f..b529af7f 100644 --- a/source/reference/method/MongoDBCollection-find.txt +++ b/source/reference/method/MongoDBCollection-find.txt @@ -81,7 +81,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst * - cursorType - integer diff --git a/source/reference/method/MongoDBCollection-findOne.txt b/source/reference/method/MongoDBCollection-findOne.txt index 99aca91c..5fc6e59f 100644 --- a/source/reference/method/MongoDBCollection-findOne.txt +++ b/source/reference/method/MongoDBCollection-findOne.txt @@ -67,7 +67,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst * - hint - string|array|object diff --git a/source/reference/method/MongoDBCollection-findOneAndDelete.txt b/source/reference/method/MongoDBCollection-findOneAndDelete.txt index a1eb75cb..f375890a 100644 --- a/source/reference/method/MongoDBCollection-findOneAndDelete.txt +++ b/source/reference/method/MongoDBCollection-findOneAndDelete.txt @@ -51,7 +51,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -59,7 +59,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBCollection-findOneAndReplace.txt b/source/reference/method/MongoDBCollection-findOneAndReplace.txt index 68c862a4..cee9f3ef 100644 --- a/source/reference/method/MongoDBCollection-findOneAndReplace.txt +++ b/source/reference/method/MongoDBCollection-findOneAndReplace.txt @@ -66,7 +66,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -74,7 +74,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBCollection-findOneAndUpdate.txt b/source/reference/method/MongoDBCollection-findOneAndUpdate.txt index c48db888..67d14251 100644 --- a/source/reference/method/MongoDBCollection-findOneAndUpdate.txt +++ b/source/reference/method/MongoDBCollection-findOneAndUpdate.txt @@ -36,8 +36,8 @@ Parameters ``$update`` : array|object Specifies the field and value combinations to update and any relevant update operators. ``$update`` uses MongoDB's :manual:`update operators - `. Starting with MongoDB 4.2, an `aggregation - pipeline `_ + `. You can also pass an :manual:`aggregation + pipeline ` can be passed as this parameter. ``$options`` : array @@ -71,7 +71,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -79,7 +79,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.7 diff --git a/source/reference/method/MongoDBCollection-insertMany.txt b/source/reference/method/MongoDBCollection-insertMany.txt index 4e07aa0a..abc2ac75 100644 --- a/source/reference/method/MongoDBCollection-insertMany.txt +++ b/source/reference/method/MongoDBCollection-insertMany.txt @@ -58,7 +58,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-insertOne.txt b/source/reference/method/MongoDBCollection-insertOne.txt index aa92ba9f..dd73aa60 100644 --- a/source/reference/method/MongoDBCollection-insertOne.txt +++ b/source/reference/method/MongoDBCollection-insertOne.txt @@ -58,7 +58,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-listIndexes.txt b/source/reference/method/MongoDBCollection-listIndexes.txt index de289989..272edc91 100644 --- a/source/reference/method/MongoDBCollection-listIndexes.txt +++ b/source/reference/method/MongoDBCollection-listIndexes.txt @@ -40,7 +40,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-rename.txt b/source/reference/method/MongoDBCollection-rename.txt index 720c4d34..6e4c2337 100644 --- a/source/reference/method/MongoDBCollection-rename.txt +++ b/source/reference/method/MongoDBCollection-rename.txt @@ -60,7 +60,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBCollection-replaceOne.txt b/source/reference/method/MongoDBCollection-replaceOne.txt index 13797018..92c14ca2 100644 --- a/source/reference/method/MongoDBCollection-replaceOne.txt +++ b/source/reference/method/MongoDBCollection-replaceOne.txt @@ -67,7 +67,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -75,7 +75,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.2.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.6 diff --git a/source/reference/method/MongoDBCollection-updateMany.txt b/source/reference/method/MongoDBCollection-updateMany.txt index 86d1d2a2..bdb37bb5 100644 --- a/source/reference/method/MongoDBCollection-updateMany.txt +++ b/source/reference/method/MongoDBCollection-updateMany.txt @@ -36,8 +36,8 @@ Parameters ``$update`` : array|object Specifies the field and value combinations to update and any relevant update operators. ``$update`` uses MongoDB's :manual:`update operators `. - Starting with MongoDB 4.2, an `aggregation pipeline - `_ + You can also pass an :manual:`aggregation pipeline + ` can be passed as this parameter. ``$options`` : array @@ -71,7 +71,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -79,7 +79,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.2.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.6 diff --git a/source/reference/method/MongoDBCollection-updateOne.txt b/source/reference/method/MongoDBCollection-updateOne.txt index 131ac036..7a701a9b 100644 --- a/source/reference/method/MongoDBCollection-updateOne.txt +++ b/source/reference/method/MongoDBCollection-updateOne.txt @@ -37,8 +37,8 @@ Parameters ``$update`` : array|object Specifies the field and value combinations to update and any relevant update operators. ``$update`` uses MongoDB's :manual:`update operators - `. Starting with MongoDB 4.2, an `aggregation - pipeline `_ + `. You can also pass an :manual:`aggregation + pipeline ` can be passed as this parameter. ``$options`` : array @@ -72,7 +72,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -80,7 +80,7 @@ Parameters - string|array|object - .. include:: /includes/extracts/common-option-hint.rst - .. include:: /includes/extracts/option-requires-4.2.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.6 diff --git a/source/reference/method/MongoDBCollection-watch.txt b/source/reference/method/MongoDBCollection-watch.txt index 6510930b..90223dd3 100644 --- a/source/reference/method/MongoDBCollection-watch.txt +++ b/source/reference/method/MongoDBCollection-watch.txt @@ -60,15 +60,14 @@ Parameters - array|object - .. include:: /includes/extracts/common-option-collation.rst - Starting in MongoDB 4.2, defaults to simple binary comparison if - omitted. In earlier versions, change streams opened on a single - collection would inherit the collection's default collation. + This option defaults to simple binary comparison if + omitted. * - comment - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBDatabase-aggregate.txt b/source/reference/method/MongoDBDatabase-aggregate.txt index 72dfc7b2..533495c9 100644 --- a/source/reference/method/MongoDBDatabase-aggregate.txt +++ b/source/reference/method/MongoDBDatabase-aggregate.txt @@ -88,8 +88,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - The comment can be any valid BSON type for server versions 4.4 and - above. Earlier server versions only support string values. + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst * - explain - boolean diff --git a/source/reference/method/MongoDBDatabase-createCollection.txt b/source/reference/method/MongoDBDatabase-createCollection.txt index f78d61eb..481c2a5a 100644 --- a/source/reference/method/MongoDBDatabase-createCollection.txt +++ b/source/reference/method/MongoDBDatabase-createCollection.txt @@ -79,7 +79,7 @@ Parameters :manual:`create ` command documentation for more information. - .. include:: /includes/extracts/option-requires-5.3.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -91,7 +91,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 @@ -113,7 +113,7 @@ Parameters the :manual:`create ` command documentation for more information. - .. include:: /includes/extracts/option-requires-5.0.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.9 @@ -191,7 +191,7 @@ Parameters the :manual:`create ` command documentation for supported options. - .. include:: /includes/extracts/option-requires-5.0.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.9 diff --git a/source/reference/method/MongoDBDatabase-drop.txt b/source/reference/method/MongoDBDatabase-drop.txt index 18ece835..651a0584 100644 --- a/source/reference/method/MongoDBDatabase-drop.txt +++ b/source/reference/method/MongoDBDatabase-drop.txt @@ -37,7 +37,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBDatabase-dropCollection.txt b/source/reference/method/MongoDBDatabase-dropCollection.txt index 5721509e..97ef7839 100644 --- a/source/reference/method/MongoDBDatabase-dropCollection.txt +++ b/source/reference/method/MongoDBDatabase-dropCollection.txt @@ -43,7 +43,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBDatabase-listCollectionNames.txt b/source/reference/method/MongoDBDatabase-listCollectionNames.txt index b13bb84e..682c9223 100644 --- a/source/reference/method/MongoDBDatabase-listCollectionNames.txt +++ b/source/reference/method/MongoDBDatabase-listCollectionNames.txt @@ -43,15 +43,13 @@ Parameters the :manual:`listCollections ` command documentation. - For servers < 4.0, this option is ignored. - .. versionadded:: 1.12 * - comment - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBDatabase-listCollections.txt b/source/reference/method/MongoDBDatabase-listCollections.txt index cad71e2c..8f33aedf 100644 --- a/source/reference/method/MongoDBDatabase-listCollections.txt +++ b/source/reference/method/MongoDBDatabase-listCollections.txt @@ -40,15 +40,13 @@ Parameters the :manual:`listCollections ` command documentation. - For servers < 4.0, this option is ignored. - .. versionadded:: 1.12 * - comment - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBDatabase-modifyCollection.txt b/source/reference/method/MongoDBDatabase-modifyCollection.txt index 4a080c4e..144eb9a5 100644 --- a/source/reference/method/MongoDBDatabase-modifyCollection.txt +++ b/source/reference/method/MongoDBDatabase-modifyCollection.txt @@ -51,7 +51,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBDatabase-renameCollection.txt b/source/reference/method/MongoDBDatabase-renameCollection.txt index 87e38532..a6b0b904 100644 --- a/source/reference/method/MongoDBDatabase-renameCollection.txt +++ b/source/reference/method/MongoDBDatabase-renameCollection.txt @@ -56,7 +56,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/option-requires-4.4.rst + .. include:: /includes/extracts/option-requires-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBDatabase-watch.txt b/source/reference/method/MongoDBDatabase-watch.txt index 68f0d273..e93c9c3f 100644 --- a/source/reference/method/MongoDBDatabase-watch.txt +++ b/source/reference/method/MongoDBDatabase-watch.txt @@ -61,7 +61,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst .. versionadded:: 1.13 diff --git a/source/reference/method/MongoDBGridFSBucket-find.txt b/source/reference/method/MongoDBGridFSBucket-find.txt index 3ceac0a9..653848b0 100644 --- a/source/reference/method/MongoDBGridFSBucket-find.txt +++ b/source/reference/method/MongoDBGridFSBucket-find.txt @@ -76,7 +76,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst * - cursorType - integer diff --git a/source/reference/method/MongoDBGridFSBucket-findOne.txt b/source/reference/method/MongoDBGridFSBucket-findOne.txt index 54f22dea..6b564461 100644 --- a/source/reference/method/MongoDBGridFSBucket-findOne.txt +++ b/source/reference/method/MongoDBGridFSBucket-findOne.txt @@ -66,7 +66,7 @@ Parameters - mixed - .. include:: /includes/extracts/common-option-comment.rst - .. include:: /includes/extracts/common-option-comment-string-before-4.4.rst + .. include:: /includes/extracts/common-option-comment-string-before-6.0.rst * - hint - string|array|object diff --git a/source/security.txt b/source/security.txt index 249ae009..310321a9 100644 --- a/source/security.txt +++ b/source/security.txt @@ -80,35 +80,6 @@ authentication mechanism: To learn more about SCRAM-SHA-256 authentication, see :ref:`php-scram-sha-256` in the Authentication guide. -SCRAM-SHA-1 ------------ - -The following code shows how to authenticate by using the ``SCRAM-SHA-1`` -authentication mechanism: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/authentication.php - :language: php - :dedent: - :start-after: start-scram-sha-1-client - :end-before: end-scram-sha-1-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/authentication.php - :language: php - :dedent: - :start-after: start-scram-sha-1-uri - :end-before: end-scram-sha-1-uri - -To learn more about SCRAM-SHA-1 authentication, see :ref:`php-scram-sha-1` in -the Authentication guide. - MONGODB X.509 ------------- diff --git a/source/security/authentication.txt b/source/security/authentication.txt index f4be9f13..eb8c9770 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -42,8 +42,7 @@ SCRAM-SHA-256 ------------- SCRAM-SHA-256, as defined by `RFC 7677 `__, -is the default authentication mechanism on MongoDB deployments -running {+mdb-server+} v4.0 or later. +is the default authentication mechanism on MongoDB deployments. To authenticate with this mechanism, set the following connection options: @@ -54,8 +53,7 @@ To authenticate with this mechanism, set the following connection options: - ``authSource``: The MongoDB database to authenticate against. By default, the {+php-library+} authenticates against the database in the connection URI, if you include one. If you don't, it authenticates against the ``admin`` database. -- ``authMechanism``: Set to ``'SCRAM-SHA-256'``. When connected to {+mdb-server+} v4.0, - setting ``authMechanism`` is optional. +- ``authMechanism``: Set to ``'SCRAM-SHA-256'``. You can set these options in two ways: by passing an options array to the ``MongoDB\Client`` constructor or through parameters in your connection URI. @@ -80,24 +78,6 @@ You can set these options in two ways: by passing an options array to the :start-after: start-scram-sha-256-uri :end-before: end-scram-sha-256-uri -.. _php-scram-sha-1: - -SCRAM-SHA-1 ------------ - -SCRAM-SHA-1, as defined by `RFC 5802 `__, -is the default authentication mechanism on MongoDB deployments -running {+mdb-server+} v3.6. - -.. note:: - - {+php-library+} v1.20 drops support for {+mdb-server+} v3.6. When using v1.20+ of - the library, all supported server versions default to the SCRAM-SHA-256 authentication - mechanism. - -To authenticate with this mechanism, use the same syntax as the :ref:`php-scram-sha-256`, -but change the value of the ``authMechanism`` option to ``'SCRAM-SHA-1'``. - .. _php-mongodb-x509: MONGODB-X509 @@ -144,7 +124,7 @@ MONGODB-AWS .. important:: - The MONGODB-AWS authentication mechanism requires {+mdb-server+} v4.4 or later. + The MONGODB-AWS authentication mechanism requires {+mdb-server+} v6.0 or later. The MONGODB-AWS authentication mechanism uses AWS IAM (Amazon Web Services Identity and Access Management) or AWS Lambda credentials to authenticate your application. To use this @@ -386,4 +366,4 @@ in the library API documentation. To view a full list of URI options that you can pass to a ``MongoDB\Client``, see the :php:`MongoDB\Driver\Manager::__construct parameters ` -in the extension API documentation. \ No newline at end of file +in the extension API documentation. diff --git a/source/security/in-use-encryption.txt b/source/security/in-use-encryption.txt index adc6e72c..03564a94 100644 --- a/source/security/in-use-encryption.txt +++ b/source/security/in-use-encryption.txt @@ -73,12 +73,13 @@ Encryption ` in the {+mdb-server+} manual. Client-side Field Level Encryption ---------------------------------- -Client-side Field Level Encryption (CSFLE) was introduced in {+mdb-server+} -version 4.2 and supports searching encrypted fields for equality. -CSFLE differs from Queryable Encryption in that you can select either a -deterministic or random encryption algorithm to encrypt fields. You can only -query encrypted fields that use a deterministic encryption algorithm when -using CSFLE. When you use a random encryption algorithm to encrypt +Client-side Field Level Encryption (CSFLE) supports searching encrypted +fields for equality. CSFLE differs from Queryable Encryption in that you +can select either a deterministic or random encryption algorithm to +encrypt fields. You can only query encrypted fields that use a +deterministic encryption algorithm when using CSFLE. + +When you use a random encryption algorithm to encrypt fields in CSFLE, they can be decrypted, but you cannot perform equality queries on those fields. When you use Queryable Encryption, you cannot specify the encryption algorithm, but you can query all encrypted @@ -98,4 +99,4 @@ low cardinality is susceptible to code breaking by frequency analysis. - :wikipedia:`Frequency Analysis ` To learn more about CSFLE, see :manual:`CSFLE ` in the {+mdb-server+} -manual. \ No newline at end of file +manual. diff --git a/source/tutorial/encryption.txt b/source/tutorial/encryption.txt index 70b99df3..821afd4c 100644 --- a/source/tutorial/encryption.txt +++ b/source/tutorial/encryption.txt @@ -130,7 +130,6 @@ alternative name using the ``keyAltName`` option instead of ``keyId``. Client-Side Field Level Encryption ---------------------------------- -Introduced in MongoDB 4.2, :manual:`Client-Side Field Level Encryption ` allows an application to encrypt specific data fields in addition to pre-existing MongoDB encryption features such as @@ -149,8 +148,9 @@ Automatic Client-Side Field Level Encryption .. note:: - Automatic client-side field level encryption requires MongoDB 4.2+ Enterprise - or a MongoDB 4.2+ Atlas cluster. + To use the automatic client-side field level encryption feature, you + must connect an Enterprise or Atlas cluster running MongoDB 6.0 or + later. Automatic client-side field level encryption is enabled by creating a client and specifying the ``autoEncryption`` @@ -166,7 +166,7 @@ object to create a new encryption key. Server-Side Field Level Encryption Enforcement ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The MongoDB 4.2+ server supports using schema validation to enforce encryption +You can use schema validation to enforce encryption of specific fields in a collection. This schema validation will prevent an application from inserting unencrypted values for any fields marked with the :manual:`"encrypt" schema keyword `. @@ -218,8 +218,7 @@ Explicit encryption is a MongoDB community feature and does not use Explicit Encryption with Automatic Decryption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Although automatic encryption requires MongoDB 4.2+ enterprise or a MongoDB 4.2+ -Atlas cluster, automatic *decryption* is supported for all users. To configure +Automatic *decryption* is supported for all users. To configure automatic decryption without automatic encryption set the ``bypassAutoEncryption`` auto encryption :php:`driver option ` From 67ac918e716509f27f9cf087de0ff6ca1fd5c919 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 23 May 2025 10:20:54 -0500 Subject: [PATCH 11/12] DOCSP-50155 - EOL MongoDB 4.0 (#252) * eol v4.0 * update compat --- source/includes/mongodb-compatibility-table-php.rst | 2 +- source/whats-new.txt | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/source/includes/mongodb-compatibility-table-php.rst b/source/includes/mongodb-compatibility-table-php.rst index ae7fd69a..32985ed1 100644 --- a/source/includes/mongodb-compatibility-table-php.rst +++ b/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 - ✓ - ✓ - ✓ diff --git a/source/whats-new.txt b/source/whats-new.txt index e7421ddd..f1fb23dd 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -33,6 +33,13 @@ following versions of the {+php-library+}: What's New in 2.1 ----------------- +.. important:: Breaking Changes + The {+library-short+} v2.1 release introduces the following breaking + changes: + + - Drops support for {+mdb-server+} 4.0. The minimum supported {+mdb-server+} version is + 4.2. + The {+library-short+} v2.1 release includes the following features, improvements, and fixes: From b7b896959f179b68078127e556f567a7da008983 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Fri, 23 May 2025 11:27:20 -0400 Subject: [PATCH 12/12] DOCSP-50294: v2.1 release (#255) --- snooty.toml | 2 +- source/includes/language-compatibility-table-php.rst | 2 +- source/whats-new.txt | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/snooty.toml b/snooty.toml index 24d9ed5e..7ce8beda 100644 --- a/snooty.toml +++ b/snooty.toml @@ -39,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" diff --git a/source/includes/language-compatibility-table-php.rst b/source/includes/language-compatibility-table-php.rst index 2c6432b4..35edc9a9 100644 --- a/source/includes/language-compatibility-table-php.rst +++ b/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 - ✓ - ✓ - ✓ diff --git a/source/whats-new.txt b/source/whats-new.txt index f1fb23dd..102da67e 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -34,11 +34,12 @@ What's New in 2.1 ----------------- .. important:: Breaking Changes + The {+library-short+} v2.1 release introduces the following breaking changes: - - Drops support for {+mdb-server+} 4.0. The minimum supported {+mdb-server+} version is - 4.2. + - Drops support for {+mdb-server+} 4.0. The minimum supported + {+mdb-server+} version is 4.2. The {+library-short+} v2.1 release includes the following features, improvements, and fixes: