` may be used to determine
-exactly which INI files have been loaded by PHP.
-
-To debug issues with the extension not being loaded, you can use the
-``detect-extension`` script provided in the tools directory. You can run this
-script from the CLI or include it in a script accessible via your web server.
-The tool will point out potential issues and installation instructions for your
-system. Assuming you've installed the library through Composer, you can call the
-script from the vendor directory:
-
-.. code-block:: none
-
- php vendor/mongodb/mongodb/tools/detect-extension.php
-
-If you want to check configuration for a web server SAPI, include the file in
-a script accessible from the web server and open it in your browser. Remember to
-wrap the script in ```` tags to properly format its output:
-
-.. code-block:: php
-
-
-
-Loading an Incompatible DLL on Windows
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Windows binaries are available for various combinations of PHP version,
-thread safety (TS or NTS), and architecture (x86 or x64). Failure to select the
-correct binary will result in an error when attempting to load the extension DLL
-at runtime:
-
-.. code-block:: none
-
- PHP Warning: PHP Startup: Unable to load dynamic library 'mongodb'
-
-Ensure that you have downloaded a DLL that corresponds to the following PHP
-runtime properties:
-
-- PHP version (``PHP_VERSION``)
-- Thread safety (``PHP_ZTS``)
-- Architecture (``PHP_INT_SIZE``)
-
-In addition to the aforementioned constants, these properties can also be
-inferred from :php:`phpinfo() `. If your system has multiple PHP
-runtimes installed, double-check that you are examining the ``phpinfo()`` output
-for the correct environment.
-
-The aforementioned ``detect-extension`` script can also be used to determine the
-appropriate DLL for your PHP environment.
-
-Connection Handling and Persistence
------------------------------------
-
-Connections to the MongoDB deployment are handled by the ``libmongoc``
-library and the :php:`{+extension-short+} `. When you construct
-a :phpclass:`MongoDB\Client` instance, the {+library-short+} creates a
-:php:`MongoDB\Driver\Manager ` instance by using the
-same connection string and options. The extension also uses those constructor
-arguments to derive a hash key for persistent ``libmongoc`` clients. If
-you previously persisted a ``libmongoc`` client by using a key, it is
-reused. Otherwise, a new ``libmongoc`` client is created and persisted
-for the lifetime of the PHP worker process. You can learn more about
-this process in the :php:`{+extension-short+} documentation
-`.
-
-Each ``libmongoc`` client maintains its own connections to the MongoDB deployment
-and a view of its topology. When you reuse a persistent ``libmongoc`` client, the
-{+library-short+} can avoid the overhead of establishing new connections and
-rediscovering the topology. This approach generally improves performance and is
-the driver's default behavior.
-
-Persistent ``libmongoc`` clients are not freed until the PHP worker process
-ends. This means that connections to a MongoDB deployment might remain open
-after a ``MongoDB\Driver\Manager`` object goes out of scope. While this is
-typically not an issue for applications that connect to one MongoDB deployment,
-it might be problematic in some situations, which are described in the
-following list:
-
-- PHP-FPM is configured with ``pm.max_requests=0``, so that workers never respawn, and a
- PHP application is deployed many times with small changes to its MongoDB
- connection string or options. This could lead to an accumulation of ``libmongoc``
- client objects in each worker process.
-
-- An application occasionally connects to a separate MongoDB deployment in a
- backend component where request latency is not the most important aspect.
-
-In the first case, restarting PHP-FPM as part of the application deployment
-allows the application to release any unused ``libmongoc`` clients and still use
-a persistent client for the latest connection string.
-
-The second case requires a different solution. Specifying ``true`` for the
-``disableClientPersistence`` driver option instructs the {+library-short+} to
-create a new ``libmongoc`` client and ensure it is freed when the corresponding
-``MongoDB\Driver\Manager`` goes out of scope.
-
-The following code demonstrates how to set the
-``disableClientPersistence`` option to ``true`` when creating a client:
-
-.. code-block:: php
- :emphasize-lines: 6
-
- true],
- );
-
-Use the ``disableClientPersistence`` driver option after careful
-consideration, because opting out of client persistence requires more
-time to establish connections to the MongoDB deployment and discover its
-topology.
-
-Server Selection Failures
--------------------------
-
-The following are all examples of
-:doc:`Server Selection ` failures:
-
-.. code-block:: none
-
- No suitable servers found (`serverSelectionTryOnce` set):
- [connection refused calling hello on 'a.example.com:27017']
- [connection refused calling hello on 'b.example.com:27017']
-
- No suitable servers found: `serverSelectionTimeoutMS` expired:
- [socket timeout calling hello on 'example.com:27017']
-
- No suitable servers found: `serverSelectionTimeoutMS` expired:
- [connection timeout calling hello on 'a.example.com:27017']
- [connection timeout calling hello on 'b.example.com:27017']
- [TLS handshake failed: -9806 calling hello on 'c.example.com:27017']
-
- No suitable servers found: `serverselectiontimeoutms` timed out:
- [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'a.example.com:27017']
- [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'b.example.com:27017']
-
-These errors typically manifest as a
-:php:`MongoDB\Driver\Exception\ConnectionTimeoutException `
-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 extension
-avoids a server selection loop and instead makes a single attempt (according to
-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.
-
-The last component of the message tells us *why* server selection failed, and
-includes one or more errors directly from the topology scanner, which is the
-service responsible for connecting to and monitoring each host. Any host that
-last experienced an error during monitoring will be included in this list. These
-messages typically originate from low-level socket or TLS functions.
-
-The following is not meant to be exhaustive, but will hopefully point you in the
-right direction for analyzing the contributing factor(s) for a server selection
-failure:
-
-- "connection refused" likely indicates that the remote host is not listening on
- the expected port.
-- "connection timeout" could indicate a routing or firewall issue, or perhaps
- a timeout due to latency.
-- "socket timeout" suggests that a connection *was* established at some point
- but was dropped or otherwise timed out due to latency.
-- "TLS handshake failed" suggests something related to TLS or OCSP verification
- and is sometimes indicative of misconfigured TLS certificates.
-
-In the case of a connection failure, you can use the ``connect`` tool to try and
-receive more information. This tool attempts to connect to each host in a
-connection string using socket functions to see if it is able to establish a
-connection, send, and receive data. The tool takes the connection string to a
-MongoDB deployment as its only argument. Assuming you've installed the library
-through Composer, you would call the script from the vendor directory:
-
-.. code-block:: none
-
- php vendor/mongodb/mongodb/tools/connect.php mongodb://127.0.0.1:27017
-
-In case the server does not accept connections, the output will look like this:
-
-.. code-block:: none
-
- Looking up MongoDB at mongodb://127.0.0.1:27017
- Found 1 host(s) in the URI. Will attempt to connect to each.
-
- Could not connect to 127.0.0.1:27017: Connection refused
-
-.. note::
-
- The tool only supports the ``mongodb://`` URI schema. Using the
- ``mongodb+srv`` scheme is not supported.
diff --git a/source/get-started.txt b/source/get-started.txt
index 45d7a3b3..35906f9c 100644
--- a/source/get-started.txt
+++ b/source/get-started.txt
@@ -1,8 +1,8 @@
.. _php-get-started:
-================================
-Get Started with the PHP Library
-================================
+===========
+Get Started
+===========
.. contents:: On this page
:local:
@@ -58,6 +58,7 @@ Download and Install
- :php:`PHP ` version 7.4 or later
- `Composer `__ version 2.0 or later
+ - :github:`pie `
.. step:: Install the MongoDB PHP extension
@@ -65,25 +66,19 @@ Download and Install
.. code-block:: bash
- sudo pecl install mongodb
+ pie install mongodb/mongodb-extension
- .. step:: Update your PHP configuration file
+ .. tip:: Specify the PHP Extension Version
- To enable the ``mongodb`` extension in your PHP configuration file, add the
- following line to the top of your ``php.ini`` file:
-
- .. code-block:: none
-
- extension=mongodb.so
-
- .. tip::
-
- You can locate your ``php.ini`` file by running the following command
- in your shell:
+ To install a specific version of the {+extension-short+}, include
+ the version number as shown in the following command:
.. code-block:: bash
- php --ini
+ pie install mongodb/mongodb-extension:^{+full-version+}
+
+ To install a {+extension-short+} version before v1.21, you must
+ use the :php:`pecl command `.
.. step:: Create a project directory
@@ -191,9 +186,8 @@ The connection string includes the hostname or IP address and
port of your deployment, the authentication mechanism, user credentials
when applicable, and connection options.
-.. TODO:
- To connect to an instance or deployment not hosted on Atlas, see
- :ref:`php-connection-targets`.
+To connect to an instance or deployment not hosted on Atlas, see
+:ref:`php-connection-targets`.
.. procedure::
:style: connected
@@ -341,8 +335,101 @@ In this tutorial, you created a PHP application that
connects to a MongoDB deployment hosted on MongoDB Atlas
and retrieves a document that matches a query.
-
Learn more about the {+php-library+} from the following resources:
-- Learn how to perform read operations in the :ref:`` section.
-- Learn how to perform write operations in the :ref:`` section.
\ No newline at end of file
+- Learn how to configure your MongoDB connection in the :ref:`php-connect` section.
+- Learn how to perform read and write operations in the :ref:`php-crud-operations` section.
+
+Troubleshooting
+---------------
+
+This section addresses issues that you might encounter when installing the
+{+library-short+} and its dependencies.
+
+PHP Headers Not Found
+~~~~~~~~~~~~~~~~~~~~~
+
+You might see a header file error that resembles the following code when installing
+the {+library-short+}:
+
+.. code-block:: none
+ :copyable: false
+
+ /private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
+
+ #include
+ ^~~~~~~
+
+This error indicates that PHP's build system cannot find the necessary headers.
+All PHP extensions require headers to compile. Those headers
+must correspond to the PHP runtime for which the extension will be used.
+The ``phpize`` command, which is invoked by ``pecl`` and ``pie``, usually ensures that the
+extension builds with the correct headers.
+
+If you install a PHP runtime, the corresponding headers are not always automatically
+available. On many Linux distributions, headers are often published under a
+separate ``php-dev`` or ``php-devel`` package. On macOS, the default PHP runtime
+does not include headers. Users typically must install PHP and its headers by using
+`Homebrew `__.
+
+Multiple PHP Runtimes Installed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your system has multiple versions of PHP installed, each version will have
+its own ``pecl``, ``pie``, and ``phpize`` commands. Additionally, each PHP runtime may
+have separate ``php.ini`` files for each server application programming interface (SAPI),
+such as FPM and CLI. If you installed the extension but it is not available at runtime,
+ensure that you use the correct ``pecl`` or ``pie`` command and modify the appropriate ``php.ini``
+file.
+
+To see which ``php.ini`` file a PHP runtime uses,
+view the output of :php:`phpinfo() ` for that particular
+SAPI. Additionally, you can use :php:`php_ini_loaded_file() ` and
+:php:`php_ini_scanned_files() ` to determine
+which INI files have been loaded by PHP.
+
+To debug issues when the extension is not loaded, you can use the
+``detect-extension`` script provided in the tools directory. You can run this
+script from the CLI or include it in a script available to your web server.
+The tool finds potential issues and installation instructions for your
+system. If you installed the library by using Composer, you can call the
+script from the vendor directory as shown in the following code:
+
+.. code-block:: none
+
+ php vendor/mongodb/mongodb/tools/detect-extension.php
+
+If you want to check configuration for a web server SAPI, include the file in
+a script available to the web server and open it in your browser. Ensure that you
+wrap the script in ```` tags to properly format its output as shown in the following code:
+
+.. code-block:: php
+
+
+
+Loading an Incompatible DLL on Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Windows binaries are available for several combinations of a PHP version,
+thread safety setting (TS or NTS), and architecture type (x86 or x64). Failure to select the
+correct binary causes an error when attempting to load the extension DLL
+at runtime, as shown in the following sample output:
+
+.. code-block:: none
+ :copyable: false
+
+ PHP Warning: PHP Startup: Unable to load dynamic library 'mongodb'
+
+Ensure that you have downloaded a DLL that corresponds to the following PHP
+runtime properties:
+
+- PHP version (``PHP_VERSION``)
+- Thread safety (``PHP_ZTS``)
+- Architecture (``PHP_INT_SIZE``)
+
+In addition to the preceding constants, these properties can also be
+inferred from :php:`phpinfo() `. If your system has multiple PHP
+runtimes installed, view the ``phpinfo()`` output for the correct environment.
+
+You can also use the ``detect-extension`` script described in the previous section to determine the
+correct DLL for your PHP environment.
\ No newline at end of file
diff --git a/source/includes/aggregation/aggregation.php b/source/includes/aggregation/aggregation.php
index f8573ac4..a36bdd54 100644
--- a/source/includes/aggregation/aggregation.php
+++ b/source/includes/aggregation/aggregation.php
@@ -32,7 +32,7 @@
$aggregate = new MongoDB\Operation\Aggregate(
$collection->getDatabaseName(),
$collection->getCollectionName(),
- $pipeline
+ $pipeline,
);
$result = $collection->explain($aggregate);
diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php
index 9ace0445..686b1631 100644
--- a/source/includes/aggregation/atlas-search.php
+++ b/source/includes/aggregation/atlas-search.php
@@ -61,9 +61,9 @@
Stage::project(
borough: 1,
cuisine: 1,
- name: 1
+ name: 1,
),
- Stage::limit(3)
+ Stage::limit(3),
);
$cursor = $collection->aggregate($pipeline);
@@ -77,21 +77,21 @@
$collection->updateSearchIndex(
'default',
['mappings' => [
- "dynamic" => false,
- "fields" => [
- "name" => [
- ["type" => "stringFacet"],
- ["type" => "string"],
+ 'dynamic' => false,
+ 'fields' => [
+ 'name' => [
+ ['type' => 'stringFacet'],
+ ['type' => 'string'],
[
- "foldDiacritics" => false,
- "maxGrams" => 7,
- "minGrams" => 3,
- "tokenization" => "edgeGram",
- "type" => "autocomplete"
+ 'foldDiacritics' => false,
+ 'maxGrams' => 7,
+ 'minGrams' => 3,
+ 'tokenization' => 'edgeGram',
+ 'type' => 'autocomplete',
],
- ]
- ]
- ]]
+ ],
+ ],
+ ]],
);
// Waits for the index to be updated.
diff --git a/source/includes/aggregation/vector-search.php b/source/includes/aggregation/vector-search.php
index 1509f9f5..d48ae73d 100644
--- a/source/includes/aggregation/vector-search.php
+++ b/source/includes/aggregation/vector-search.php
@@ -22,8 +22,8 @@
'path' => 'plot_embedding',
'numDimensions' => 1536,
'similarity' => 'dotProduct',
- 'quantization' => 'scalar'
- ]]
+ 'quantization' => 'scalar',
+ ]],
],
['name' => 'vector', 'type' => 'vectorSearch'],
);
diff --git a/source/includes/authentication.php b/source/includes/authentication.php
index 7810406b..4270f0fa 100644
--- a/source/includes/authentication.php
+++ b/source/includes/authentication.php
@@ -2,6 +2,24 @@
require __DIR__ . '/../vendor/autoload.php';
+// start-default-client
+$uriOptions = [
+ 'username' => '',
+ 'password' => '',
+ 'authSource' => '',
+];
+
+$client = new MongoDB\Client(
+ 'mongodb://:',
+ $uriOptions,
+);
+// end-default-client
+
+// start-default-uri
+$uri = 'mongodb://:@:/?authSource=admin';
+$client = new MongoDB\Client($uri);
+// end-default-uri
+
// start-scram-sha-256-client
$uriOptions = [
'username' => '',
@@ -79,7 +97,7 @@
// start-mongodb-aws-env-client
$client = new MongoDB\Client(
'mongodb://:',
- ['authMechanism' => 'MONGODB-AWS']
+ ['authMechanism' => 'MONGODB-AWS'],
);
// end-mongodb-aws-env-client
@@ -87,3 +105,141 @@
$uri = 'mongodb://:/?authMechanism=MONGODB-AWS';
$client = new MongoDB\Client($uri);
// end-mongodb-aws-env-uri
+
+// Connects to a MongoDB deployment and enables TLS using client
+// options
+// start-enable-tls-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true],
+);
+// end-enable-tls-client
+
+// Connects to a MongoDB deployment and enables TLS using connection URI
+// parameters
+// start-enable-tls-uri
+$uri = 'mongodb://:/?tls=true';
+$client = new MongoDB\Client($uri);
+// end-enable-tls-uri
+
+// Connects to a MongoDB deployment, enables TLS, and specifies the path to
+// a CA file using client options
+// start-ca-file-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'],
+);
+// end-ca-file-client
+
+// Connects to a MongoDB deployment, enables TLS, and specifies the path to
+// a CA file using connection URI parameters
+// start-ca-file-uri
+$uri = 'mongodb://:/?tls=true&tlsCAFile=/path/to/ca.pem';
+$client = new MongoDB\Client($uri);
+// end-ca-file-uri
+
+// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks
+// using client options
+// start-disable-ocsp-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true],
+);
+// end-disable-ocsp-client
+
+// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks
+// using connection URI parameters
+// start-disable-ocsp-uri
+$uri = 'mongodb://:/?tls=true&tlsDisableOCSPEndpointCheck=true';
+$client = new MongoDB\Client($uri);
+// end-disable-ocsp-uri
+
+// Connects to a TLS-enabled deployment and instructs the driver to check the
+// server certificate against a CRL
+// start-crl
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true],
+ ['crl_file' => '/path/to/file.pem'],
+);
+// end-crl
+
+// Presents a client certificate to prove identity
+// using client options
+// start-client-cert-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'],
+);
+// end-client-cert-client
+
+// Presents a client certificate to prove identity
+// using connection URI parameters
+// start-client-cert-uri
+$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem';
+$client = new MongoDB\Client($uri);
+// end-client-cert-uri
+
+// Specifies the password for a client certificate using client options
+// start-key-file-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ [
+ 'tls' => true,
+ 'tlsCertificateKeyFile' => '/path/to/client.pem',
+ 'tlsCertificateKeyFilePassword' => '',
+ ],
+);
+// end-key-file-client
+
+// Specifies the password for a client certificate using connection URI parameters
+// start-key-file-uri
+$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword=';
+$client = new MongoDB\Client($uri);
+// end-key-file-uri
+
+// Connects to a TLS-enabled deployment and disables server certificate verification
+// using client options
+// start-insecure-tls-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true, 'tlsInsecure' => true],
+);
+// end-insecure-tls-client
+
+// Connects to a TLS-enabled deployment and disables server certificate verification
+// using connection URI parameters
+// start-insecure-tls-uri
+$uri = 'mongodb://:/?tls=true&tlsInsecure=true';
+$client = new MongoDB\Client($uri);
+// end-insecure-tls-uri
+
+// Disables certificate validation using client options
+// start-disable-cert-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true, 'tlsAllowInvalidCertificates' => true],
+);
+// end-disable-cert-client
+
+// Disables certificate validation using connection URI parameters
+// start-disable-cert-uri
+$uri = 'mongodb://:/?tls=true&tlsAllowInvalidCertificates=true';
+$client = new MongoDB\Client($uri);
+// end-disable-cert-uri
+
+// Connects to a TLS-enabled deployment and disables hostname verification
+// using client options
+// start-disable-hostname-client
+$client = new MongoDB\Client(
+ 'mongodb://:/',
+ ['tls' => true, 'tlsAllowInvalidHostnames' => true],
+);
+// end-disable-hostname-client
+
+// Connects to a TLS-enabled deployment and disables hostname verification
+// using connection URI parameters
+// start-disable-hostname-uri
+$uri = 'mongodb://:/?tls=true&tlsAllowInvalidHostnames=true';
+$client = new MongoDB\Client($uri);
+// end-disable-hostname-uri
diff --git a/source/includes/bson/Person.php b/source/includes/bson/Person.php
new file mode 100644
index 00000000..cd63e419
--- /dev/null
+++ b/source/includes/bson/Person.php
@@ -0,0 +1,33 @@
+id = new \MongoDB\BSON\ObjectId();
+ $this->createdAt = new \MongoDB\BSON\UTCDateTime();
+ }
+
+ public function bsonSerialize(): array
+ {
+ return [
+ '_id' => $this->id,
+ 'name' => $this->name,
+ 'createdAt' => $this->createdAt,
+ ];
+ }
+
+ public function bsonUnserialize(array $data): void
+ {
+ $this->id = $data['_id'];
+ $this->name = $data['name'];
+ $this->createdAt = $data['createdAt'];
+ }
+}
+// end-person-class
diff --git a/source/includes/bson/Role.php b/source/includes/bson/Role.php
new file mode 100644
index 00000000..c4239e74
--- /dev/null
+++ b/source/includes/bson/Role.php
@@ -0,0 +1,11 @@
+ $this->_id,
+ 'username' => $this->username,
+ 'role' => $this->role,
+ ];
+ }
+
+ public function bsonUnserialize(array $data): void
+ {
+ $this->_id = $data['_id'];
+ $this->username = $data['username'];
+ $this->role = Role::from($data['role']);
+ }
+}
+// end-user-class
diff --git a/source/includes/bson/interact-bson.php b/source/includes/bson/interact-bson.php
new file mode 100644
index 00000000..70b41b2b
--- /dev/null
+++ b/source/includes/bson/interact-bson.php
@@ -0,0 +1,56 @@
+test;
+
+// start-create-doc
+$document = [
+ 'address' => [
+ 'street' => 'Pizza St',
+ 'zipcode' => '10003',
+ ],
+ 'coord' => [-73.982419, 41.579505],
+ 'cuisine' => 'Pizza',
+ 'name' => 'Planet Pizza',
+];
+// end-create-doc
+
+// start-modify-doc
+$document['restaurant_id'] = 12345;
+$document['name'] = 'Galaxy Pizza';
+// end-modify-doc
+
+// start-type-map
+$options = [
+ 'typeMap' => [
+ 'array' => 'MongoDB\Model\BSONDocument',
+ 'root' => 'MongoDB\Model\BSONDocument',
+ 'document' => 'MongoDB\Model\BSONDocument',
+ ],
+];
+
+$db->createCollection('restaurants', $options);
+// end-type-map
+
+// start-person-serialize
+$collection = $client->test->persons;
+$result = $collection->insertOne(new Person('Bob'));
+$person = $collection->findOne(['_id' => $result->getInsertedId()]);
+
+var_dump($person);
+// end-person-serialize
+
+// start-enum-serialize
+$collection = $client->test->users;
+$result = $collection->insertOne(new User('alice', Role::USER));
+$person = $collection->findOne(['_id' => $result->getInsertedId()]);
+
+var_dump($person);
+// end-enum-serialize
diff --git a/source/includes/builders.php b/source/includes/builders.php
index 3044147b..b06b78a4 100644
--- a/source/includes/builders.php
+++ b/source/includes/builders.php
@@ -27,8 +27,8 @@
coordinates: [-79.9, 9.3],
),
maxDistance: 10000,
- )
- )
+ ),
+ ),
);
// Prints matching documents
@@ -44,7 +44,7 @@
Query::or(
Query::query(feature_type: Query::regex('nondangerous$', '')),
Query::query(depth: Query::gt(10.0)),
- )
+ ),
);
// Prints number of deleted documents
@@ -76,7 +76,7 @@
// Opens the change stream
$changeStream = $collection->watch(
$pipeline,
- ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP]
+ ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP],
);
// Prints change events based on the pipeline specifications
diff --git a/source/includes/collation.rst b/source/includes/collation.rst
new file mode 100644
index 00000000..bed2508b
--- /dev/null
+++ b/source/includes/collation.rst
@@ -0,0 +1,97 @@
+To specify a collation for your operation, pass an ``$options`` array
+parameter that sets the ``collation`` option to the operation method.
+Assign the ``collation`` option to an array that configures the collation
+rules.
+
+The following table describes the fields you can set to configure
+the collation:
+
+.. list-table::
+ :widths: 30 70
+ :header-rows: 1
+
+ * - Field
+ - Description
+
+ * - ``locale``
+ - | *(Required)* Specifies the International Components for Unicode (ICU) locale. For a
+ list of supported locales, see :manual:`Collation Locales and Default Parameters
+ `
+ in the {+mdb-server+} manual.
+ |
+ | **Data Type**: {+string-data-type+}
+
+ * - ``caseLevel``
+ - | *(Optional)* Specifies whether to include case comparison.
+ |
+ | When set to ``true``, the comparison behavior depends on the value of
+ the ``strength`` field:
+ |
+ | - If ``strength`` is ``1``, the {+library-short+} compares base
+ | characters and case.
+ |
+ | - If ``strength`` is ``2``, the {+library-short+} compares base
+ | characters, diacritics, other secondary differences, and case.
+ |
+ | - If ``strength`` is any other value, this field is ignored.
+ |
+ | When set to ``false``, the {+library-short+} doesn't include case comparison at
+ strength level ``1`` or ``2``.
+ |
+ | **Data Type**: {+bool-data-type+}
+ | **Default**: ``false``
+
+ * - ``caseFirst``
+ - | *(Optional)* Specifies the sort order of case differences during tertiary
+ level comparisons.
+ |
+ | **Data Type**: {+string-data-type+}
+ | **Default**: ``"off"``
+
+ * - ``strength``
+ - | *(Optional)* Specifies the level of comparison to perform, as defined in the
+ `ICU documentation `__.
+ |
+ | **Data Type**: {+int-data-type+}
+ | **Default**: ``3``
+
+ * - ``numericOrdering``
+ - | *(Optional)* Specifies whether the driver compares numeric strings as numbers.
+ |
+ | If set to ``true``, the {+library-short+} compares numeric strings as numbers.
+ For example, when comparing the strings "10" and "2", the library uses the
+ strings' numeric values and treats "10" as greater than "2".
+ |
+ | If set to ``false``, the {+library-short+} compares numeric strings
+ as strings. For example, when comparing the strings "10" and "2", the library
+ compares one character at a time and treats "10" as less than "2".
+ |
+ | For more information, see :manual:`Collation Restrictions `
+ in the {+mdb-server+} manual.
+ |
+ | **Data Type**: {+bool-data-type+}
+ | **Default**: ``false``
+
+ * - ``alternate``
+ - | *(Optional)* Specifies whether the library considers whitespace and punctuation as base
+ characters for comparison purposes.
+ |
+ | **Data Type**: {+string-data-type+}
+ | **Default**: ``"non-ignorable"``
+
+ * - ``maxVariable``
+ - | *(Optional)* Specifies which characters the library considers ignorable when
+ the ``alternate`` field is set to ``"shifted"``.
+ |
+ | **Data Type**: {+string-data-type+}
+ | **Default**: ``"punct"``
+
+ * - ``backwards``
+ - | *(Optional)* Specifies whether strings containing diacritics sort from the back of the string
+ to the front.
+ |
+ | **Data Type**: {+bool-data-type+}
+ | **Default**: ``false``
+
+To learn more about collation and the possible values for each field, see the :manual:`Collation `
+entry in the {+mdb-server+} manual.
\ No newline at end of file
diff --git a/source/includes/connect/atlas.php b/source/includes/connect/atlas.php
index 43bb4ab2..bf9cc882 100644
--- a/source/includes/connect/atlas.php
+++ b/source/includes/connect/atlas.php
@@ -5,7 +5,7 @@
// Create a MongoDB client with server API options
$client = new MongoDB\Client($uri, [], [
- 'serverApi' => new MongoDB\Driver\ServerApi('1')
+ 'serverApi' => new MongoDB\Driver\ServerApi('1'),
]);
// Ping the server to verify that the connection works
@@ -15,4 +15,3 @@
echo json_encode($result), PHP_EOL;
echo 'Pinged your deployment. You successfully connected to MongoDB!\n';
-
diff --git a/source/includes/connect/ca-dir.php b/source/includes/connect/ca-dir.php
index 03e88108..7b1c9018 100644
--- a/source/includes/connect/ca-dir.php
+++ b/source/includes/connect/ca-dir.php
@@ -1,11 +1,8 @@
-$uri = 'mongodb://:';
+ true,
-];
+$uri = 'mongodb://:';
-$driverOptions = [
- 'ca_dir' => '/path/to/search/'
-];
+$uriOptions = ['tls' => true];
+$driverOptions = ['ca_dir' => '/path/to/search/'];
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);
diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs.rst
index 57bfd343..7fa15dc5 100644
--- a/source/includes/connect/ca-file-tabs.rst
+++ b/source/includes/connect/ca-file-tabs.rst
@@ -9,7 +9,7 @@
$options = [
'tls' => true,
- 'tlsCAFile' => '/path/to/ca.pem'
+ 'tlsCAFile' => '/path/to/ca.pem',
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/client-cert-tabs.rst b/source/includes/connect/client-cert-tabs.rst
index a93a9185..94d77221 100644
--- a/source/includes/connect/client-cert-tabs.rst
+++ b/source/includes/connect/client-cert-tabs.rst
@@ -9,7 +9,7 @@
$options = [
'tls' => true,
- 'tlsCertificateKeyFile' => '/path/to/client.pem'
+ 'tlsCertificateKeyFile' => '/path/to/client.pem',
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/client.php b/source/includes/connect/client.php
index 48d40f4e..7bde69d9 100644
--- a/source/includes/connect/client.php
+++ b/source/includes/connect/client.php
@@ -1,3 +1,6 @@
10000];
+
+$client = new MongoDB\Client($uri, $uriOptions);
diff --git a/source/includes/connect/connection-options.php b/source/includes/connect/connection-options.php
index f6297065..7af57681 100644
--- a/source/includes/connect/connection-options.php
+++ b/source/includes/connect/connection-options.php
@@ -1,6 +1,8 @@
+:/?tls=true&tlsCertificateKeyFile=/path/to/file.pem";
+$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/file.pem';
// Create a MongoDB client
$client = new MongoDB\Client($uri);
@@ -8,13 +10,13 @@
// start-client-options
// Replace the placeholders with your actual hostname and port
-$uri = "mongodb://:/";
+$uri = 'mongodb://:/';
// Set the connection options
// Replace the placeholder with the actual path to the certificate key file
$uriOptions = [
'tls' => true,
- 'tlsCertificateKeyFile' => '/path/to/file.pem'
+ 'tlsCertificateKeyFile' => '/path/to/file.pem',
];
// Create a MongoDB client with the URI and options
diff --git a/source/includes/connect/crl-file.php b/source/includes/connect/crl-file.php
index 8904c0e4..ef3f134a 100644
--- a/source/includes/connect/crl-file.php
+++ b/source/includes/connect/crl-file.php
@@ -1,11 +1,8 @@
-$uri = 'mongodb://:';
+ true,
-];
+$uri = 'mongodb://:';
-$driverOptions = [
- 'crl_file' => '/path/to/file.pem'
-];
+$uriOptions = ['tls' => true];
+$driverOptions = ['crl_file' => '/path/to/file.pem'];
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);
diff --git a/source/includes/connect/crl-tabs.rst b/source/includes/connect/crl-tabs.rst
index 3784ce06..8caf0b03 100644
--- a/source/includes/connect/crl-tabs.rst
+++ b/source/includes/connect/crl-tabs.rst
@@ -9,7 +9,7 @@
$options = [
'tls' => true,
- 'tlsCRLFile' => '/path/to/crl.pem'
+ 'tlsCRLFile' => '/path/to/crl.pem',
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/direct-connection.php b/source/includes/connect/direct-connection.php
index 665bc3ae..c70f215a 100644
--- a/source/includes/connect/direct-connection.php
+++ b/source/includes/connect/direct-connection.php
@@ -4,4 +4,4 @@
$uri = 'mongodb://:/?directConnection=true';
// Create a MongoDB client
-$client = new MongoDB\Client($uri);
\ No newline at end of file
+$client = new MongoDB\Client($uri);
diff --git a/source/includes/connect/disable-cert-validation-tabs.rst b/source/includes/connect/disable-cert-validation-tabs.rst
index 60e77093..9b1c47e7 100644
--- a/source/includes/connect/disable-cert-validation-tabs.rst
+++ b/source/includes/connect/disable-cert-validation-tabs.rst
@@ -9,7 +9,7 @@
$options = [
'tls' => true,
- 'tlsAllowInvalidCertificates' => true
+ 'tlsAllowInvalidCertificates' => true,
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/disable-host-verification-tabs.rst b/source/includes/connect/disable-host-verification-tabs.rst
index 96cc4cfc..33b2e8cd 100644
--- a/source/includes/connect/disable-host-verification-tabs.rst
+++ b/source/includes/connect/disable-host-verification-tabs.rst
@@ -9,7 +9,7 @@
$options = [
'tls' => true,
- 'tlsAllowInvalidHostnames' => true
+ 'tlsAllowInvalidHostnames' => true,
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/insecure-tls-tabs.rst b/source/includes/connect/insecure-tls-tabs.rst
index e04e56ea..ba1f3158 100644
--- a/source/includes/connect/insecure-tls-tabs.rst
+++ b/source/includes/connect/insecure-tls-tabs.rst
@@ -9,7 +9,7 @@
$options = [
'tls' => true,
- 'tlsInsecure' => true
+ 'tlsInsecure' => true,
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/key-file-password.rst b/source/includes/connect/key-file-password.rst
index a6b2f8ea..200f8189 100644
--- a/source/includes/connect/key-file-password.rst
+++ b/source/includes/connect/key-file-password.rst
@@ -10,7 +10,7 @@
$options = [
'tls' => true,
'tlsCertificateKeyFile' => '/path/to/client.pem',
- 'tlsCertificateKeyFilePassword' => ''
+ 'tlsCertificateKeyFilePassword' => '',
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/network-compression.php b/source/includes/connect/network-compression.php
new file mode 100644
index 00000000..ac96a721
--- /dev/null
+++ b/source/includes/connect/network-compression.php
@@ -0,0 +1,30 @@
+:',
+ ['compressors' => 'snappy,zstd,zlib'],
+);
+// end-enable-client
+
+// start-enable-uri
+$uri = 'mongodb://:/?compressors=snappy,zstd,zlib';
+$client = new MongoDB\Client($uri);
+// end-enable-uri
+
+// start-set-level-client
+$uriOptions = [
+ 'compressors' => 'zlib',
+ 'zlibCompressionLevel' => 1,
+];
+
+$client = new MongoDB\Client(
+ 'mongodb://:',
+ $uriOptions,
+);
+// end-set-level-client
+
+// start-set-level-uri
+$uri = 'mongodb://:/?compressors=zlib&zlibCompressionLevel=1';
+$client = new MongoDB\Client($uri);
+// end-set-level-uri
diff --git a/source/includes/connect/ocsp-tabs.rst b/source/includes/connect/ocsp-tabs.rst
index 467fed14..87978476 100644
--- a/source/includes/connect/ocsp-tabs.rst
+++ b/source/includes/connect/ocsp-tabs.rst
@@ -9,7 +9,7 @@
$options = [
'tls' => true,
- 'tlsDisableOCSPEndpointCheck' => true
+ 'tlsDisableOCSPEndpointCheck' => true,
];
$client = new MongoDB\Client($uri, $options);
diff --git a/source/includes/connect/replica-set.php b/source/includes/connect/replica-set.php
index cd8840fb..c17c6d8f 100644
--- a/source/includes/connect/replica-set.php
+++ b/source/includes/connect/replica-set.php
@@ -3,4 +3,4 @@
$uri = 'mongodb://host1:27017/?replicaSet=sampleRS';
// Create a MongoDB client
-$client = new MongoDB\Client($uri);
\ No newline at end of file
+$client = new MongoDB\Client($uri);
diff --git a/source/includes/connect/stable-api.php b/source/includes/connect/stable-api.php
index f84470c4..4aa087ef 100644
--- a/source/includes/connect/stable-api.php
+++ b/source/includes/connect/stable-api.php
@@ -1,7 +1,7 @@
:";
+$uri = 'mongodb://:';
$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')];
@@ -9,7 +9,7 @@
// end-specify-v1
// start-stable-api-options
-$uri = "mongodb://:";
+$uri = 'mongodb://:';
$serverApi = new MongoDB\Driver\ServerApi('1', strict: true, deprecationErrors: true);
$driverOptions = ['serverApi' => $serverApi];
diff --git a/source/includes/databases-collections/time-series.php b/source/includes/databases-collections/time-series.php
index f12104eb..763c09cf 100644
--- a/source/includes/databases-collections/time-series.php
+++ b/source/includes/databases-collections/time-series.php
@@ -1,5 +1,5 @@
'timestamp',
'metaField' => 'location',
'granularity' => 'minutes',
- ]
+ ],
];
$db->createCollection('sept2023', $options);
@@ -43,6 +43,6 @@
'location' => 'New York City',
'timestamp' => new MongoDB\BSON\UTCDateTime(1695594780000),
],
- ]
+ ],
);
// end-insert-ts
diff --git a/source/includes/extended-json.php b/source/includes/extended-json.php
new file mode 100644
index 00000000..0c4398b7
--- /dev/null
+++ b/source/includes/extended-json.php
@@ -0,0 +1,33 @@
+ [1, 2],
+ 'bar' => ['hello' => 'world'],
+ 'code' => new MongoDB\BSON\Javascript('function x() { return 1; }', []),
+ 'date' => new DateTime('2024-07-20 10:30:00'),
+];
+
+echo 'Relaxed format: ' , MongoDB\BSON\Document::fromPHP($doc)->toRelaxedExtendedJSON(), PHP_EOL;
+echo 'Canonical format: ' , MongoDB\BSON\Document::fromPHP($doc)->toCanonicalExtendedJSON(), PHP_EOL;
+// end-write-extended
+
+// start-read-extended
+$ejsonStr = '{
+ "foo": [
+ { "$numberInt": "1" },
+ { "$numberInt": "2" }
+ ],
+ "bar": { "hello": "world" },
+ "code": {
+ "$code": "function x() { return 1; }",
+ "$scope": {}
+ },
+ "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } }
+}';
+
+$decodedJson = json_decode($ejsonStr, true);
+print_r($decodedJson);
+// end-read-extended
diff --git a/source/includes/extracts-bucket-option.yaml b/source/includes/extracts-bucket-option.yaml
index 1ca8a553..e0a92e68 100644
--- a/source/includes/extracts-bucket-option.yaml
+++ b/source/includes/extracts-bucket-option.yaml
@@ -1,6 +1,6 @@
ref: bucket-option-codec
content: |
- The :doc:`codec ` to use for encoding or decoding documents.
+ The :ref:`php-codecs` to use for encoding or decoding documents.
This option is mutually exclusive with the ``typeMap`` option.
Defaults to the bucket's codec. Inheritance for a default ``codec`` option
diff --git a/source/includes/extracts-collection-option.yaml b/source/includes/extracts-collection-option.yaml
index c293dc62..0ae5d0d0 100644
--- a/source/includes/extracts-collection-option.yaml
+++ b/source/includes/extracts-collection-option.yaml
@@ -1,6 +1,6 @@
ref: collection-option-codec
content: |
- The :doc:`codec ` to use for encoding or decoding documents.
+ The :ref:`php-codecs` to use for encoding or decoding documents.
This option is mutually exclusive with the ``typeMap`` option.
Defaults to the collection's codec. Inheritance for a default ``codec`` option
diff --git a/source/includes/extracts-common-option.yaml b/source/includes/extracts-common-option.yaml
index f75bcd15..350f725e 100644
--- a/source/includes/extracts-common-option.yaml
+++ b/source/includes/extracts-common-option.yaml
@@ -1,6 +1,6 @@
ref: common-option-codec
content: |
- The :doc:`codec ` to use for encoding or decoding documents.
+ The :ref:`php-codecs` to use for encoding or decoding documents.
This option is mutually exclusive with the ``typeMap`` option.
---
ref: common-option-collation
diff --git a/source/includes/get-started/quickstart.php b/source/includes/get-started/quickstart.php
index 58237258..77542dfc 100644
--- a/source/includes/get-started/quickstart.php
+++ b/source/includes/get-started/quickstart.php
@@ -2,10 +2,9 @@
require __DIR__ . '/../vendor/autoload.php';
-use MongoDB\Client;
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException(
- 'Set the MONGODB_URI environment variable to your Atlas URI'
+ 'Set the MONGODB_URI environment variable to your Atlas URI',
);
$client = new MongoDB\Client($uri);
$collection = $client->sample_mflix->movies;
diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php
index f7947e02..e6135374 100644
--- a/source/includes/indexes/indexes.php
+++ b/source/includes/indexes/indexes.php
@@ -33,15 +33,15 @@
// start-index-compound
$indexName = $collection->createIndex(
- ['title' => 1, 'year' => 1]
+ ['title' => 1, 'year' => 1],
);
// end-index-compound
// start-compound-query
-$document = $collection->findOne(
- ['title' => ['$regex' => 'Sunrise'],
- 'year' => ['$gte' => 1990]]
-);
+$document = $collection->findOne([
+ 'title' => ['$regex' => 'Sunrise'],
+ 'year' => ['$gte' => 1990],
+]);
echo json_encode($document), PHP_EOL;
// end-compound-query
@@ -51,7 +51,7 @@
// start-index-array-query
$document = $collection->findOne(
- ['cast' => ['$in' => ['Aamir Khan', 'Kajol']]]
+ ['cast' => ['$in' => ['Aamir Khan', 'Kajol']]],
);
echo json_encode($document), PHP_EOL;
// end-index-array-query
@@ -59,7 +59,7 @@
// start-create-search-index
$searchIndexName = $collection->createSearchIndex(
['mappings' => ['dynamic' => true]],
- ['name' => 'mySearchIdx']
+ ['name' => 'mySearchIdx'],
);
// end-create-search-index
@@ -70,10 +70,10 @@
'type' => 'vector',
'path' => 'plot_embedding',
'numDimensions' => 1536,
- 'similarity' => 'dotProduct'
- ]]
+ 'similarity' => 'dotProduct',
+ ]],
],
- ['name' => 'myVSidx', 'type' => 'vectorSearch']
+ ['name' => 'myVSidx', 'type' => 'vectorSearch'],
);
// end-create-vector-index
@@ -92,11 +92,11 @@
'type' => 'vector',
'path' => 'plot_embedding',
'numDimensions' => 1536,
- 'similarity' => 'dotProduct'
- ]]
+ 'similarity' => 'dotProduct',
+ ]],
],
],
- ]
+ ],
);
// end-create-multiple-indexes
@@ -114,13 +114,13 @@
'fields' => [
'title' => [
'type' => 'string',
- 'analyzer' => 'lucene.simple'
- ]
- ]
- ]]
+ 'analyzer' => 'lucene.simple',
+ ],
+ ],
+ ]],
);
// end-update-search-indexes
// start-delete-search-index
$collection->dropSearchIndex('mySearchIdx');
-// end-delete-search-index
\ No newline at end of file
+// end-delete-search-index
diff --git a/source/includes/monitoring-logging/MyCommandSubscriber.php b/source/includes/monitoring-logging/MyCommandSubscriber.php
new file mode 100644
index 00000000..1f50e6f1
--- /dev/null
+++ b/source/includes/monitoring-logging/MyCommandSubscriber.php
@@ -0,0 +1,32 @@
+stream, sprintf(
+ 'Started command #%d "%s": %s%s',
+ $event->getRequestId(),
+ $event->getCommandName(),
+ MongoDB\BSON\Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(),
+ PHP_EOL,
+ ));
+ }
+
+ public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void
+ {
+ }
+
+ public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void
+ {
+ }
+}
+// end-command-subscriber
diff --git a/source/includes/monitoring-logging/MySdamSubscriber.php b/source/includes/monitoring-logging/MySdamSubscriber.php
new file mode 100644
index 00000000..52e49285
--- /dev/null
+++ b/source/includes/monitoring-logging/MySdamSubscriber.php
@@ -0,0 +1,56 @@
+stream,
+ 'Server opening on %s:%s\n',
+ $event->getHost(),
+ $event->getPort(),
+ PHP_EOL,
+ );
+ }
+
+ public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void
+ {
+ }
+
+ public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void
+ {
+ }
+
+ public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void
+ {
+ }
+
+ public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void
+ {
+ }
+
+ public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void
+ {
+ }
+
+ public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void
+ {
+ }
+
+ public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void
+ {
+ }
+
+ public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void
+ {
+ }
+}
+// end-sdam-subscriber
diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php
new file mode 100644
index 00000000..7df5c778
--- /dev/null
+++ b/source/includes/monitoring-logging/logging.php
@@ -0,0 +1,33 @@
+pushHandler(new StreamHandler(__DIR__ . '/mongodb.log', Logger::DEBUG));
+
+MongoDB\add_logger($logger);
+// end-monolog-logger
+
+// start-custom-logger
+class MyLogger extends Psr\Log\AbstractLogger
+{
+ public array $logs = [];
+
+ public function log(string $level, string|\Stringable $message, array $context = []): void
+ {
+ $this->logs[] = [$level, $message, $context['domain']];
+ }
+}
+
+$customLogger = new MyLogger();
+MongoDB\add_logger($customLogger);
+print_r($customLogger->logs);
+// end-custom-logger
+
+// start-remove-logger
+MongoDB\remove_logger($logger);
+// end-remove-logger
diff --git a/source/includes/monitoring-logging/monitor.php b/source/includes/monitoring-logging/monitor.php
new file mode 100644
index 00000000..b44b5e86
--- /dev/null
+++ b/source/includes/monitoring-logging/monitor.php
@@ -0,0 +1,25 @@
+db->my_coll;
+
+// start-add-subs
+$commandSub = new MyCommandSubscriber(STDERR);
+$sdamSub = new MySDAMSubscriber(STDERR);
+
+$client->addSubscriber($commandSub);
+$client->addSubscriber($sdamSub);
+// end-add-subs
+
+$collection->insertOne(['x' => 100]);
+
+// start-remove-sub
+$client->removeSubscriber($commandSub);
+// end-remove-sub
diff --git a/source/includes/monitoring/sdam.php b/source/includes/monitoring/sdam.php
deleted file mode 100644
index 1647f9d9..00000000
--- a/source/includes/monitoring/sdam.php
+++ /dev/null
@@ -1,49 +0,0 @@
-stream = $stream;
- }
-
- public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void {
- fprintf(
- $this->stream,
- 'Server opening on %s:%s\n',
- $event->getHost(),
- $event->getPort(),
- );
- }
-
- public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void {}
- public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void {}
- public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void {}
- public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void {}
- public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void {}
- public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void {}
- public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void {}
- public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void {}
-}
-// end-mysubscriber
-
-$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI');
-$client = new MongoDB\Client($uri);
-
-$collection = $client->db->my_coll;
-
-// start-add-sub
-$subscriber = new MySubscriber(STDERR);
-$client->addSubscriber($subscriber);
-// end-add-sub
-
-$collection->insertOne(['x' => 100]);
-
-// start-remove-sub
-$client->removeSubscriber($subscriber);
-// end-remove-sub
\ No newline at end of file
diff --git a/source/includes/read-write-pref.php b/source/includes/read-write-pref.php
index 9ce3c7c9..902abc4f 100644
--- a/source/includes/read-write-pref.php
+++ b/source/includes/read-write-pref.php
@@ -1,10 +1,10 @@
updateOne(
['name' => 'Blarney Castle'],
- ['$set' => ['cuisine' => 'Irish']]
+ ['$set' => ['cuisine' => 'Irish']],
);
// end-update-for-change-stream
diff --git a/source/includes/read/change-streams/change-stream.php b/source/includes/read/change-streams/change-stream.php
index 7cba22e9..d583de00 100644
--- a/source/includes/read/change-streams/change-stream.php
+++ b/source/includes/read/change-streams/change-stream.php
@@ -1,5 +1,5 @@
updateOne(
['name' => 'Blarney Castle'],
- ['$set' => ['cuisine' => 'Irish']]
+ ['$set' => ['cuisine' => 'Irish']],
);
// end-update-for-change-stream
diff --git a/source/includes/read/count.php b/source/includes/read/count.php
index e76bbedf..d4e6d617 100644
--- a/source/includes/read/count.php
+++ b/source/includes/read/count.php
@@ -1,7 +1,6 @@
countDocuments(
['number_of_employees' => 50],
- ['limit' => 100]
+ ['limit' => 100],
);
echo 'Number of companies with 50 employees: ', $result;
// end-modify-accurate
diff --git a/source/includes/read/cursor.php b/source/includes/read/cursor.php
index aff1b4ec..ff0e3f90 100644
--- a/source/includes/read/cursor.php
+++ b/source/includes/read/cursor.php
@@ -26,20 +26,20 @@
// Converts the documents stored in a cursor to an array
// start-cursor-array
$cursor = $collection->find(['name' => 'Dunkin\' Donuts']);
-$array_results = $cursor->toArray();
+$resultArray = $cursor->toArray();
// end-cursor-array
// Creates a collection with a maximum size and inserts documents representing vegetables
// start-capped-coll
$db = $client->db;
$db->createCollection(
- 'vegetables',
- ['capped' => true, 'size' => 1024 * 1024]
+ 'vegetables',
+ ['capped' => true, 'size' => 1024 * 1024],
);
$vegetables = [
['name' => 'cauliflower'],
- ['name' => 'zucchini']
+ ['name' => 'zucchini'],
];
$collection = $db->vegetables;
@@ -52,12 +52,12 @@
$cursor = $collection->find([], ['cursorType' => MongoDB\Operation\Find::TAILABLE]);
$cursor->rewind();
-$docs_found = 0;
-while ($docs_found < 3) {
+$docsFound = 0;
+while ($docsFound < 3) {
if ($cursor->valid()) {
$doc = $cursor->current();
echo json_encode($doc), PHP_EOL;
- $docs_found++;
+ $docsFound++;
}
$cursor->next();
}
diff --git a/source/includes/read/distinct.php b/source/includes/read/distinct.php
index 92745a3c..b0e84599 100644
--- a/source/includes/read/distinct.php
+++ b/source/includes/read/distinct.php
@@ -1,7 +1,6 @@
find(
['cuisine' => 'Italian'],
- ['limit' => 5]
+ ['limit' => 5],
);
foreach ($cursor as $doc) {
@@ -24,8 +24,8 @@
// Retrieves documents with a "cuisine" value of "Italian" and sorts in ascending "name" order
// start-sort
$cursor = $collection->find(
- ['cuisine' => 'Italian'],
- ['sort' => ['name' => 1]]
+ ['cuisine' => 'Italian'],
+ ['sort' => ['name' => 1]],
);
foreach ($cursor as $doc) {
@@ -37,7 +37,7 @@
// start-skip
$cursor = $collection->find(
['borough' => 'Manhattan'],
- ['skip' => 10]
+ ['skip' => 10],
);
foreach ($cursor as $doc) {
@@ -64,9 +64,9 @@
// start-return-type
$options = [
'typeMap' => [
- 'root' => 'array',
- 'document' => 'array'
- ]
+ 'root' => 'array',
+ 'document' => 'array',
+ ],
];
$cursor = $collection->find(['cuisine' => 'Hawaiian'], $options);
diff --git a/source/includes/read/retrieve.php b/source/includes/read/retrieve.php
index 27765c96..3419ffb4 100644
--- a/source/includes/read/retrieve.php
+++ b/source/includes/read/retrieve.php
@@ -30,7 +30,7 @@
// start-modify
$results = $collection->find(
['number_of_employees' => 1000],
- ['limit' => 5]
+ ['limit' => 5],
);
foreach ($results as $doc) {
diff --git a/source/includes/read/specify-queries.php b/source/includes/read/specify-queries.php
index 27ce4ebd..8337c10d 100644
--- a/source/includes/read/specify-queries.php
+++ b/source/includes/read/specify-queries.php
@@ -17,7 +17,7 @@
'qty' => 5,
'rating' => 3,
'color' => 'red',
- 'type' => ['fuji', 'honeycrisp']
+ 'type' => ['fuji', 'honeycrisp'],
],
[
'_id' => 2,
@@ -25,22 +25,22 @@
'qty' => 7,
'rating' => 4,
'color' => 'yellow',
- 'type' => ['cavendish']
+ 'type' => ['cavendish'],
],
[
'_id' => 3,
'name' => 'oranges',
'qty' => 6,
'rating' => 2,
- 'type' => ['naval', 'mandarin']
+ 'type' => ['naval', 'mandarin'],
],
[
'_id' => 4,
'name' => 'pineapples',
'qty' => 3,
'rating' => 5,
- 'color' => 'yellow'
- ]
+ 'color' => 'yellow',
+ ],
];
$result = $collection->insertMany($fruits);
@@ -75,8 +75,8 @@
$cursor = $collection->find([
'$or' => [
['qty' => ['$gt' => 5]],
- ['color' => 'yellow']
- ]
+ ['color' => 'yellow'],
+ ],
]);
foreach ($cursor as $doc) {
echo json_encode($doc), PHP_EOL;
diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php
index cc994df0..0d9da013 100644
--- a/source/includes/usage-examples/connect-code-examples.php
+++ b/source/includes/usage-examples/connect-code-examples.php
@@ -28,150 +28,28 @@
$client = new MongoDB\Client($uri);
// end-replica-set-uri
-// Connects to a MongoDB deployment and enables TLS using client
-// options
-// start-enable-tls-client
-$client = new MongoDB\Client(
- 'mongodb://:/',
- ['tls' => true],
-);
-// end-enable-tls-client
-
-// Connects to a MongoDB deployment and enables TLS using connection URI
-// parameters
-// start-enable-tls-uri
-$uri = 'mongodb://:/?tls=true';
-$client = new MongoDB\Client($uri);
-// end-enable-tls-uri
-
-// Connects to a MongoDB deployment, enables TLS, and specifies the path to
-// a CA file using client options
-// start-ca-file-client
-$client = new MongoDB\Client(
- 'mongodb://:/',
- ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'],
-);
-// end-ca-file-client
-
-// Connects to a MongoDB deployment, enables TLS, and specifies the path to
-// a CA file using connection URI parameters
-// start-ca-file-uri
-$uri = 'mongodb://:/?tls=true&tlsCAFile=/path/to/ca.pem';
-$client = new MongoDB\Client($uri);
-// end-ca-file-uri
-
-// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks
-// using client options
-// start-disable-ocsp-client
-$client = new MongoDB\Client(
- 'mongodb://:/',
- ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true],
-);
-// end-disable-ocsp-client
-
-// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks
-// using connection URI parameters
-// start-disable-ocsp-uri
-$uri = 'mongodb://:/?tls=true&tlsDisableOCSPEndpointCheck=true';
-$client = new MongoDB\Client($uri);
-// end-disable-ocsp-uri
-
-// Connects to a TLS-enabled deployment and instructs the driver to check the
-// server certificate against a CRL
-// start-crl
-$client = new MongoDB\Client(
- 'mongodb://:/',
- ['tls' => true],
- ['crl_file' => '/path/to/file.pem'],
-);
-// end-crl
-
-// Presents a client certificate to prove identity
-// using client options
-// start-client-cert-client
-$client = new MongoDB\Client(
- 'mongodb://:/',
- ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'],
-);
-// end-client-cert-client
-
-// Presents a client certificate to prove identity
-// using connection URI parameters
-// start-client-cert-uri
-$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem';
-$client = new MongoDB\Client($uri);
-// end-client-cert-uri
-
-// Specifies the password for a client certificate using client options
-// start-key-file-client
-$client = new MongoDB\Client(
- 'mongodb://:/',
- [
- 'tls' => true,
- 'tlsCertificateKeyFile' => '/path/to/client.pem',
- 'tlsCertificateKeyFilePassword' => ''
- ],
-);
-// end-key-file-client
-
-// Specifies the password for a client certificate using connection URI parameters
-// start-key-file-uri
-$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword=';
-$client = new MongoDB\Client($uri);
-// end-key-file-uri
-
-// Connects to a TLS-enabled deployment and disables server certificate verification
-// using client options
-// start-insecure-tls-client
-$client = new MongoDB\Client(
- 'mongodb://:/',
- ['tls' => true, 'tlsInsecure' => true],
-);
-// end-insecure-tls-client
-
-// Connects to a TLS-enabled deployment and disables server certificate verification
-// using connection URI parameters
-// start-insecure-tls-uri
-$uri = 'mongodb://:/?tls=true&tlsInsecure=true';
-$client = new MongoDB\Client($uri);
-// end-insecure-tls-uri
-
-// Disables certificate validation using client options
-// start-disable-cert-client
+// Connects to a MongoDB deployment and enables the stable API
+// start-stable-api
+$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')];
$client = new MongoDB\Client(
'mongodb://:/',
- ['tls' => true, 'tlsAllowInvalidCertificates' => true],
+ [],
+ $driverOptions,
);
-// end-disable-cert-client
-
-// Disables certificate validation using connection URI parameters
-// start-disable-cert-uri
-$uri = 'mongodb://:/?tls=true&tlsAllowInvalidCertificates=true';
-$client = new MongoDB\Client($uri);
-// end-disable-cert-uri
+// end-stable-api
-// Connects to a TLS-enabled deployment and disables hostname verification
+// Connects to a MongoDB deployment and compresses network traffic
// using client options
-// start-disable-hostname-client
+// start-compression-client
$client = new MongoDB\Client(
- 'mongodb://:/',
- ['tls' => true, 'tlsAllowInvalidHostnames' => true],
+ 'mongodb://:',
+ ['compressors' => 'snappy,zstd,zlib'],
);
-// end-disable-hostname-client
+// end-compression-client
-// Connects to a TLS-enabled deployment and disables hostname verification
+// Connects to a MongoDB deployment and compresses network traffic
// using connection URI parameters
-// start-disable-hostname-uri
-$uri = 'mongodb://:/?tls=true&tlsAllowInvalidHostnames=true';
+// start-compression-uri
+$uri = 'mongodb://:/?compressors=snappy,zstd,zlib';
$client = new MongoDB\Client($uri);
-// end-disable-hostname-uri
-
-// Connects to a MongoDB deployment and enables the stable API
-// start-stable-api
-$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')];
-$client = new MongoDB\Client(
- 'mongodb://:/',
- [],
- $driverOptions,
-);
-// end-stable-api
+// end-compression-uri
diff --git a/source/includes/usage-examples/index-code-examples.php b/source/includes/usage-examples/index-code-examples.php
index 779e3a4e..739a23b8 100644
--- a/source/includes/usage-examples/index-code-examples.php
+++ b/source/includes/usage-examples/index-code-examples.php
@@ -21,7 +21,7 @@ function toJSON(object $document): string
// start-compound
$indexName = $collection->createIndex(
- ['' => 1, '' => 1]
+ ['' => 1, '' => 1],
);
// end-compound
@@ -32,7 +32,7 @@ function toJSON(object $document): string
// start-search-create
$indexName = $collection->createSearchIndex(
['mappings' => ['dynamic' => true]],
- ['name' => '']
+ ['name' => ''],
);
// end-search-create
@@ -50,11 +50,11 @@ function toJSON(object $document): string
'fields' => [
'' => [
'type' => 'string',
- 'analyzer' => 'lucene.standard'
- ]
- ]
- ]]
- );
+ 'analyzer' => 'lucene.standard',
+ ],
+ ],
+ ]],
+);
// end-search-update
// start-search-delete
@@ -67,7 +67,7 @@ function toJSON(object $document): string
// start-geo
$indexName = $collection->createIndex(
- [ '' => '2dsphere']
+ ['' => '2dsphere'],
);
// end-geo
@@ -83,8 +83,8 @@ function toJSON(object $document): string
$options = [
'clusteredIndex' => [
'key' => ['_id' => 1],
- 'unique' => true
- ]
+ 'unique' => true,
+ ],
];
$database->createCollection('', $options);
@@ -98,4 +98,4 @@ function toJSON(object $document): string
// start-remove
$collection->dropIndex('');
-// end-remove
\ No newline at end of file
+// end-remove
diff --git a/source/includes/usage-examples/read-code-examples.php b/source/includes/usage-examples/read-code-examples.php
index b1ce6da9..4bbfef22 100644
--- a/source/includes/usage-examples/read-code-examples.php
+++ b/source/includes/usage-examples/read-code-examples.php
@@ -2,7 +2,6 @@
require_once __DIR__ . '/vendor/autoload.php';
-use MongoDB\Client;
$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);
diff --git a/source/includes/write/bulk-write.php b/source/includes/write/bulk-write.php
index 2e0f9612..fca1ea98 100644
--- a/source/includes/write/bulk-write.php
+++ b/source/includes/write/bulk-write.php
@@ -29,7 +29,7 @@
['borough' => 'Manhattan'],
],
],
- ]
+ ],
);
// end-run-bulk
@@ -50,7 +50,7 @@
],
],
],
- ['ordered' => false]
+ ['ordered' => false],
);
// end-bulk-options
@@ -154,7 +154,7 @@
// start-bulk-client-options
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection(
$restaurantCollection,
- ['ordered' => false]
+ ['ordered' => false],
);
// end-bulk-client-options
diff --git a/source/includes/write/delete.php b/source/includes/write/delete.php
index bab197a6..d943e5ae 100644
--- a/source/includes/write/delete.php
+++ b/source/includes/write/delete.php
@@ -31,4 +31,3 @@
$result = $collection->deleteMany(['cuisine' => 'Greek']);
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;
// end-delete-count
-
diff --git a/source/includes/write/gridfs.php b/source/includes/write/gridfs.php
index 104a90cf..bf233f57 100644
--- a/source/includes/write/gridfs.php
+++ b/source/includes/write/gridfs.php
@@ -1,8 +1,8 @@
db->selectGridFSBucket(
- ['bucketName' => 'myCustomBucket']
+$customBucket = $client->db->selectGridFSBucket(
+ ['bucketName' => 'myCustomBucket'],
);
// end-create-custom-bucket
// Uploads a file called "my_file" to the GridFS bucket and writes data to it
// start-open-upload-stream
$stream = $bucket->openUploadStream('my_file', [
- 'metadata' => ['contentType' => 'text/plain']
+ 'metadata' => ['contentType' => 'text/plain'],
]);
fwrite($stream, 'Data to store');
fclose($stream);
@@ -44,8 +44,8 @@ function toJSON(object $document): string
// Prints information about each file in the bucket
// start-retrieve-file-info
$files = $bucket->find();
-foreach ($files as $file_doc) {
- echo toJSON($file_doc), PHP_EOL;
+foreach ($files as $fileDocument) {
+ echo toJSON($fileDocument), PHP_EOL;
}
// end-retrieve-file-info
@@ -75,8 +75,8 @@ function toJSON(object $document): string
// start-download-to-stream
$file = fopen('/path/to/output_file', 'wb');
$bucket->downloadToStream(
- new ObjectId('66e0a5487c880f844c0a32b1'),
- $file,
+ new ObjectId('66e0a5487c880f844c0a32b1'),
+ $file,
);
// end-download-to-stream
diff --git a/source/includes/write/insert.php b/source/includes/write/insert.php
index 3561a65e..eb95005a 100644
--- a/source/includes/write/insert.php
+++ b/source/includes/write/insert.php
@@ -18,7 +18,7 @@
// start-insert-many
$restaurants = [
['name' => 'Mongo\'s Burgers'],
- ['name' => 'Mongo\'s Pizza']
+ ['name' => 'Mongo\'s Pizza'],
];
$result = $collection->insertMany($restaurants);
@@ -29,9 +29,8 @@
$docs = [
['name' => 'Mongo\'s Burgers'],
['name' => 'Mongo\'s Pizza'],
- ['name' => 'Mongo\'s Tacos']
+ ['name' => 'Mongo\'s Tacos'],
];
$result = $collection->insertMany($docs, ['bypassDocumentValidation' => true]);
// end-modify
-
diff --git a/source/includes/write/replace.php b/source/includes/write/replace.php
index 7c14c806..eb63d4e6 100644
--- a/source/includes/write/replace.php
+++ b/source/includes/write/replace.php
@@ -1,5 +1,5 @@
'Mongo\'s Pizza',
'cuisine' => 'Pizza',
'address' => [
'street' => '123 Pizza St',
'zipCode' => '10003',
],
- 'borough' => 'Manhattan'
+ 'borough' => 'Manhattan',
];
-$result = $collection->replaceOne(['name' => 'Pizza Town'], $replace_document);
+$result = $collection->replaceOne(['name' => 'Pizza Town'], $replaceDocument);
echo 'Modified documents: ', $result->getModifiedCount();
// end-replace-one
// start-replace-options
-$replace_document = [
+$replaceDocument = [
'name' => 'Food World',
'cuisine' => 'Mixed',
'address' => [
'street' => '123 Food St',
'zipCode' => '10003',
],
- 'borough' => 'Manhattan'
+ 'borough' => 'Manhattan',
];
$result = $collection->replaceOne(
['name' => 'Food Town'],
- $replace_document,
- ['upsert' => true]
+ $replaceDocument,
+ ['upsert' => true],
);
// end-replace-options
diff --git a/source/includes/write/run-command.php b/source/includes/write/run-command.php
index ccde87fb..2a63dd58 100644
--- a/source/includes/write/run-command.php
+++ b/source/includes/write/run-command.php
@@ -2,7 +2,6 @@
require __DIR__ . '/vendor/autoload.php';
-use MongoDB\Client;
$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI');
$client = new MongoDB\Client($uri);
@@ -15,8 +14,8 @@
// start-readpref
$readPref = new MongoDB\Driver\ReadPreference('primaryPreferred');
$cursor = $database->command(
- ['hello' => 1],
- ['readPreference' => $readPref]
+ ['hello' => 1],
+ ['readPreference' => $readPref],
);
// end-readpref
diff --git a/source/includes/write/transaction.php b/source/includes/write/transaction.php
index eaa73394..02a4cbc5 100644
--- a/source/includes/write/transaction.php
+++ b/source/includes/write/transaction.php
@@ -1,5 +1,5 @@
bank->checking_accounts;
$saving = $client->bank->saving_accounts;
-$accountId = "5678";
+$accountId = '5678';
$transferAmount = 1000.0;
$callback = function (MongoDB\Driver\Session $session) use (
@@ -17,33 +17,33 @@
$saving,
$receipts,
$accountId,
- $transferAmount
+ $transferAmount,
): void {
$checking->updateOne(
- ["account_id" => $accountId],
- ['$inc' => ["balance" => -$transferAmount]],
- ["session" => $session]
+ ['account_id' => $accountId],
+ ['$inc' => ['balance' => -$transferAmount]],
+ ['session' => $session],
);
$saving->updateOne(
- ["account_id" => $accountId],
- ['$inc' => ["balance" => $transferAmount]],
- ["session" => $session]
+ ['account_id' => $accountId],
+ ['$inc' => ['balance' => $transferAmount]],
+ ['session' => $session],
);
$summary = sprintf('SAVINGS +%1$u CHECKING -%1$u', $transferAmount);
$receipts->insertOne(
[
- "account_id" => $accountId,
- "summary" => $summary,
- "timestamp" => new MongoDB\BSON\UTCDateTime(),
+ 'account_id' => $accountId,
+ 'summary' => $summary,
+ 'timestamp' => new MongoDB\BSON\UTCDateTime(),
],
- ["session" => $session]
+ ['session' => $session],
);
- echo "Successfully performed transaction!", PHP_EOL;
- echo "Summary: ", $summary, PHP_EOL;
+ echo 'Successfully performed transaction!', PHP_EOL;
+ echo 'Summary: ', $summary, PHP_EOL;
};
// end-callback
@@ -53,6 +53,6 @@
try {
MongoDB\with_transaction($session, $callback);
} catch (MongoDB\Driver\Exception\RuntimeException $e) {
- echo "Caught exception: ", $e->getMessage(), PHP_EOL;
+ echo 'Caught exception: ', $e->getMessage(), PHP_EOL;
}
-// end-txn
\ No newline at end of file
+// end-txn
diff --git a/source/includes/write/update.php b/source/includes/write/update.php
index cd43f60c..d79d1bd4 100644
--- a/source/includes/write/update.php
+++ b/source/includes/write/update.php
@@ -13,7 +13,7 @@
// start-update-one
$result = $collection->updateOne(
['name' => 'Bagels N Buns'],
- ['$set' => ['name' => '2 Bagels 2 Buns']]
+ ['$set' => ['name' => '2 Bagels 2 Buns']],
);
// end-update-one
@@ -21,7 +21,7 @@
// start-update-many
$result = $collection->updateMany(
['cuisine' => 'Pizza'],
- ['$set' => ['cuisine' => 'Pasta']]
+ ['$set' => ['cuisine' => 'Pasta']],
);
// end-update-many
@@ -30,7 +30,7 @@
$result = $collection->updateMany(
['borough' => 'Manhattan'],
['$set' => ['borough' => 'Manhattan (north)']],
- ['upsert' => true]
+ ['upsert' => true],
);
// end-update-options
@@ -38,8 +38,7 @@
// start-update-result
$result = $collection->updateMany(
['name' => 'Dunkin\' Donuts'],
- ['$set' => ['name' => 'Dunkin\'']]
+ ['$set' => ['name' => 'Dunkin\'']],
);
echo 'Modified documents: ', $result->getModifiedCount();
// end-update-result
-
diff --git a/source/index.txt b/source/index.txt
index 53398b22..ec6638fc 100644
--- a/source/index.txt
+++ b/source/index.txt
@@ -13,25 +13,21 @@ MongoDB PHP Library
.. toctree::
:titlesonly:
- Get Started
- Connect to MongoDB
+ Getting Started
+ Connect
Databases & Collections
- Read Data
- Write Data
- Operations with Builders
- CRUD Operations & Replica Sets
- Run a Database Command
- Data Aggregation
+ CRUD Operations
+ Aggregation
+ Data Formats
Indexes
- Monitor Your Application
+ Run a Database Command
+ Atlas Search
+ Atlas Vector Search
+ Logging and Monitoring
Security
- Specialized Data Formats
- Deploy to AWS Lambda
- Compatibility
- What's New
- Upgrade
- FAQ
+ Reference
API Documentation
+ Issues & Help
Overview
--------
@@ -65,50 +61,49 @@ Databases and Collections
Learn how to use the {+library-short+} to work with MongoDB databases and collections
in the :ref:`php-databases-collections` section.
-Read Data
----------
+Read and Write Data
+-------------------
-Learn how you can retrieve data from MongoDB in the :ref:`php-read` section.
+Learn how to find, update, and delete data in the :ref:`` section.
-Write Data to MongoDB
----------------------
+Transform Your Data with Aggregation
+------------------------------------
-Learn how you can write data to MongoDB in the :ref:`php-write` section.
+Learn how to use the {+library-short+} to perform aggregation operations in the
+:ref:`php-aggregation` section.
-Operations with Builders
-------------------------
+Data Formats
+------------
-Learn how to use builder classes and factory methods to create queries
-in the :ref:`php-builders` section.
+Learn how to work with specialized data formats and custom types in the
+:ref:`php-data-formats` section.
-Specify How CRUD Operations Run on Replica Sets
------------------------------------------------
+Optimize Queries with Indexes
+-----------------------------
-Learn how to configure settings for read and write operations on replica
-sets in the :ref:`php-read-write-pref` section.
+Learn how to work with common types of indexes in the :ref:`php-indexes`
+section.
Run a Database Command
----------------------
Learn how to run a database command in the :ref:`php-run-command` section.
-Transform Your Data with Aggregation
-------------------------------------
+Atlas Search
+------------
-Learn how to use the {+library-short+} to perform aggregation operations in the
-:ref:`php-aggregation` section.
+Learn how to run Atlas Search queries in the :ref:`` section.
-Optimize Queries with Indexes
------------------------------
+Atlas Vector Search
+-------------------
-Learn how to work with common types of indexes in the :ref:`php-indexes`
-section.
+Learn how to run Atlas Vector Search queries in the :ref:`` section.
-Monitoring
-----------
+Monitoring and Logging
+----------------------
-Learn how to monitor change events in the :ref:`php-monitoring`
-section.
+Learn how to monitor changes to your application and write them to logs in the
+:ref:`` section.
Secure Your Data
----------------
@@ -116,39 +111,14 @@ Secure Your Data
Learn about ways you can authenticate your application and encrypt your data in
the :ref:`php-security` section.
-Specialized Data Formats
-------------------------
-
-Learn how to work with specialized data formats and custom types in the
-:ref:`php-data-formats` section.
-
-Deploy to AWS Lambda
---------------------
+Reference
+---------
-Learn how to deploy a PHP application on AWS Lambda by using Bref in the
-:ref:`php-aws-lambda` section.
+Learn more about {+library-short+} versions, compatibility, and upgrade considerations in the
+:ref:`Reference ` section.
-Compatibility
+Issues & Help
-------------
-See compatibility tables showing the recommended {+library-short+} version to use for
-specific PHP and {+mdb-server+} versions in the :ref:`php-compatibility` section.
-
-What's New
-----------
-
-Learn about new features and changes in each version in the :ref:``
-section.
-
-
-Upgrade Library Versions
-------------------------
-
-Learn what changes you must make to your application to upgrade library and
-extension versions in the :ref:`php-upgrade` section.
-
-FAQ
----
-
-See answers to commonly asked questions about the {+library-short+} in the
-the :ref:`php-faq` section.
+Learn how to report bugs, contribute to the library, and find help in the
+:ref:`Issues & Help ` section.
diff --git a/source/indexes.txt b/source/indexes.txt
index dfe80727..6c44c544 100644
--- a/source/indexes.txt
+++ b/source/indexes.txt
@@ -1,8 +1,8 @@
.. _php-indexes:
-=================================
-Optimize Queries by Using Indexes
-=================================
+==============================
+Indexes for Query Optimization
+==============================
.. contents:: On this page
:local:
diff --git a/source/issues-and-help.txt b/source/issues-and-help.txt
new file mode 100644
index 00000000..bd7af828
--- /dev/null
+++ b/source/issues-and-help.txt
@@ -0,0 +1,80 @@
+.. _php-issues-and-help:
+
+============================
+Report Issues & Request Help
+============================
+
+.. facet::
+ :name: genre
+ :values: reference
+
+.. meta::
+ :keywords: php, troubleshooting, feedback
+ :description: Find support for the PHP library, report bugs or feature requests, and learn how to contribute.
+
+.. contents:: On this page
+ :local:
+ :backlinks: none
+ :depth: 1
+ :class: singlecol
+
+We are lucky to have a vibrant MongoDB PHP community that includes users
+with varying levels of experience using the {+library-short+}. The
+quickest way to get support for general questions is through the
+:community-forum:`MongoDB Community Forums `.
+
+Bugs / Feature Requests
+-----------------------
+
+If you have feedback about the {+library-short+}, visit the `MongoDB
+Feedback Engine `__ and select
+:guilabel:`Drivers` from the list of products on the right side of
+your screen. You can propose improvements, report issues, and provide
+other types of feedback by using this site.
+
+You can also open a case in Jira, our issue management tool, to identify
+bugs or propose improvements. The following steps describe how to create
+a Jira issue:
+
+1. Visit the `MongoDB Jira issue tracker `__ and click the
+ `signup link. `__
+ Create an account, and then log in to Jira.
+#. Navigate to the `PHPLIB Jira project. `__
+#. Click :guilabel:`Create` to create a ticket. Please provide as much
+ information as possible about the issue or request in the ticket.
+
+.. note::
+
+ Bug reports in the PHPLIB Jira project are publicly viewable.
+
+If you've identified a security vulnerability in any official MongoDB
+product, please report it according to the instructions found in the
+:manual:`Create a Vulnerability Report page. `
+
+Pull Requests
+-------------
+
+We are happy to accept contributions to help improve the {+library-short+}. We guide
+user contributions to ensure they meet the standards of the codebase. Ensure
+that any pull requests include documentation, tests, and pass the
+static analysis checks.
+
+To contribute to the library, check out the source and work on a branch:
+
+.. code-block:: bash
+
+ git clone https://github.com/mongodb/mongo-php-library.git
+ cd mongo-php-library
+ composer update
+ git checkout -b myNewFeature
+
+Then, run the library's test suite by using the following command:
+
+.. code-block:: bash
+
+ composer run test
+
+To learn more about the requirements for pull requests, see
+:github:`Contributing to the PHP Library for MongoDB
+
`
+on GitHub.
diff --git a/source/monitoring-logging.txt b/source/monitoring-logging.txt
new file mode 100644
index 00000000..e11b3e16
--- /dev/null
+++ b/source/monitoring-logging.txt
@@ -0,0 +1,23 @@
+.. _php-monitoring:
+.. _php-monitoring-logging:
+
+======================
+Logging and Monitoring
+======================
+
+.. toctree::
+ :caption: Monitoring categories
+
+ Monitoring
+ Change Streams
+ Logging
+
+.. /monitoring/command-monitoring
+.. /monitoring/connection-monitoring
+
+- :ref:`Monitor Application Events `: Monitor changes
+ in your application
+- :ref:`Logging `: Configure logging to receive messages
+ about {+library-short+} events
+- :ref:`Change Streams `: Monitor data changes in
+ your application
diff --git a/source/read/change-streams.txt b/source/monitoring-logging/change-streams.txt
similarity index 96%
rename from source/read/change-streams.txt
rename to source/monitoring-logging/change-streams.txt
index a74b0814..56ea645d 100644
--- a/source/read/change-streams.txt
+++ b/source/monitoring-logging/change-streams.txt
@@ -1,8 +1,8 @@
.. _php-change-streams:
-====================
-Monitor Data Changes
-====================
+================================
+Monitor Data with Change Streams
+================================
.. contents:: On this page
:local:
@@ -38,7 +38,7 @@ database from the :atlas:`Atlas sample datasets `. To access this
from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster
and assign the following value to your ``$collection`` variable:
-.. literalinclude:: /includes/read/change/streams/change-stream.php
+.. literalinclude:: /includes/read/change-streams/change-stream.php
:language: php
:dedent:
:start-after: start-db-coll
@@ -174,7 +174,8 @@ can set in the array:
| This option is mutually exclusive with ``startAfter`` and ``resumeAfter``.
* - ``collation``
- - | Sets the collation to use for the change stream cursor.
+ - | Sets the collation to use for the change stream cursor. To learn more,
+ see the :ref:`php-change-stream-collation` section of this page.
For a full list of ``watch()`` options, see `MongoDB\\Collection::watch()
<{+api+}/method/MongoDBCollection-watch/>`__ in the API
@@ -255,6 +256,13 @@ output:
:manual:`Change Streams with Document Pre- and Post-Images `
in the {+mdb-server+} manual.
+.. _php-change-stream-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
Additional Information
----------------------
diff --git a/source/monitoring-logging/logging.txt b/source/monitoring-logging/logging.txt
new file mode 100644
index 00000000..7eecd8a9
--- /dev/null
+++ b/source/monitoring-logging/logging.txt
@@ -0,0 +1,160 @@
+.. _php-logging:
+
+=================
+Log Driver Events
+=================
+
+.. contents:: On this page
+ :local:
+ :backlinks: none
+ :depth: 2
+ :class: singlecol
+
+.. facet::
+ :name: genre
+ :values: reference
+
+.. meta::
+ :keywords: debugging, printing
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+library-short+} to
+set up and configure **logging**. Logging allows you to receive
+information about database operations, server connections, errors,
+and other events that occur while your application runs.
+
+The {+library-short+} supports `Psr\\Log\\LoggerInterface
+`__, a PSR-3
+logger interface that configures your application to receive log messages.
+You can register one or more instances of a class that implements
+``Psr\Log\LoggerInterface`` to receive log messages. The {+library-short+} is built on top of
+the MongoDB C driver and the {+extension-short+}, so the logger receives event notifications
+from each component.
+
+Configure Logging
+-----------------
+
+To configure your application to receive messages about driver events,
+create an instance of a logger class that implements the ``Psr\Log\LoggerInterface``
+interface. Then, use the ``MongoDB\add_logger()`` function to register
+your logger.
+
+After registering a logger, the {+library-short+} generates log messages
+that resemble the following sample message:
+
+.. code-block:: none
+ :copyable: false
+
+ [0] => Array
+ (
+ [0] => debug
+ [1] => Created client with hash: ...
+ [2] => PHONGO
+ )
+
+The sample log message includes the following information:
+
+- Log level: Indicates the severity of the message. The ``debug`` level corresponds to
+ standard driver activities. To view a list of possible levels, see `PSR\\Log\\LogLevel `__.
+- Message: Describes the logged event, which signals the creation of a new client.
+- Domain string: Specifies the driver component that emitted the log message. The
+ ``PHONGO`` domain indicates that the {+extension-short+} generated the event.
+
+.. note:: Log Message Format
+
+ The preceding example shows a log message stored in an array. However,
+ the format of your log messages might differ depending on your logging
+ implementation.
+
+Create a Monolog Logger
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use `Monolog `__, a
+PHP logging library, to configure logging in your application. Monolog simplifies
+logging configuration by providing a ``Monolog\Logger`` class. This class implements
+the ``Psr\Log\LoggerInterface`` interface and provides handlers that direct logs to
+specified locations.
+
+To use Monolog, install the ``monolog/monolog`` package by running
+the following command:
+
+.. code-block:: shell
+
+ composer require monolog/monolog
+
+Then, you can create a logger by defining a ``Monolog\Logger`` object
+and registering it with the {+library-short+}.
+
+This example performs the following actions:
+
+- Creates a Monolog logger called ``mongodb-logger``
+- Uses a handler to write all logs with a severity of ``debug`` or higher
+ to a file called ``mongodb.log`` in your project directory
+- Registers the logger
+
+.. literalinclude:: /includes/monitoring-logging/logging.php
+ :language: php
+ :start-after: start-monolog-logger
+ :end-before: end-monolog-logger
+ :dedent:
+
+Create a Custom Logger
+~~~~~~~~~~~~~~~~~~~~~~
+
+To create a custom PSR-3 logger, create a class that implements the
+``Psr\Log\LoggerInterface`` interface. You can implement ``Psr\Log\LoggerInterface``
+by defining a class that extends the ``Psr\Log\AbstractLogger`` class.
+``AbstractLogger`` implements ``LoggerInterface`` and a generic ``log()`` method,
+which receives log messages at each severity level.
+
+This example performs the following actions:
+
+- Creates a logger class named ``MyLogger`` that extends the ``AbstractLogger`` class
+ and records the log level, description, and domain of each event
+- Creates a ``MyLogger`` object and registers the logger
+- Prints each log message
+
+.. literalinclude:: /includes/monitoring-logging/logging.php
+ :language: php
+ :start-after: start-custom-logger
+ :end-before: end-custom-logger
+ :dedent:
+
+Remove a Logger
+---------------
+
+To unregister a logger, pass your logger object as a parameter to the ``MongoDB\remove_logger()``
+function. After calling this function, your logger no longer receives log
+messages about your application.
+
+The following example unregisters a logger:
+
+.. literalinclude:: /includes/monitoring-logging/logging.php
+ :language: php
+ :start-after: start-remove-logger
+ :end-before: end-remove-logger
+ :dedent:
+
+Additional Information
+----------------------
+
+To learn more about PSR-3 loggers, see `PSR-3: Logger Interface
+`__ in the PHP-FIG documentation.
+
+To learn more about Monolog, see the :github:`monolog `
+GitHub repository.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the {+library-short+} methods discussed in this guide, see the
+following API documentation:
+
+- :phpmethod:`MongoDB\add_logger()`
+- :phpmethod:`MongoDB\remove_logger()`
+
+To learn more about how the underlying C driver generates log messages, see `Logging
+`__ in the ``libmongoc``
+API documentation.
diff --git a/source/monitoring-logging/monitoring.txt b/source/monitoring-logging/monitoring.txt
new file mode 100644
index 00000000..b930eef3
--- /dev/null
+++ b/source/monitoring-logging/monitoring.txt
@@ -0,0 +1,268 @@
+.. _php-cluster-monitoring:
+.. _php-monitoring:
+
+==========================
+Monitor Application Events
+==========================
+
+.. facet::
+ :name: genre
+ :values: reference
+
+.. meta::
+ :keywords: code example, server, topology
+
+.. contents:: On this page
+ :local:
+ :backlinks: none
+ :depth: 2
+ :class: singlecols
+
+Overview
+--------
+
+In this guide, you can learn how to set up and configure **monitoring**
+in the {+php-library+}.
+
+Monitoring is the process of gathering information about your application's
+behavior as it runs. This information can help you make informed decisions when
+designing and debugging your application. You can also use information from monitoring
+events to track your application's performance and resource use.
+
+The {+php-library+} emits command events and Server Discovery and Monitoring (SDAM)
+events that provide application information. You can listen for these events to
+monitor your application.
+
+.. note::
+
+ This page explains how to monitor your application in code. To learn how to
+ record this information to an external log, see the :ref:`php-logging` guide.
+
+Event Types
+-----------
+
+The type of event that the driver emits depends on the operation being performed.
+The following table describes the types of events that the driver emits:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Event Type
+ - Description
+
+ * - Command events
+ - Events related to MongoDB database commands, such as ``find``, ``insert``,
+ ``delete``, and ``count``. To learn how to use the {+library-short+} to run a
+ database command, see :ref:``. For more information about
+ MongoDB database commands, see :manual:`Database Commands `
+ in the {+mdb-server+} manual.
+
+ * - Server Discovery and Monitoring (SDAM) events
+ - Events related to changes in the state of the MongoDB deployment.
+
+Monitor Events
+--------------
+
+To monitor events, you must perform the following actions:
+
+1. :ref:`php-subscribe`: Create a class that implements the command or
+ SDAM event subscriber
+#. :ref:`php-register`: Register a monitoring event subscriber with your
+ ``MongoDB\Client``
+
+.. tip::
+
+ To view a list of monitoring events to which you can subscribe, see the
+ :php:`Monitoring classes and subscriber functions `
+ section of the PHP manual.
+
+.. _php-subscribe:
+
+Create an Event Subscriber
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To subscribe to a monitoring event, create a class that implements the
+event subscriber interface. You can implement the following interfaces:
+
+- ``MongoDB\Driver\Monitoring\CommandSubscriber``, which subscribes to
+ command events
+- ``MongoDB\Driver\Monitoring\SDAMSubscriber``, which subscribes to
+ SDAM events
+
+.. _php-subscribe-command:
+
+Command Event Subscriber Example
+````````````````````````````````
+
+To subscribe to an SDAM event, create a class that implements the
+``MongoDB\Driver\Monitoring\CommandSubscriber`` interface. In your
+class, define each of the ``CommandSubscriber`` methods. The following
+table describes these methods and the command events they receive notifications
+for:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 20 50
+
+ * - Method
+ - Command Event
+ - Description
+
+ * - :php:`commandFailed() `
+ - :php:`CommandFailedEvent `
+ - Called when a command does not succeed
+
+ * - :php:`commandStarted() `
+ - :php:`CommandStartedEvent `
+ - Called when a command is sent to the server
+
+ * - :php:`commandSucceeded() `
+ - :php:`CommandSucceededEvent `
+ - Called when a command succeeds
+
+The following code creates the ``MyCommandSubscriber`` class, which implements
+the ``CommandSubscriber`` interface. The class defines each ``CommandSubscriber`` method
+and includes custom logic for the ``commandStarted()`` method, which prints details
+about each new command that the server receives:
+
+.. literalinclude:: /includes/monitoring-logging/MyCommandSubscriber.php
+ :start-after: start-command-subscriber
+ :end-before: end-command-subscriber
+ :language: php
+ :copyable:
+ :dedent:
+
+.. _php-subscribe-sdam:
+
+SDAM Event Subscriber Example
+`````````````````````````````
+
+To subscribe to an SDAM event, create a class that implements the
+``MongoDB\Driver\Monitoring\SDAMSubscriber`` interface. In your
+class, define each ``SDAMSubscriber`` method. The following
+table describes these methods and the command events they receive
+notifications for:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 20 50
+
+ * - Method
+ - SDAM Event
+ - Description
+
+ * - :php:`serverChanged() `
+ - :php:`ServerChangedEvent `
+ - Called when a server's description changes
+
+ * - :php:`serverClosed() `
+ - :php:`ServerClosedEvent `
+ - Called when a server is removed from the topology
+
+ * - :php:`serverHeartbeatFailed() `
+ - :php:`ServerHeartbeatFailedEvent `
+ - Called when a server heartbeat is unsuccessful
+
+ * - :php:`serverHeartbeatStarted() `
+ - :php:`ServerHeartbeatStartedEvent `
+ - Called when the server receives a heartbeat
+
+ * - :php:`serverHeartbeatSucceeded() `
+ - :php:`ServerHeartbeatSucceededEvent `
+ - Called when a server heartbeat succeeds
+
+ * - :php:`serverOpening() `
+ - :php:`ServerOpeningEvent `
+ - Called when a new server is added to the topology
+
+ * - :php:`topologyChanged() `
+ - :php:`TopologyChangedEvent `
+ - Called when the topology description changes
+
+ * - :php:`topologyClosed() `
+ - :php:`TopologyClosedEvent `
+ - Called when the topology is closed
+
+ * - :php:`topologyOpening() `
+ - :php:`TopologyOpeningEvent `
+ - Called when the topology is opened
+
+The following code creates the ``MySDAMSubscriber`` class, which implements
+the ``SDAMSubscriber`` interface. The class defines each ``SDAMSubscriber`` method
+and includes custom logic for the ``serverOpening()`` method, which prints details
+about servers added to the topology:
+
+.. literalinclude:: /includes/monitoring-logging/MySdamSubscriber.php
+ :start-after: start-sdam-subscriber
+ :end-before: end-sdam-subscriber
+ :language: php
+ :copyable:
+ :dedent:
+
+.. _php-register:
+
+Register an Event Subscriber
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After creating a class that implements your subscriber interface,
+you must register this class with a ``MongoDB\Client`` to receive
+event notifications for your client. To register a subscriber, call the
+``MongoDB\Client::addSubscriber()`` method and pass an instance
+of your subscriber class as a parameter.
+
+Example
+```````
+
+The following code registers the command and SDAM event subscribers
+created in the :ref:`php-subscribe` section of this page with a
+``MongoDB\Client``:
+
+.. literalinclude:: /includes/monitoring-logging/monitor.php
+ :start-after: start-add-subs
+ :end-before: end-add-subs
+ :language: php
+ :copyable:
+ :dedent:
+
+When you start the application and run an insert command, your subscribers
+record the events and output messages that resemble the following:
+
+.. code-block:: none
+ :copyable: false
+
+ Server opening on ac-rmuag0v-shard-00-00.gh0qg50.mongodb.net:27017
+ Server opening on ac-rmuag0v-shard-00-01.gh0qg50.mongodb.net:27017
+ Server opening on ac-rmuag0v-shard-00-02.gh0qg50.mongodb.net:27017
+ Started command #3 "insert": { "insert" : ... }
+
+Remove a Subscriber
+-------------------
+
+To unregister a subscriber from your client, use the
+``MongoDB\Client::removeSubscriber()`` method.
+
+The following code shows how to remove the subscriber created in
+the :ref:`php-subscribe-command` section of this page:
+
+.. literalinclude:: /includes/monitoring-logging/monitor.php
+ :start-after: start-remove-sub
+ :end-before: end-remove-sub
+ :language: php
+ :copyable:
+ :dedent:
+
+API Documentation
+-----------------
+
+To learn more about any of the classes or methods discussed in this guide, see the
+following API documentation:
+
+- :phpmethod:`MongoDB\Client::addSubscriber()`
+- :phpmethod:`MongoDB\Client::removeSubscriber()`
+
+To learn more about subscriber classes and methods, see the following
+pages in the PHP manual:
+
+- :php:`MongoDB\Driver\Monitoring\CommandSubscriber `
+- :php:`MongoDB\Driver\Monitoring\SDAMSubscriber `
diff --git a/source/monitoring.txt b/source/monitoring.txt
deleted file mode 100644
index 43d15f27..00000000
--- a/source/monitoring.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-.. _php-monitoring:
-
-========================
-Monitor Your Application
-========================
-
-.. toctree::
- :caption: Monitoring categories
-
- Cluster Monitoring
-
-.. /monitoring/command-monitoring
-.. /monitoring/connection-monitoring
-
-- :ref:`Cluster Monitoring `: Monitor changes
- in your cluster configuration
-
-.. TODO - :ref:`Command Monitoring `: monitor command
-.. execution
-.. - :ref:`Connection Pool Monitoring `:
-.. monitor changes in the connection pool
\ No newline at end of file
diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt
deleted file mode 100644
index 0093aa47..00000000
--- a/source/monitoring/cluster-monitoring.txt
+++ /dev/null
@@ -1,163 +0,0 @@
-.. _php-cluster-monitoring:
-
-==================
-Cluster Monitoring
-==================
-
-.. facet::
- :name: genre
- :values: reference
-
-.. meta::
- :keywords: code example, server, topology
-
-.. contents:: On this page
- :local:
- :backlinks: none
- :depth: 2
- :class: singlecols
-
-Overview
---------
-
-This guide shows you how to use the {+php-library+} to monitor server
-discovery and monitoring (SDAM) events in a MongoDB instance, replica
-set, or sharded cluster. These events occur when there are any changes
-in the state of the MongoDB instance or cluster that you are connected
-to.
-
-You might use information about SDAM events in your application to
-understand cluster changes, assess cluster health, or perform capacity
-planning.
-
-.. _php-subscribe-sdam:
-
-Subscribe to Events
--------------------
-
-You can access details about SDAM events by subscribing to them
-in your application. To subscribe to an event, create a class that
-implements the ``MongoDB\Driver\Monitoring\SDAMSubscriber`` interface,
-then use the ``MongoDB\Client::addSubscriber()`` method to register the
-event subscriber with your ``MongoDB\Client`` instance.
-
-The following code creates the ``MySubscriber`` class, which implements
-the ``SDAMSubscriber`` interface. The class is defined with a method to
-output a message when a ``ServerOpeningEvent`` is generated by the
-server:
-
-.. literalinclude:: /includes/monitoring/sdam.php
- :start-after: start-mysubscriber
- :end-before: end-mysubscriber
- :language: php
- :copyable:
- :dedent:
-
-.. note::
-
- As shown in the preceding code, you must implement all the methods
- of the ``SDAMSubscriber`` interface, even for events you are not subscribing to.
- The example defines the extra methods as empty so that the
- application does not output any messages for those events.
-
-Then, use the ``addSubscriber()`` method to register ``MySubscriber``
-with the client, as shown in the following code:
-
-.. literalinclude:: /includes/monitoring/sdam.php
- :start-after: start-add-sub
- :end-before: end-add-sub
- :language: php
- :copyable:
- :dedent:
-
-When you run the application, your subscriber records the SDAM event and
-outputs messages such as the following:
-
-.. code-block:: none
- :copyable: false
-
- Server opening on ac-rmuag0v-shard-00-00.gh0qg50.mongodb.net:27017
- Server opening on ac-rmuag0v-shard-00-01.gh0qg50.mongodb.net:27017
- Server opening on ac-rmuag0v-shard-00-02.gh0qg50.mongodb.net:27017
-
-Event Descriptions
-------------------
-
-You can subscribe to SDAM events by implementing the corresponding
-method from the ``SDAMSubscriber`` interface. The following table
-provides the name of each SDAM event, linked to the class's API
-documentation, and a description of when the event is published:
-
-.. list-table::
- :widths: 35 65
- :header-rows: 1
-
- * - Event Type
- - Description
-
- * - :php:`ServerChangedEvent `
- - Created when the server description changes, such as the server's
- type changing from secondary to primary.
-
- * - :php:`ServerOpeningEvent `
- - Created when a new server is added to the topology.
-
- * - :php:`ServerClosedEvent `
- - Created when an existing server is removed from the topology.
-
- * - :php:`TopologyChangedEvent `
- - Created when the topology description changes, such as when there
- is an election of a new primary.
-
- * - :php:`TopologyOpeningEvent `
- - Created when the driver first connects to the cluster.
-
- * - :php:`TopologyClosedEvent `
- - Created when the driver disconnects from the cluster.
-
- * - :php:`ServerHeartbeatStartedEvent `
- - Created when the server monitor sends a ``hello`` command to the server.
- This action is called a heartbeat.
-
- * - :php:`ServerHeartbeatSucceededEvent `
- - Created when the heartbeat succeeds.
-
- * - :php:`ServerHeartbeatFailedEvent `
- - Created when the heartbeat fails.
-
-You can find a list of the monitoring subscriber classes and event
-methods in the :php:`Monitoring classes and subscriber functions
-` section of the PHP manual.
-
-Remove a Subscriber
--------------------
-
-Later in your application, you might not want to subscribe to
-SDAM events. To unregister a subscriber from your client, use the
-``MongoDB\Client::removeSubscriber()`` method. If you attempt to remove
-a nonexistent subscriber, the method doesn't perform any action.
-
-The following code shows how to remove the subscriber that you
-registered in the :ref:`php-subscribe-sdam` section:
-
-.. literalinclude:: /includes/monitoring/sdam.php
- :start-after: start-remove-sub
- :end-before: end-remove-sub
- :language: php
- :copyable:
- :dedent:
-
-API Documentation
------------------
-
-To learn more about any of the classes or methods discussed in this guide, see the
-following API documentation:
-
-- :phpmethod:`MongoDB\Client::addSubscriber()`
-- :phpmethod:`MongoDB\Client::removeSubscriber()`
-
-To learn more about subscriber classes and methods, see the following
-pages in the PHP manual:
-
-- :php:`MongoDB\Driver\Monitoring\SDAMSubscriber `
-- :php:`MongoDB\Driver\Monitoring\ServerOpeningEvent `
diff --git a/source/read.txt b/source/read.txt
deleted file mode 100644
index 10dc8d84..00000000
--- a/source/read.txt
+++ /dev/null
@@ -1,167 +0,0 @@
-.. _php-read:
-
-=========
-Read Data
-=========
-
-.. contents:: On this page
- :local:
- :backlinks: none
- :depth: 2
- :class: singlecol
-
-.. facet::
- :name: genre
- :values: reference
-
-.. meta::
- :description: Learn how to use the PHP Library to read data to MongoDB.
- :keywords: usage examples, save, crud, read, code example
-
-.. toctree::
- :titlesonly:
- :maxdepth: 1
-
- Retrieve Data
- Specify Fields to Return
- Access Data from a Cursor
- Count Documents
- Specify Documents to Return
- Specify a Query
- Distinct Field Values
- Monitor Changes
-
-Overview
---------
-
-On this page, you can see copyable code examples that show common
-{+library-short+} methods for retrieving documents.
-
-.. tip::
-
- To learn more about any of the methods shown on this page, see the link
- provided in each section.
-
-To use an example from this page, copy the code example into the
-:ref:`sample application ` or your own application.
-Make sure to set the ``MONGODB_URI`` environment variable to the
-connection string for your MongoDB deployment, and replace the
-```` and ```` placeholders with values for your
-target namespace.
-
-.. _php-read-sample:
-
-.. include:: /includes/usage-examples/sample-app-intro.rst
-
-.. literalinclude:: /includes/usage-examples/sample-app.php
- :language: php
- :dedent:
- :linenos:
- :emphasize-lines: 10-12
-
-Find One
---------
-
-The following code shows how to retrieve a single document from a collection
-that matches the specified criteria:
-
-.. literalinclude:: /includes/usage-examples/read-code-examples.php
- :start-after: start-find-one
- :end-before: end-find-one
- :language: php
- :dedent:
-
-To learn more about the ``findOne()`` method, see the :ref:`php-retrieve-find-one`
-section in the Retrieve Data guide.
-
-.. _php-find-many-documents:
-
-Find Multiple
--------------
-
-The following code shows how to retrieve all documents from a collection
-that match the specified criteria:
-
-.. literalinclude:: /includes/usage-examples/read-code-examples.php
- :start-after: start-find-multiple
- :end-before: end-find-multiple
- :language: php
- :dedent:
-
-To learn more about the ``find()`` method, see the :ref:`php-retrieve-find-multiple`
-section in the Retrieve Data guide.
-
-Count Documents in a Collection
--------------------------------
-
-The following code shows how to count the number of documents in
-a collection:
-
-.. literalinclude:: /includes/usage-examples/read-code-examples.php
- :start-after: start-count
- :end-before: end-count
- :language: php
- :dedent:
-
-To learn more about the ``countDocuments()`` method, see the
-:ref:`php-count-all` section in the Count Documents guide.
-
-Count Documents Returned from a Query
--------------------------------------
-
-The following code shows how to count documents in a collection
-that match the specified criteria:
-
-.. literalinclude:: /includes/usage-examples/read-code-examples.php
- :start-after: start-count-specific
- :end-before: end-count-specific
- :language: php
- :dedent:
-
-To learn more about the ``countDocuments()`` method, see the
-:ref:`php-count-specific` section in the Count Documents guide.
-
-Estimated Document Count
-------------------------
-
-The following code shows how to retrieve an estimated count of the
-number of documents in a collection:
-
-.. literalinclude:: /includes/usage-examples/read-code-examples.php
- :start-after: start-count-estimate
- :end-before: end-count-estimate
- :language: php
- :dedent:
-
-To learn more about the ``estimatedDocumentCount()`` method, see the
-:ref:`php-estimated-count` section in the Count Documents guide.
-
-Retrieve Distinct Values
-------------------------
-
-The following code shows how to retrieve the unique values of a field
-for documents that match the specified criteria:
-
-.. literalinclude:: /includes/usage-examples/read-code-examples.php
- :start-after: start-distinct
- :end-before: end-distinct
- :language: php
- :dedent:
-
-To learn more about the ``distinct()`` method, see the
-:ref:`php-distinct` guide.
-
-Monitor Data Changes
---------------------
-
-The following code shows how to monitor and print changes to a
-collection:
-
-.. literalinclude:: /includes/usage-examples/read-code-examples.php
- :start-after: start-change-stream
- :end-before: end-change-stream
- :language: php
- :dedent:
-
-To learn more about the ``watch()`` method, see the
-:ref:`php-change-streams` guide.
diff --git a/source/reference/class/MongoDBModelCollectionInfo.txt b/source/reference/class/MongoDBModelCollectionInfo.txt
index a869b322..21b2dbb9 100644
--- a/source/reference/class/MongoDBModelCollectionInfo.txt
+++ b/source/reference/class/MongoDBModelCollectionInfo.txt
@@ -39,6 +39,7 @@ Methods
getOptions()
getType()
isCapped()
+ isView()
- :phpmethod:`MongoDB\Model\CollectionInfo::getCappedMax()`
- :phpmethod:`MongoDB\Model\CollectionInfo::getCappedSize()`
@@ -47,4 +48,5 @@ Methods
- :phpmethod:`MongoDB\Model\CollectionInfo::getName()`
- :phpmethod:`MongoDB\Model\CollectionInfo::getOptions()`
- :phpmethod:`MongoDB\Model\CollectionInfo::getType()`
-- :phpmethod:`MongoDB\Model\CollectionInfo::isCapped()`
\ No newline at end of file
+- :phpmethod:`MongoDB\Model\CollectionInfo::isCapped()`
+- :phpmethod:`MongoDB\Model\CollectionInfo::isView()`
diff --git a/source/reference/method/MongoDBClient-getCollection.txt b/source/reference/method/MongoDBClient-getCollection.txt
index d6adb303..faefbf54 100644
--- a/source/reference/method/MongoDBClient-getCollection.txt
+++ b/source/reference/method/MongoDBClient-getCollection.txt
@@ -47,7 +47,7 @@ Parameters
* - codec
- MongoDB\\Codec\\DocumentCodec
- - The default :doc:`codec ` to use for collection
+ - The default :ref:`php-codecs` to use for collection
operations.
.. versionadded:: 1.17
diff --git a/source/reference/method/MongoDBClient-selectCollection.txt b/source/reference/method/MongoDBClient-selectCollection.txt
index aa2fdb29..d5fe57f2 100644
--- a/source/reference/method/MongoDBClient-selectCollection.txt
+++ b/source/reference/method/MongoDBClient-selectCollection.txt
@@ -50,7 +50,7 @@ Parameters
* - codec
- MongoDB\\Codec\\DocumentCodec
- - The default :doc:`codec ` to use for collection
+ - The default :ref:`php-codecs` to use for collection
operations.
.. versionadded:: 1.17
diff --git a/source/reference/method/MongoDBCollection__construct.txt b/source/reference/method/MongoDBCollection__construct.txt
index 35fdf3df..d532ec0f 100644
--- a/source/reference/method/MongoDBCollection__construct.txt
+++ b/source/reference/method/MongoDBCollection__construct.txt
@@ -60,7 +60,7 @@ Definition
* - codec
- MongoDB\\Codec\\DocumentCodec
- - The default :doc:`codec ` to use for collection
+ - The default :ref:`php-codecs` to use for collection
operations.
.. versionadded:: 1.17
diff --git a/source/reference/method/MongoDBDatabase-getCollection.txt b/source/reference/method/MongoDBDatabase-getCollection.txt
index 1255c300..3dd2b813 100644
--- a/source/reference/method/MongoDBDatabase-getCollection.txt
+++ b/source/reference/method/MongoDBDatabase-getCollection.txt
@@ -43,7 +43,7 @@ Parameters
* - codec
- MongoDB\\Codec\\DocumentCodec
- - The default :doc:`codec ` to use for collection
+ - The default :ref:`php-codecs` to use for collection
operations.
.. versionadded:: 1.17
diff --git a/source/reference/method/MongoDBDatabase-selectCollection.txt b/source/reference/method/MongoDBDatabase-selectCollection.txt
index f27fb8a7..9e7db979 100644
--- a/source/reference/method/MongoDBDatabase-selectCollection.txt
+++ b/source/reference/method/MongoDBDatabase-selectCollection.txt
@@ -43,7 +43,7 @@ Parameters
* - codec
- MongoDB\\Codec\\DocumentCodec
- - The default :doc:`codec ` to use for collection
+ - The default :ref:`php-codecs` to use for collection
operations.
.. versionadded:: 1.17
diff --git a/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt b/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt
index 174c0d31..6b76b752 100644
--- a/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt
+++ b/source/reference/method/MongoDBDatabase-selectGridFSBucket.txt
@@ -48,7 +48,7 @@ Parameters
* - codec
- MongoDB\\Codec\\DocumentCodec
- - The default :doc:`codec ` to use for bucket methods
+ - The default :ref:`php-codecs` to use for bucket methods
that return a file document (e.g. :phpmethod:`MongoDB\GridFS\Bucket::find()`).
.. versionadded:: 1.17
diff --git a/source/reference/method/MongoDBGridFSBucket__construct.txt b/source/reference/method/MongoDBGridFSBucket__construct.txt
index 3c9d429e..c0f2939c 100644
--- a/source/reference/method/MongoDBGridFSBucket__construct.txt
+++ b/source/reference/method/MongoDBGridFSBucket__construct.txt
@@ -56,7 +56,7 @@ Parameters
* - codec
- MongoDB\\Codec\\DocumentCodec
- - The default :doc:`codec ` to use for bucket methods
+ - The default :ref:`php-codecs` to use for bucket methods
that return a file document (e.g. :phpmethod:`MongoDB\GridFS\Bucket::find()`).
.. versionadded:: 1.17
diff --git a/source/reference/method/MongoDBModelCollectionInfo-isView.txt b/source/reference/method/MongoDBModelCollectionInfo-isView.txt
new file mode 100644
index 00000000..074aa1a9
--- /dev/null
+++ b/source/reference/method/MongoDBModelCollectionInfo-isView.txt
@@ -0,0 +1,53 @@
+========================================
+MongoDB\\Model\\CollectionInfo::isView()
+========================================
+
+.. contents:: On this page
+ :local:
+ :backlinks: none
+ :depth: 1
+ :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\Model\CollectionInfo::isView()
+
+ Return whether the collection is a :manual:`view `.
+
+ .. code-block:: php
+
+ function isView(): boolean
+
+Return Values
+-------------
+
+A boolean indicating whether the collection is a view.
+
+Examples
+--------
+
+.. code-block:: php
+
+ 'foo',
+ 'type' => 'view',
+ 'info' => ['readOnly' => true],
+ ]);
+
+ var_dump($info->isView());
+
+The output resembles the following:
+
+.. code-block:: none
+
+ bool(true)
+
+See Also
+--------
+
+- :manual:`Views ` in the {+mdb-server+} manual
+- :manual:`Create and Query a View ` in the
+ {+mdb-server+} manual
diff --git a/source/references.txt b/source/references.txt
new file mode 100644
index 00000000..361ddefd
--- /dev/null
+++ b/source/references.txt
@@ -0,0 +1,20 @@
+.. _php-reference:
+
+=========
+Reference
+=========
+
+.. toctree::
+ :titlesonly:
+ :maxdepth: 1
+
+ Release Notes
+ Compatibility
+ Upgrade
+
+To learn about the differences between versions of
+the {+library-short+}, view the following guides:
+
+- :ref:`php-release-notes`
+- :ref:`php-compatibility`
+- :ref:`php-upgrade`
\ No newline at end of file
diff --git a/source/compatibility.txt b/source/references/compatibility.txt
similarity index 100%
rename from source/compatibility.txt
rename to source/references/compatibility.txt
diff --git a/source/whats-new.txt b/source/references/release-notes.txt
similarity index 99%
rename from source/whats-new.txt
rename to source/references/release-notes.txt
index 102da67e..147fa614 100644
--- a/source/whats-new.txt
+++ b/source/references/release-notes.txt
@@ -1,8 +1,9 @@
.. _php-lib-whats-new:
+.. _php-release-notes:
-==========
-What's New
-==========
+=============
+Release Notes
+=============
.. facet::
:name: genre
diff --git a/source/upgrade.txt b/source/references/upgrade.txt
similarity index 94%
rename from source/upgrade.txt
rename to source/references/upgrade.txt
index 5c0c8fe8..df98d8c4 100644
--- a/source/upgrade.txt
+++ b/source/references/upgrade.txt
@@ -58,7 +58,16 @@ directory:
.. code-block:: bash
- pecl upgrade mongodb-
+ pie install mongodb/mongodb-extension:^
+
+.. tip:: Previous PHP Extension Versions
+
+ To upgrade to a {+extension-short+} version before v1.21,
+ use the following command:
+
+ .. code-block:: bash
+
+ pecl upgrade mongodb-
To upgrade the PHP library version, replace ```` with the
version number you want to upgrade to and run the following command in your
diff --git a/source/security.txt b/source/security.txt
index 310321a9..20a70c35 100644
--- a/source/security.txt
+++ b/source/security.txt
@@ -23,12 +23,13 @@ Secure Your Data
:maxdepth: 1
Authentication
- Encryption
+ In-Use Encryption
+ TLS
Overview
--------
-MongoDB supports multiple mechanisms that you can use to authenticate your application.
+MongoDB supports multiple mechanisms that secure your database connection.
This page contains code examples that demonstrate each of these mechanisms.
.. tip::
@@ -36,7 +37,7 @@ This page contains code examples that demonstrate each of these mechanisms.
To learn more about any of the mechanisms shown on this page, see the link
provided in each section.
-To use an authentication example from this page, copy the code example into the
+To use an example from this page, copy the code example into the
:ref:`sample application ` or your own application.
Make sure to replace all placeholders in the code examples, such as ````, with
the relevant values for your MongoDB deployment.
@@ -193,3 +194,268 @@ credentials, see the following sections in the Authentication guide:
- :ref:`php-mongodb-aws-oidc`
- :ref:`php-mongodb-aws-ecs`
- :ref:`php-mongodb-aws-ec2`
+
+Transport Layer Security (TLS)
+------------------------------
+
+Enable TLS
+~~~~~~~~~~
+
+The following code shows how to enable TLS for the connection to your
+MongoDB instance:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-enable-tls-client
+ :end-before: end-enable-tls-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-enable-tls-uri
+ :end-before: end-enable-tls-uri
+
+To learn more about enabling TLS, see :ref:`php-enable-tls` in
+the TLS Configuration guide.
+
+Specify a Certificate Authority (CA) File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to specify the path to your CA file
+for the connection to your MongoDB instance:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-ca-file-client
+ :end-before: end-ca-file-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-ca-file-uri
+ :end-before: end-ca-file-uri
+
+To learn more about specifying a CA file, see :ref:`php-specify-ca-file` in
+the TLS Configuration guide.
+
+Disable OCSP Checks
+~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to prevent the driver from contacting
+the OCSP endpoint:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-disable-ocsp-client
+ :end-before: end-disable-ocsp-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-disable-ocsp-uri
+ :end-before: end-disable-ocsp-uri
+
+To learn more about disabling OCSP checks, see :ref:`php-disable-ocsp` in
+the TLS Configuration guide.
+
+Specify a Certificate Revocation List (CRL)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to instruct the driver to verify the server's
+certificate against a CRL:
+
+.. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-crl
+ :end-before: end-crl
+
+To learn more about specifying a CRL, see :ref:`php-crl` in the TLS
+configuration guide.
+
+Present a Client Certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to specify the client certificate that
+the driver presents to your MongoDB deployment:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-client-cert-client
+ :end-before: end-client-cert-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-client-cert-uri
+ :end-before: end-client-cert-uri
+
+To learn more about specifying a client certificate, see :ref:`php-client-cert` in
+the TLS Configuration guide.
+
+Provide a Certificate Key File Password
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to specify the password for your
+client certificate:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-key-file-client
+ :end-before: end-key-file-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-key-file-uri
+ :end-before: end-key-file-uri
+
+.. important::
+
+ When replacing the ```` placeholder in the connection URI, ensure
+ that you :wikipedia:`percent-encode ` the value.
+
+To learn more about providing a key file password, see :ref:`php-key-file-password` in
+the TLS Configuration guide.
+
+Allow Insecure TLS
+~~~~~~~~~~~~~~~~~~
+
+The following code shows how to relax TLS constraints, which has the same
+effect as disabling both :ref:`certificate validation `
+and :ref:`hostname verification `:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-insecure-tls-client
+ :end-before: end-insecure-tls-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-insecure-tls-uri
+ :end-before: end-insecure-tls-uri
+
+To learn more about allowing insecure TLS, see :ref:`php-insecure-tls` in
+the TLS Configuration guide.
+
+.. warning::
+
+ Setting the ``tlsInsecure`` option to ``true`` might expose your application
+ to security risks. Enabling this option makes your application insecure and
+ potentially vulnerable to expired certificates and to foreign processes posing
+ as valid client instances.
+
+.. _php-connect-disable-cert:
+
+Disable Certificate Validation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to disable certificate validation:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-disable-cert-client
+ :end-before: end-disable-cert-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-disable-cert-uri
+ :end-before: end-disable-cert-uri
+
+To learn more about disabling certificate validation, see :ref:`php-insecure-tls` in
+the TLS Configuration guide.
+
+.. _php-connect-disable-hostname:
+
+Disable Hostname Verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows how to disable hostname verification:
+
+.. tabs::
+
+ .. tab:: MongoDB\\Client
+ :tabid: Client
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-disable-hostname-client
+ :end-before: end-disable-hostname-client
+
+ .. tab:: Connection URI
+ :tabid: connectionstring
+
+ .. literalinclude:: /includes/authentication.php
+ :language: php
+ :dedent:
+ :start-after: start-disable-hostname-uri
+ :end-before: end-disable-hostname-uri
+
+To learn more about disabling hostname verification, see :ref:`php-insecure-tls` in
+the TLS Configuration guide.
diff --git a/source/security/authentication.txt b/source/security/authentication.txt
index eb8c9770..a9c3930a 100644
--- a/source/security/authentication.txt
+++ b/source/security/authentication.txt
@@ -17,6 +17,13 @@ Authentication Mechanisms
.. meta::
:keywords: authorize, secure, connect, code example
+.. toctree::
+ :caption: Authentication
+
+ SCRAM
+ X.509
+ AWS IAM
+
Overview
--------
@@ -36,334 +43,30 @@ users.
- `RFC 3986 `__
- :php:`rawurlencode ` in the PHP manual
-.. _php-scram-sha-256:
-
-SCRAM-SHA-256
--------------
-
-SCRAM-SHA-256, as defined by `RFC 7677 `__,
-is the default authentication mechanism on MongoDB deployments.
-
-To authenticate with this mechanism, set the following connection options:
-
-- ``username``: The username to authenticate. Percent-encode this value before including
- it in a connection URI.
-- ``password``: The password to authenticate. Percent-encode this value before including
- it in a connection URI.
-- ``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'``.
-
-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.
-
-.. tabs::
-
- .. tab:: MongoDB\\Client
- :tabid: Client
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-scram-sha-256-client
- :end-before: end-scram-sha-256-client
-
- .. tab:: Connection URI
- :tabid: connectionstring
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-scram-sha-256-uri
- :end-before: end-scram-sha-256-uri
-
-.. _php-mongodb-x509:
-
-MONGODB-X509
-------------
-
-If you enable TLS, during the TLS handshake, the {+php-library+} can present an X.509
-client certificate to MongoDB to prove its identity. The MONGODB-X509 authentication
-mechanism uses this certificate to authenticate the client.
-
-To authenticate with this mechanism, set the following connection options:
-
-- ``tls``: Set to ``true``.
-- ``tlsCertificateKeyFile``: The file path of the ``.pem`` file that contains your
- client certificate and private key.
-- ``authMechanism``: Set to ``'MONGODB-X509'``.
-
-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.
-
-.. tabs::
-
- .. tab:: MongoDB\\Client
- :tabid: Client
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-mongodb-X509-client
- :end-before: end-mongodb-X509-client
-
- .. tab:: Connection URI
- :tabid: connectionstring
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-mongodb-X509-uri
- :end-before: end-mongodb-X509-uri
-
-.. _php-mongodb-aws:
-
-MONGODB-AWS
------------
-
-.. important::
-
- 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
-method to authenticate, you must specify ``'MONGODB-AWS'`` as the value of
-the ``authMechanism`` connection option.
-
-.. note::
-
- The {+php-library+} uses libmongoc's implementation of the MONGODB-AWS
- authentication mechanism. To learn more about using this authentication mechanism
- with libmongoc, see `Authentication via AWS IAM
- `__
- in the C driver documentation.
-
-When you use the MONGODB-AWS mechanism, the driver tries to retrieve AWS
-credentials from the following sources, in the order listed:
-
-1. Options passed to the ``MongoDB\Client`` either as part of the connection
- URI or an options parameter
-#. Environment variables
-#. AWS EKS ``AssumeRoleWithWebIdentity`` request
-#. ECS container metadata
-#. EC2 instance metadata
-
-The following sections describe how to retrieve credentials from
-these sources and use them to authenticate your PHP application.
-
-.. _php-mongodb-aws-credentials:
-
-MongoDB\\Client Credentials
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-First, the driver checks whether you passed AWS credentials to the
-``MongoDB\Client`` constructor, either as as part of the connection
-URI or the ``$uriOptions`` array parameter. To pass your credentials to
-``MongoDB\Client``, set the following connection options:
-
-- ``username``: The AWS IAM access key ID to authenticate. Percent-encode this value
- before including it in a connection URI.
-- ``password``: The AWS IAM secret access key. Percent-encode this value before including
- it in a connection URI.
-- ``authMechanism``: Set to ``'MONGODB-AWS'``.
-
-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.
-
-.. tabs::
-
- .. tab:: MongoDB\\Client
- :tabid: Client
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-mongodb-aws-client
- :end-before: end-mongodb-aws-client
-
- .. tab:: Connection URI
- :tabid: connectionstring
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-mongodb-aws-uri
- :end-before: end-mongodb-aws-uri
-
-.. _php-mongodb-aws-env-vars:
-
-Environment Variables
-~~~~~~~~~~~~~~~~~~~~~
-
-If you don't provide a username and password when you construct your ``MongoDB\Client``
-object, the driver tries to retrieve AWS credentials from the following
-environment variables:
-
-- ``AWS_ACCESS_KEY_ID``
-- ``AWS_SECRET_ACCESS_KEY``
-- ``AWS_SESSION_TOKEN``
-
-To use these environment variables to authenticate your application, first set them to the
-AWS IAM values needed for authentication. You can run the ``export`` command in your shell or
-add the variables to a ``.env`` file, as shown in the following code example:
-
-.. tabs::
-
- .. tab:: Shell Commands
- :tabid: shell
-
- .. code-block:: sh
-
- export AWS_ACCESS_KEY_ID=
- export AWS_SECRET_ACCESS_KEY=
- export AWS_SESSION_TOKEN=
-
- .. tab:: .env File
- :tabid: dotenv
-
- .. code-block:: php
-
- AWS_ACCESS_KEY_ID=
- AWS_SECRET_ACCESS_KEY=
- AWS_SESSION_TOKEN=
-
-.. important::
-
- Don't percent-encode the values in these environment variables.
-
-After you set these environment variables, set the ``authMechanism``
-connection option to ``'MONGODB-AWS'``.
-
-.. _php-mongodb-aws-env-example:
-
-Example
-```````
-
-The following example sets the ``authMechanism`` connection option.
-You can set this option in two ways: by passing an options array to the
-``MongoDB\Client`` constructor or through a parameter in your connection URI.
-
-.. tabs::
-
- .. tab:: MongoDB\\Client
- :tabid: Client
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-mongodb-aws-env-client
- :end-before: end-mongodb-aws-env-client
-
- .. tab:: Connection URI
- :tabid: connectionstring
-
- .. literalinclude:: /includes/authentication.php
- :language: php
- :dedent:
- :start-after: start-mongodb-aws-env-uri
- :end-before: end-mongodb-aws-env-uri
-
-.. tip:: AWS Lambda
-
- AWS Lambda runtimes can automatically set these environment variables during
- initialization. For more information about using environment variables in an AWS Lambda
- environment, see `Using Lambda environment variables
- `__
- in the AWS documentation.
-
-.. _php-mongodb-aws-oidc:
-
-AssumeRoleWithWebIdentity Request
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC)
-identity provider, the driver can make an ``AssumeRoleWithWebIdentity`` request
-to exchange the OIDC token for temporary AWS credentials for your application.
-
-To authenticate with temporary AWS IAM credentials returned by an
-``AssumeRoleWithWebIdentity`` request, ensure that the AWS config file exists in your
-environment and is configured correctly. To learn how to create and configure
-an AWS config file, see `Configuration `__
-in the AWS documentation.
-
-After you configure your environment for an ``AssumeRoleWithWebIdentity`` request,
-set the ``authMechanism`` connection option to ``'MONGODB-AWS'``.
-To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example
-` on this page.
-
-.. tip::
-
- For more information about using an ``AssumeRoleWithWebIdentity`` request to
- authenticate your application, see the following AWS documentation:
-
- - `Authenticating users for your cluster from an OpenID Connect identity provider
- `__
- - `AssumeRoleWithWebIdentity
- `__
-
-.. _php-mongodb-aws-ecs:
-
-ECS Metadata
-~~~~~~~~~~~~
-
-If your application runs in an Elastic Container Service (ECS) container,
-the driver can automatically retrieve temporary AWS credentials from an
-ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called
-``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``. You can set this variable by running
-the ``export`` shell command or adding it to your ``.env`` file, as shown in the following
-example:
-
-.. tabs::
-
- .. tab:: Shell Commands
- :tabid: shell
-
- .. code-block:: sh
-
- export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=
-
- .. tab:: .env File
- :tabid: dotenv
-
- .. code-block:: php
-
- AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=
-
-After you set the environment variable, set the ``authMechanism``
-connection option to ``'MONGODB-AWS'``. To view an example that sets the
-``authMechanism`` option, see the :ref:`authMechanism example
-` on this page.
-
-.. _php-mongodb-aws-ec2:
-
-EC2 Instance Metadata
-~~~~~~~~~~~~~~~~~~~~~
-
-The driver can automatically retrieve temporary AWS credentials from an
-Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from
-within an EC2 instance, set the ``authMechanism`` connection option to ``'MONGODB-AWS'``.
-To view an example that sets the ``authMechanism`` option, see the :ref:`authMechanism example
-` on this page.
-
-.. note::
-
- The {+php-library+} retrieves credentials from an EC2 instance only if the
- environment variables described in the :ref:`php-mongodb-aws-env-vars` section
- are not set.
-
-Additional Information
-----------------------
-
-To learn more about creating a ``MongoDB\Client`` object in the {+php-library+},
-see the :ref:`php-client` guide.
-
-API Documentation
-~~~~~~~~~~~~~~~~~
-
-To learn more about the ``MongoDB\Client`` class, see :phpclass:`MongoDB\Client`
-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