Merge v1.19 into master (#1341)

mongodb-php-bot · web-flow · commit 42d5f61d3cf0 · 2024-06-06T22:07:57.000+02:00
diff --git a/docs/faq.txt b/docs/faq.txt
@@ -125,15 +125,15 @@ The following are all examples of
 
 These errors typically manifest as a
 :php:`MongoDB\Driver\Exception\ConnectionTimeoutException <mongodb-driver-exception-connectiontimeoutexception>`
-exception from the driver. The actual exception messages originate from
-libmongoc, which is the underlying library used by the PHP driver. Since these
-messages can take many forms, it's helpful to break down the structure of the
-message so you can better diagnose errors in your application.
+exception from the extension. The actual exception messages originate from
+libmongoc, which is the underlying system library used by the extension. Since
+these messages can take many forms, it's helpful to break down the structure of
+the message so you can better diagnose errors in your application.
 
 Messages will typically start with "No suitable servers found". The next part of
-the message indicates *how* server selection failed. By default, the PHP driver
+the message indicates *how* server selection failed. By default, the extension
 avoids a server selection loop and instead makes a single attempt (according to
-the ``serverSelectionTryOnce`` connection string option). If the driver is
+the ``serverSelectionTryOnce`` connection string option). If the extension is
 configured to utilize a loop, a message like "serverSelectionTimeoutMS expired"
 will tell us that we exhausted its time limit.
 
diff --git a/docs/includes/extracts-error.yaml b/docs/includes/extracts-error.yaml
@@ -10,12 +10,12 @@ ref: error-driver-invalidargumentexception
 content: |
   :php:`MongoDB\Driver\Exception\InvalidArgumentException
   <mongodb-driver-exception-invalidargumentexception>` for errors related to the
-  parsing of parameters or options at the driver level.
+  parsing of parameters or options at the extension level.
 ---
 ref: error-driver-runtimeexception
 content: |
   :php:`MongoDB\Driver\Exception\RuntimeException
-  <mongodb-driver-exception-runtimeexception>` for other errors at the driver
+  <mongodb-driver-exception-runtimeexception>` for other errors at the extension
   level (e.g. connection errors).
 ---
 ref: error-badmethodcallexception-write-result
diff --git a/docs/includes/extracts-note.yaml b/docs/includes/extracts-note.yaml
@@ -6,7 +6,7 @@ content: |
   :php:`comparison <manual/en/types.comparisons.php>` and :php:`type juggling
   <manual/en/language.types.type-juggling.php>` rules. When matching a special
   BSON type the query criteria should use the respective :php:`BSON class
-  <manual/en/book.bson.php>` in the driver (e.g. use
+  <manual/en/book.bson.php>` in the extension (e.g. use
   :php:`MongoDB\BSON\ObjectId <class.mongodb-bson-objectid>` to match an
   :manual:`ObjectId </reference/object-id/>`).
 ---
diff --git a/docs/index.txt b/docs/index.txt
@@ -5,8 +5,7 @@ MongoDB PHP Library
 .. default-domain:: mongodb
 
 The |php-library| provides a high-level abstraction around the lower-level
-`PHP driver <https://php.net/mongodb>`_, also known as the ``mongodb``
-extension.
+:php:`mongodb extension <mongodb>`.
 
 The ``mongodb`` extension provides a limited API to connect to the database and
 execute generic commands, queries, and write operations. In contrast, the
diff --git a/docs/reference/bson.txt b/docs/reference/bson.txt
@@ -28,7 +28,7 @@ Classes
 
    This class extends PHP's :php:`ArrayObject <arrayobject>` class. It also
    implements PHP's :php:`JsonSerializable <jsonserializable>` interface and the
-   driver's :php:`MongoDB\BSON\Serializable <mongodb-bson-serializable>` and
+   extension's :php:`MongoDB\BSON\Serializable <mongodb-bson-serializable>` and
    :php:`MongoDB\BSON\Unserializable <mongodb-bson-unserializable>`
    interfaces.
 
@@ -41,7 +41,7 @@ Classes
 
    This class extends PHP's :php:`ArrayObject <arrayobject>` class. It also
    implements PHP's :php:`JsonSerializable <jsonserializable>` interface and the
-   driver's :php:`MongoDB\BSON\Serializable <mongodb-bson-serializable>` and
+   extension's :php:`MongoDB\BSON\Serializable <mongodb-bson-serializable>` and
    :php:`MongoDB\BSON\Unserializable <mongodb-bson-unserializable>`
    interfaces.
 
diff --git a/docs/reference/class/MongoDBClient.txt b/docs/reference/class/MongoDBClient.txt
@@ -18,7 +18,7 @@ Definition
    This class serves as an entry point for the |php-library|. It is the
    preferred class for connecting to a MongoDB server or cluster of servers and
    acts as a gateway for accessing individual databases and collections.
-   :phpclass:`MongoDB\Client` is analogous to the driver's
+   :phpclass:`MongoDB\Client` is analogous to the extension's
    :php:`MongoDB\Driver\Manager <mongodb-driver-manager>` class, which it
    `composes <https://en.wikipedia.org/wiki/Object_composition>`_.
 
diff --git a/docs/reference/class/MongoDBCollection.txt b/docs/reference/class/MongoDBCollection.txt
@@ -18,7 +18,7 @@ Definition
    Provides methods for common operations on collections and documents,
    including CRUD operations and index management.
 
-   You can construct collections directly using the driver's
+   You can construct collections directly using the extension's
    :php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>` class or
    select a collection from the library's :phpclass:`MongoDB\Client` or
    :phpclass:`MongoDB\Database` classes. A collection may also be cloned from
@@ -37,20 +37,6 @@ Definition
    Operations within the :phpclass:`MongoDB\Collection` class inherit the
    collection's options.
 
-Type Map Limitations
---------------------
-
-The :manual:`aggregate </reference/command/aggregate>` (when not using a
-cursor), :manual:`distinct </reference/command/distinct>`, and
-:manual:`findAndModify </reference/command/findAndModify>` helpers do not
-support a ``typeMap`` option due to a driver limitation. The
-:phpmethod:`aggregate() <MongoDB\Collection::aggregate()>`,
-:phpmethod:`distinct() <MongoDB\Collection::distinct()>`,
-:phpmethod:`findOneAndReplace() <MongoDB\Collection::findOneAndReplace()>`,
-:phpmethod:`findOneAndUpdate() <MongoDB\Collection::findOneAndUpdate()>`, and
-:phpmethod:`findOneAndDelete() <MongoDB\Collection::findOneAndDelete()>`
-methods return BSON documents as ``stdClass`` objects and BSON arrays as arrays.
-
 Methods
 -------
 
diff --git a/docs/reference/class/MongoDBDatabase.txt b/docs/reference/class/MongoDBDatabase.txt
@@ -18,7 +18,7 @@ Definition
    Provides methods for common operations on a database, such as executing
    database commands and managing collections.
 
-   You can construct a database directly using the driver's
+   You can construct a database directly using the extension's
    :php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>` class or
    select a database from the library's :phpclass:`MongoDB\Client` class. A
    database may also be cloned from an existing :phpclass:`MongoDB\Database`
diff --git a/docs/reference/class/MongoDBGridFSBucket.txt b/docs/reference/class/MongoDBGridFSBucket.txt
@@ -22,7 +22,7 @@ Definition
    provides an interface around these collections for working with the files as
    PHP :php:`Streams <stream>`.
 
-   You can construct a GridFS bucket using the driver's
+   You can construct a GridFS bucket using the extension's
    :php:`Manager <class.mongodb-driver-manager>` class, or select a bucket from
    the library's :phpclass:`MongoDB\Database` class via the
    :phpmethod:`selectGridFSBucket() <MongoDB\Database::selectGridFSBucket()>`
diff --git a/docs/reference/exception-classes.txt b/docs/reference/exception-classes.txt
@@ -53,7 +53,7 @@ MongoDB\\Exception\\InvalidArgumentException
    Thrown for errors related to the parsing of parameters or options within the
    library.
 
-   This class extends the driver's :php:`InvalidArgumentException
+   This class extends the extension's :php:`InvalidArgumentException
    <mongodb-driver-exception-invalidargumentexception>` class and implements the
    library's :phpclass:`Exception <MongoDB\Exception\Exception>` interface.
 
@@ -67,10 +67,9 @@ MongoDB\\Exception\\UnexpectedValueException
    This exception is thrown when a command response from the server is
    malformed or not what the library expected. This exception means that an
    assertion in some operation, which abstracts a database command, has failed.
-   It may indicate a corrupted BSON response or bug in the server, driver, or
-   library.
+   It may indicate a corrupted BSON response or bug in the server or driver.
 
-   This class extends the driver's :php:`UnexpectedValueException
+   This class extends the extension's :php:`UnexpectedValueException
    <mongodb-driver-exception-unexpectedvalueexception>` class and implements the
    library's :phpclass:`Exception <MongoDB\Exception\Exception>` interface.
 
@@ -133,7 +132,7 @@ MongoDB\\Exception\\Exception
 
 .. phpclass:: MongoDB\Exception\Exception
 
-   This interface extends the driver's :php:`Exception
+   This interface extends the extension's :php:`Exception
    <mongodb-driver-exception-exception>` interface and is implemented by all
    exception classes within the library.
 
@@ -144,6 +143,6 @@ MongoDB\\Exception\\RuntimeException
 
 .. phpclass:: MongoDB\Exception\RuntimeException
 
-   This class extends the driver's :php:`RuntimeException
+   This class extends the extension's :php:`RuntimeException
    <mongodb-driver-exception-runtimeexception>` class, which in turn extends
    PHP's :php:`RuntimeException <runtimeexception>` class.
diff --git a/docs/reference/function/add_logger.txt b/docs/reference/function/add_logger.txt
@@ -17,7 +17,7 @@ Definition
 
 .. phpmethod:: MongoDB\add_logger()
 
-   Registers a PSR logger to receive log messages from the driver.
+   Registers a PSR logger to receive log messages from the extension.
 
    .. code-block:: php
 
@@ -36,8 +36,8 @@ Behavior
 
 This function allows the application to register one or more
 `Psr\\Log\\LoggerInterface <https://www.php-fig.org/psr/psr-3/#3-psrlogloggerinterface>`__
-objects to receive log messages from libmongoc and the driver. Each registered
-logger will receive messages for *all* clients.
+objects to receive log messages from libmongoc and the extension. Each
+registered logger will receive messages for *all* clients.
 
 Messages originating from the extension will have their log level translated to
 an equivalent `PSR log level <https://www.php-fig.org/psr/psr-3/#5-psrlogloglevel>`__.
diff --git a/docs/reference/function/remove_logger.txt b/docs/reference/function/remove_logger.txt
@@ -17,7 +17,8 @@ Definition
 
 .. phpmethod:: MongoDB\remove_logger()
 
-   Unregisters a PSR logger to no longer receive log messages from the driver.
+   Unregisters a PSR logger to no longer receive log messages from the
+   extension.
 
    .. code-block:: php
 
diff --git a/docs/reference/method/MongoDBDatabase__construct.txt b/docs/reference/method/MongoDBDatabase__construct.txt
@@ -29,8 +29,8 @@ Parameters
 ----------
 
 ``$manager`` : :php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>`
-  The :php:`Manager <mongodb-driver-manager>` instance from the driver. The
-  manager maintains connections between the driver and your MongoDB instances.
+  The :php:`Manager <mongodb-driver-manager>` instance from the extension. The
+  manager maintains connections between the driver and MongoDB.
 
 ``$databaseName`` : string
   The name of the database.
diff --git a/docs/reference/method/MongoDBGridFSBucket__construct.txt b/docs/reference/method/MongoDBGridFSBucket__construct.txt
@@ -29,8 +29,8 @@ Parameters
 ----------
 
 ``$manager`` : :php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>`
-  The :php:`Manager <mongodb-driver-manager>` instance from the driver. The
-  manager maintains connections between the driver and your MongoDB instances.
+  The :php:`Manager <mongodb-driver-manager>` instance from the extension. The
+  manager maintains connections between the driver and MongoDB.
 
 ``$databaseName`` : string
   The name of the database.
diff --git a/docs/tutorial/commands.txt b/docs/tutorial/commands.txt
@@ -91,7 +91,7 @@ The output might resemble the following:
    will return a single result document with the essential ingredients for
    constructing the cursor (i.e. the cursor's ID, namespace, and an optional
    first batch of results). If the :php:`MongoDB\Driver\Manager::executeCommand()
-   <mongodb-driver-manager.executecommand>` method in the PHP driver detects
+   <mongodb-driver-manager.executecommand>` method in the extension detects
    such a response, it will construct an iterable command cursor and return it
    instead of the raw result document. If necessary, raw result documents can
    still be observed using `command monitoring
