diff --git a/docs/faq.txt b/docs/faq.txt index fef322646..101f757fd 100644 --- 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 ` -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 index 1a41843ad..c4d8afa5e 100644 --- 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 ` 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 - ` for other errors at the driver + ` 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 index 620a7ac38..6225fafba 100644 --- a/docs/includes/extracts-note.yaml +++ b/docs/includes/extracts-note.yaml @@ -6,7 +6,7 @@ content: | :php:`comparison ` and :php:`type juggling ` rules. When matching a special BSON type the query criteria should use the respective :php:`BSON class - ` in the driver (e.g. use + ` in the extension (e.g. use :php:`MongoDB\BSON\ObjectId ` to match an :manual:`ObjectId `). --- diff --git a/docs/index.txt b/docs/index.txt index 7e76323fd..011581689 100644 --- 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 `_, also known as the ``mongodb`` -extension. +:php:`mongodb extension `. 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 index 307532472..315b87a58 100644 --- a/docs/reference/bson.txt +++ b/docs/reference/bson.txt @@ -28,7 +28,7 @@ Classes This class extends PHP's :php:`ArrayObject ` class. It also implements PHP's :php:`JsonSerializable ` interface and the - driver's :php:`MongoDB\BSON\Serializable ` and + extension's :php:`MongoDB\BSON\Serializable ` and :php:`MongoDB\BSON\Unserializable ` interfaces. @@ -41,7 +41,7 @@ Classes This class extends PHP's :php:`ArrayObject ` class. It also implements PHP's :php:`JsonSerializable ` interface and the - driver's :php:`MongoDB\BSON\Serializable ` and + extension's :php:`MongoDB\BSON\Serializable ` and :php:`MongoDB\BSON\Unserializable ` interfaces. diff --git a/docs/reference/class/MongoDBClient.txt b/docs/reference/class/MongoDBClient.txt index 4dc6cdbea..d5145c652 100644 --- 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 ` class, which it `composes `_. diff --git a/docs/reference/class/MongoDBCollection.txt b/docs/reference/class/MongoDBCollection.txt index 956b0129f..462ac4d94 100644 --- 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 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 ` (when not using a -cursor), :manual:`distinct `, and -:manual:`findAndModify ` helpers do not -support a ``typeMap`` option due to a driver limitation. The -:phpmethod:`aggregate() `, -:phpmethod:`distinct() `, -:phpmethod:`findOneAndReplace() `, -:phpmethod:`findOneAndUpdate() `, and -:phpmethod:`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 index c5a5b3a58..d733616f6 100644 --- 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 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 index 51d61fce0..c3e3e6e69 100644 --- 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 `. - You can construct a GridFS bucket using the driver's + You can construct a GridFS bucket using the extension's :php:`Manager ` class, or select a bucket from the library's :phpclass:`MongoDB\Database` class via the :phpmethod:`selectGridFSBucket() ` diff --git a/docs/reference/exception-classes.txt b/docs/reference/exception-classes.txt index 584c55d53..b21801a36 100644 --- 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 ` class and implements the library's :phpclass:`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 ` class and implements the library's :phpclass:`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 ` 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 ` class, which in turn extends PHP's :php:`RuntimeException ` class. diff --git a/docs/reference/function/add_logger.txt b/docs/reference/function/add_logger.txt index ea105a9fe..690769158 100644 --- 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 `__ -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 `__. diff --git a/docs/reference/function/remove_logger.txt b/docs/reference/function/remove_logger.txt index 099b1c02b..369c5c13d 100644 --- 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 index cf52a134f..f25e6c4b0 100644 --- a/docs/reference/method/MongoDBDatabase__construct.txt +++ b/docs/reference/method/MongoDBDatabase__construct.txt @@ -29,8 +29,8 @@ Parameters ---------- ``$manager`` : :php:`MongoDB\Driver\Manager ` - The :php:`Manager ` instance from the driver. The - manager maintains connections between the driver and your MongoDB instances. + The :php:`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 index 58f4e3db3..1349e5f44 100644 --- a/docs/reference/method/MongoDBGridFSBucket__construct.txt +++ b/docs/reference/method/MongoDBGridFSBucket__construct.txt @@ -29,8 +29,8 @@ Parameters ---------- ``$manager`` : :php:`MongoDB\Driver\Manager ` - The :php:`Manager ` instance from the driver. The - manager maintains connections between the driver and your MongoDB instances. + The :php:`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 index 3efa999e5..1debe37b1 100644 --- 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() - ` method in the PHP driver detects + ` 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 index b96a04219..f3736675a 100644 --- 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 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 ` method which is diff --git a/docs/tutorial/decimal128.txt b/docs/tutorial/decimal128.txt index eced91cfe..2397ccd88 100644 --- 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 `, such as financial and tax computations. -The :php:`MongoDB\BSON\Decimal128 ` class, which was -introduced in :php:`PHP driver ` 1.2.0, may be used to work with this -type in PHP. +The :php:`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 ` does not provide any functionality for working +The :php:`extension ` does not provide any functionality for working with ``Decimal128`` values; however, the string representation of a :php:`MongoDB\BSON\Decimal128 ` object may be used with PHP's :php:`BCMath ` extension. diff --git a/docs/tutorial/encryption.txt b/docs/tutorial/encryption.txt index c16845f9e..adf4cc411 100644 --- 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 `_ (i.e. ``mongodb`` extension) will need -to be compiled with `libmongocrypt `_ -(enabled by default). +:php:`extension ` will need to be compiled with +`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* @@ -31,14 +31,14 @@ The :manual:`Automatic Encryption Shared Library ` -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 `. diff --git a/docs/tutorial/example-data.txt b/docs/tutorial/example-data.txt index 920de5877..d0b748cc3 100644 --- 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 `_. 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 ` directly: +example imports the ``zips.json`` file into a ``test.zips`` collection using the +:php:`extension ` directly: .. code-block:: php diff --git a/docs/tutorial/install-php-library.txt b/docs/tutorial/install-php-library.txt index af409c360..913a945e9 100644 --- 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 `_ (i.e. ``mongodb`` extension). This page -will briefly explain how to install both the ``mongodb`` extension and the -|php-library|. +:php:`mongodb extension `. 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 index 56f0217af..5429b0313 100644 --- 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 ` outlines how -classes implementing its :php:`MongoDB\BSON\Persistable +The extension's :php:`persistence specification ` outlines +how classes implementing its :php:`MongoDB\BSON\Persistable ` interface are serialized to and deserialized from BSON. The :php:`Persistable ` interface is analogous to PHP's :php:`Serializable interface `. -The driver automatically handles serialization and deserialization for classes -implementing the :php:`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 ` 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 index 31047d936..c63ca5c9c 100644 --- 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 index 58d34eb18..18e92e52f 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -19,9 +19,9 @@ those differences for the benefit of those upgrading from the legacy driver. Additionally, a community-developed `mongo-php-adapter `_ library exists, which -implements the ``mongo`` extension API using this library and the new driver. -While this adapter library is not officially supported by MongoDB, it does bear -mentioning. +implements the ``mongo`` extension API using this library and the ``mongodb`` +extension. While this adapter library is not officially supported by MongoDB, it +does bear mentioning. BSON ---- @@ -31,9 +31,9 @@ Type Classes When upgrading from the legacy driver, type classes such as MongoId must be replaced with classes in the -`MongoDB\\BSON namespace `_. The -new driver also introduces interfaces for its BSON types, which should be -preferred if applications need to type hint against BSON values. +`MongoDB\\BSON namespace `_. The new +driver also introduces interfaces for its BSON types, which should be preferred +if applications need to type hint against BSON values. The following table lists all legacy classes alongside the equivalent class in the new driver. @@ -95,10 +95,7 @@ the new driver. 64-bit integer depending on their value. .. [2] :php:`MongoDB\BSON\Int64 ` does not have an - interface defined. The new driver does not allow applications to instantiate - this type (i.e. its constructor is private) and it is only created during - BSON decoding when a 64-bit integer cannot be represented as a PHP integer on - a 32-bit platform. + interface defined. .. [3] The new driver does not implement an equivalent class for MongoDBRef since :manual:`DBRefs ` are merely a BSON @@ -307,7 +304,7 @@ generated ObjectId (i.e. MongoId object). This behavior was a bit of a hack, as it did not rely on the argument being :php:`passed by reference `; instead, it directly modified memory through the extension API and could not be implemented in PHP userland. As such, it is no -longer done in the new driver and library. +longer done in the new driver. IDs of inserted documents (whether generated or not) may be accessed through the following methods on the write result objects: