diff --git a/reference/mongodb/architecture.xml b/reference/mongodb/architecture.xml
index ba01b5411528..02931db9dd30 100644
--- a/reference/mongodb/architecture.xml
+++ b/reference/mongodb/architecture.xml
@@ -10,94 +10,60 @@
Architecture Overview
- This section explains how all the different parts of the driver fit
- together. From the different language runtimes, through the extension and
- to the PHP libraries on top. This new architecture has replaced the old
- mongo extension. We refer to the new one
- as the mongodb extension.
+ This article explains how all the different components of the PHP driver fit
+ together, from base system libraries, through the extension, and to the PHP
+ libraries on top.
- Architecture Diagram
+
+ PHP Driver Architecture Diagram. The lowest level of the driver is our
+ system libraries: libmongoc, libbson, and libmongocrypt. The middle level
+ is the MongoDB PHP C extension. The upper level is PHP userland and
+ includes the MongoDB PHP library and higher-level packages such as
+ framework integrations and applications.
+
-
+
- At the top of this stack sits a pure
- PHP library, which we will
- distribute as a Composer package. This library will provide an API similar
- to what users have come to expect from the old mongo driver (e.g. CRUD methods,
- database and collection objects, command helpers) and we expect it to be a
- common dependency for most applications built with MongoDB. This library
- will also implement common
- specifications, in the
- interest of improving API consistency across all of the
- drivers maintained by
- MongoDB (and hopefully some community drivers, too).
+ At the top of this stack sits a
+ PHP library,
+ which is distributed as a
+ Composer package.
+ This library provides an API consistent with other MongoDB
+ drivers
+ and implements various cross-driver
+ specifications.
+ While the extension can be used directly, the library has minimal overhead and
+ should be a common dependency for most applications built with MongoDB.
- Sitting below that library we have the lower level driver.
- This extension will effectively form the glue between PHP and our
- system libraries (libmongoc and
- libbson). This extension
- will expose an identical public API for the most essential and
- performance-sensitive functionality:
+ Sitting below that library is a PHP extension, which is distributed through
+ PECL.
+ The extension forms the glue between PHP and our system libraries
+ (libmongoc,
+ libbson, and
+ libmongocrypt).
+ Its public API provides only the most essential functionality:
Connection managementBSON encoding and decodingObject document serialization (to support ODM libraries)
- Executing commands and write operations
- Handling queries and cursors
+ Executing commands, queries, and write operations
+ Handling cursors for command and query results
- By decoupling the driver internals and a high-level API into an extension and
- PHP libraries, respectively, we hope to reduce our maintainence burden and
- allow for faster iteration on new features. As a welcome side effect, this
- also makes it easier for anyone to contribute to the driver. Additionally,
- an identical public API will make it that much easier to port an
- application across PHP runtimes, whether the application uses the low-level
- driver directly or a higher-level PHP library.
-
-
- GridFS is a great example
- of why we chose this direction.
- Although we implemented GridFS in C for our old mongo driver, it is actually
- quite a high-level specification. Its API is just an abstraction for
- accessing two collections: files (i.e. metadata) and chunks (i.e. blocks of
- data). Likewise, all of the syntactic sugar found in the old mongo driver,
- such as processing uploaded files or exposing GridFS files as PHP streams,
- can be implemented in pure PHP. Provided we have performant methods for
- reading from and writing to GridFS' collections – and thanks to our low
- level extensions, we will – shifting this API to PHP is win-win.
-
-
- Earlier I mentioned that we expect the PHP library to be a common
- dependency for most applications, but not
- all. Some users may prefer to stick to the no-frills
- API offered by the extensions, or create their own high-level abstraction
- (akin to Doctrine MongoDB for
- the old mongo driver). Future libraries could include a PHP library geared
- for MongoDB administration, which provides an API for various user
- management and ops commands. The next major version of
- Doctrine MongoDB ODM will
- likely also sit directly atop the extensions.
-
-
- While we will continue to maintain and support the old mongo driver and its
- users for the foreseeable future, we invite everyone to use the
- next-generation driver and consider it for any new projects going forward.
- You can find all of the essential components across GitHub and JIRA:
-
-
-
- The existing PHP project in JIRA
- will remain open for reporting bugs against the old mongo driver, but we
- would ask that you use the new projects above for anything pertaining to
- our next-generation drivers.
-
@@ -153,7 +112,8 @@
options). The driver will attempt to find a previously persisted
libmongoc client object for
that hash. If an existing client cannot be found for the hash, a new client
- will be created (and persisted for future use).
+ will be created and persisted for future use. This behavior can be disabled
+ via the "disableClientPersistence" driver option.
@@ -203,7 +163,7 @@ foreach ($managers as $manager) {
If the same worker executes the script again in a second request, the three
- clients will be re-used and no new connections should be made. Depending on
+ clients will be re-used and no new connections will be made. Depending on
how long ago the previous request was served, the driver may need to issue
additional hello commands to update its view of the
topologies.
diff --git a/reference/mongodb/images/driver_arch.png b/reference/mongodb/images/driver_arch.png
deleted file mode 100644
index 74064bf78fd9..000000000000
Binary files a/reference/mongodb/images/driver_arch.png and /dev/null differ
diff --git a/reference/mongodb/images/driver_arch.svg b/reference/mongodb/images/driver_arch.svg
new file mode 100644
index 000000000000..a978d2cbbeb9
--- /dev/null
+++ b/reference/mongodb/images/driver_arch.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/reference/mongodb/tutorial/library.xml b/reference/mongodb/tutorial/library.xml
index 351d384549ec..65fc08f0c58e 100644
--- a/reference/mongodb/tutorial/library.xml
+++ b/reference/mongodb/tutorial/library.xml
@@ -81,19 +81,16 @@ require 'vendor/autoload.php';
- If you have previously used the old driver (i.e. mongo
- extension), the library's API should look familiar. It contains a
+ If you have used MongoDB drivers in other languages, the library's API
+ should look familiar. It contains a
Client
- class for connecting to MongoDB, and
+ class for connecting to MongoDB, a
Database
- class for database-level operations (e.g. commands, collection management)
+ class for database-level operations (e.g. commands, collection management),
and a
Collection
class for collection-level operations (e.g.
CRUD methods, index management).
- Various Collection methods have been renamed for clarity, and to be in
- accordance with a new language-agnostic
- specification.
@@ -117,15 +114,17 @@ echo "Inserted with Object ID '{$result->getInsertedId()}'";
- Instead of injecting the generated _id field into the input
- document (as was done in the old driver), it is now made available through
- the result object returned by the insertOne method.
+ Since the inserted document did not contain an _id field, the
+ driver will generate an MongoDB\BSON\ObjectId for the
+ server to use as the _id. This value is also made available to
+ the caller via the result object returned by the insertOne
+ method.
- After insertion, you can of course also query the data that you have just
- inserted. For that, you use the find method, which returns an
- iterable cursor:
+ After insertion, you can query for the data that you have just inserted.
+ For that, you use the find method, which returns an iterable
+ cursor:
ArrayObject for enhanced usability. You can find more
information on how serialization and deserialization between PHP variables
and BSON is handled by the driver and library by reading the