diff --git a/docs/tutorial/custom-types.txt b/docs/tutorial/custom-types.txt
@@ -16,7 +16,7 @@ if you want to store date/time information retaining the time zone
 information that PHP's :php:`DateTimeImmutable <class.datetimeimmutable>`
 class stores with a point in time.
 
-The driver serializes PHP variables, including objects, into BSON when it
+The extension serializes PHP variables, including objects, into BSON when it
 communicates to the server, and deserializes BSON back into PHP variables when
 it receives data from the server.
 
@@ -74,12 +74,12 @@ a string containing the Olson time zone identifier:
         }
     ?>
 
-The driver will additionally add a ``__pclass`` field to the document, and
+The extension will additionally add a ``__pclass`` field to the document, and
 store that in the database, too. This field contains the PHP class name so that
-upon deserialization the driver knows which class to use for recreating the
+upon deserialization the extension knows which class to use for recreating the
 stored object.
 
-When the document is read from the database, the driver detects whether a
+When the document is read from the database, the extension detects whether a
 ``__pclass`` field is present and then executes
 :php:`MongoDB\BSON\Persistable::bsonUnserialize
 <mongodb-bson-unserializable.bsonunserialize>` method which is
diff --git a/docs/tutorial/decimal128.txt b/docs/tutorial/decimal128.txt
@@ -19,9 +19,8 @@ floating-point value capable of emulating decimal rounding with exact precision.
 This functionality is intended for applications that handle :manual:`monetary
 data </tutorial/model-monetary-data>`, such as financial and tax computations.
 
-The :php:`MongoDB\BSON\Decimal128 <mongodb-bson-decimal128>` class, which was
-introduced in :php:`PHP driver <mongodb>` 1.2.0, may be used to work with this
-type in PHP.
+The :php:`MongoDB\BSON\Decimal128 <mongodb-bson-decimal128>` class may be used
+to work with this type in PHP.
 
 Working with Decimal128 Values
 ------------------------------
@@ -70,7 +69,7 @@ The output would then resemble:
 Mathematical Operations with BCMath
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :php:`PHP driver <mongodb>` does not provide any functionality for working
+The :php:`extension <mongodb>` does not provide any functionality for working
 with ``Decimal128`` values; however, the string representation of a
 :php:`MongoDB\BSON\Decimal128 <mongodb-bson-decimal128>` object may be used
 with PHP's :php:`BCMath <bcmath>` extension.
diff --git a/docs/tutorial/encryption.txt b/docs/tutorial/encryption.txt
@@ -15,9 +15,9 @@ Dependencies
 ------------
 
 To get started using in-use encryption in your project, the
-`PHP driver <https://php.net/mongodb>`_ (i.e. ``mongodb`` extension) will need
-to be compiled with `libmongocrypt <https://github.com/mongodb/libmongocrypt>`_
-(enabled by default).
+:php:`extension <mongodb>` will need to be compiled with
+`libmongocrypt <https://github.com/mongodb/libmongocrypt>`_ (enabled by
+default).
 
 Additionally, either ``crypt_shared`` or ``mongocryptd`` are required in order to
 use *automatic* client-side encryption. Neither is required for *explicit*
@@ -30,14 +30,14 @@ The :manual:`Automatic Encryption Shared Library </core/queryable-encryption/ref
 (``crypt_shared``) provides the same functionality as ``mongocryptd``, but does not
 require you to spawn another process to perform automatic encryption.
 
-By default, the PHP driver attempts to load ``crypt_shared`` from the system path(s)
-and uses it automatically if found. To load ``crypt_shared`` from another location,
-use the ``cryptSharedLibPath`` auto encryption
+By default, the extension attempts to load ``crypt_shared`` from the system
+path(s) and uses it automatically if found. To load ``crypt_shared`` from
+another location, use the ``cryptSharedLibPath`` auto encryption
 :php:`driver option <manual/en/mongodb-driver-manager.construct.php#mongodb-driver-manager.construct-driveroptions>`
-when constructing a client. If the driver cannot load ``crypt_shared`` it will
-attempt to fallback to using ``mongocryptd`` by default. The
-``cryptSharedLibRequired`` option may be used to always require ``crypt_shared`` and
-fail if it cannot be loaded.
+when constructing a client. If the extension cannot load ``crypt_shared`` it
+will attempt to fallback to using ``mongocryptd`` by default. The
+``cryptSharedLibRequired`` option may be used to always require ``crypt_shared``
+and fail if it cannot be loaded.
 
 For detailed installation instructions see the MongoDB documentation for the
 :manual:`Automatic Encryption Shared Library </core/queryable-encryption/reference/shared-library/>`.
diff --git a/docs/tutorial/example-data.txt b/docs/tutorial/example-data.txt
@@ -9,8 +9,8 @@ Some examples in this documentation use example data fixtures from
 `primer-dataset.json <https://raw.githubusercontent.com/mongodb/docs-assets/primer-dataset/primer-dataset.json>`_.
 
 Importing the dataset into MongoDB can be done in several ways. The following
-example imports the ``zips.json`` file into a ``test.zips`` collection:
-:php:`driver <mongodb>` directly:
+example imports the ``zips.json`` file into a ``test.zips`` collection using the
+:php:`extension <mongodb>` directly:
 
 .. code-block:: php
 
diff --git a/docs/tutorial/install-php-library.txt b/docs/tutorial/install-php-library.txt
@@ -11,9 +11,8 @@ Install the |php-library|
    :class: singlecol
 
 The |php-library| is a high-level abstraction for the
-`PHP driver <https://php.net/mongodb>`_ (i.e. ``mongodb`` extension). This page
-will briefly explain how to install both the ``mongodb`` extension and the
-|php-library|.
+:php:`mongodb extension <mongodb>`. This page will briefly explain how to
+install both the ``mongodb`` extension and the |php-library|.
 
 Installing the Extension
 ------------------------
diff --git a/docs/tutorial/modeling-bson-data.txt b/docs/tutorial/modeling-bson-data.txt
@@ -53,16 +53,16 @@ are aliases of one another).
 Persistable Classes
 -------------------
 
-The driver's :php:`persistence specification <mongodb.persistence>` outlines how
-classes implementing its :php:`MongoDB\BSON\Persistable
+The extension's :php:`persistence specification <mongodb.persistence>` outlines
+how classes implementing its :php:`MongoDB\BSON\Persistable
 <mongodb-bson-persistable>` interface are serialized to and deserialized from
 BSON. The :php:`Persistable <mongodb-bson-persistable>` interface is analogous
 to PHP's :php:`Serializable interface <class.serializable>`.
 
-The driver automatically handles serialization and deserialization for classes
-implementing the :php:`Persistable <mongodb-bson-persistable>` interface without
-requiring the use of the ``typeMap`` option. This is done by encoding the name
-of the PHP class in a special property within the BSON document.
+The extension automatically handles serialization and deserialization for
+classes implementing the :php:`Persistable <mongodb-bson-persistable>` interface
+without requiring the use of the ``typeMap`` option. This is done by encoding
+the name of the PHP class in a special property within the BSON document.
 
 .. note::
 
diff --git a/docs/tutorial/server-selection.txt b/docs/tutorial/server-selection.txt
@@ -15,8 +15,8 @@ Server Selection and Monitoring
 
 Before any operation can be executed, the |php-library| must first select a
 server from the topology (e.g. replica set, sharded cluster). Selecting a server
-requires an accurate view of the topology, so the driver (i.e. ``mongodb``
-extension) regularly monitors the servers to which it is connected.
+requires an accurate view of the topology, so the extension regularly monitors
+the servers to which it is connected.
 
 In most other drivers, server discovery and monitoring is handled by a
 background thread; however, the PHP driver is single-threaded and must therefore
@@ -30,9 +30,9 @@ Consider the following example application:
 
    /**
     * When constructing a Client, the library creates a MongoDB\Driver\Manager
-    * object from the driver. In turn, the driver will either create a libmongoc
-    * client object (and persist it according to the constructor parameters) or
-    * re-use a previously persisted client.
+    * object from the extension. In turn, the extension will either create a
+    * libmongoc client object (and persist it according to the constructor
+    * parameters) or re-use a previously persisted client.
     *
     * Assuming a new libmongoc client was created, the host name(s) in the
     * connection string must be resolved via DNS. Likewise, if the connection
diff --git a/docs/upgrade.txt b/docs/upgrade.txt
