edits

Author: norareidy

config/redirects

@@ -92,4 +92,5 @@ raw: ${prefix}/stable -> ${base}/current/
 [*-master]: ${prefix}/${version}/aggregation/vector-search/ -> ${base}/${version}/vector-search/
 [*-master]: ${prefix}/${version}/monitoring/ -> ${base}/${version}/monitoring-logging/
 [*-master]: ${prefix}/${version}/read/ -> ${base}/${version}/crud/
-[*-master]: ${prefix}/${version}/write/ -> ${base}/${version}/crud/
+[*-master]: ${prefix}/${version}/write/ -> ${base}/${version}/crud/
+[*-master]: ${prefix}/${version}/faq/ -> ${base}/${version}/

source/connect/client.txt

@@ -124,13 +124,12 @@ Troubleshooting
 This section addresses issues that you might encounter when using a
 MongoDB client.
 
-Client Persistence Errors
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Client Persistence Considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Connections to the MongoDB deployment are handled by the ``libmongoc``
-library and the :php:`{+extension-short+} <mongodb>`. When you construct
-a :phpclass:`MongoDB\Client` instance, the {+library-short+} creates a
-:php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>` instance by using the
+The ``libmongoc`` library and the {+extension-short+} handle connections
+to a MongoDB deployment. When you construct a :phpclass:`MongoDB\Client` instance, the
+{+library-short+} creates a :php:`MongoDB\Driver\Manager <class.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
@@ -151,7 +150,7 @@ 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 cause errors in the following situations:
 
-- PHP-FPM is configured with ``pm.max_requests=0``, so that workers never respawn, and a
+- PHP-FPM is configured with ``pm.max_requests=0`` so 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.

source/connect/connection-options.txt

@@ -321,93 +321,6 @@ Miscellaneous Configuration
        | **MongoDB\\Client Example**: ``$uriOptions = ['srvMaxHosts' => 5];``
        | **Connection URI Example**: ``srvMaxHosts=5``
 
-Troubleshooting
----------------
-
-This section addresses issues related to MongoDB connection options.
-
-Server Selection Errors
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The following code shows possible server selection error
-messages that your application might generate: 
-
-.. code-block:: none
-   :copyable: false
-
-   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']
-
-The {+extension-short+} usually represents these errors as
-:php:`MongoDB\Driver\Exception\ConnectionTimeoutException <mongodb-driver-exception-connectiontimeoutexception>`
-exceptions. However, the exception messages originate from
-``libmongoc``, which is the underlying system library used by the extension. Since
-these messages can take many forms, we recommend breaking down the structure of
-the message so you can better diagnose errors in your application.
-
-Messages typically start with "No suitable servers found". The next part of
-the message indicates *how* server selection failed. The extension
-avoids a server selection loop and makes a single attempt by default, according to
-the ``serverSelectionTryOnce`` connection string option. If the extension is
-configured to use a loop, a message that includes the phrase "serverSelectionTimeoutMS expired"
-indicates that you 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
-previously experienced an error during monitoring will be included in this list. These
-messages typically originate from low-level socket or TLS functions.
-
-The following list describes the possible meanings of common phrases in the last error message
-component: 
-
-- "Connection refused": The remote host might not be not listening on
-  the expected port.
-- "Connection timeout": There might be a routing problem, a firewall error, or
-  a timeout due to latency.
-- "Socket timeout": You likely established an initial connection that
-  was dropped or timed out due to latency.
-- "TLS handshake failed": TLS or OCSP verification did not succeed, and you might
-  have misconfigured TLS certificates.
-
-In the case of a connection failure, you can use the ``connect`` tool for
-more troubleshooting information. This tool tries to connect to each host in a
-connection string by using socket functions, and then attempts to interact with
-data. If you used Composer to install the library, you can use the following command
-to use the ``connect`` tool:
-
-.. code-block:: none
-
-   php vendor/mongodb/mongodb/tools/connect.php <connection URI>
-
-If the server you are connecting to does not accept connections, the output
-resembles the following code:
-
-.. code-block:: none
-
-   Looking up MongoDB at <connection URI>
-   Found 1 host(s) in the URI. Will attempt to connect to each.
-
-   Could not connect to <host>:<port>: Connection refused
-
-.. note::
-
-   The tool supports only the ``mongodb://`` URI schema. Using the
-   ``mongodb+srv`` scheme is not supported.
-
 API Documentation
 -----------------
 

source/connect/connection-targets.txt

@@ -124,6 +124,94 @@ DNS Service Discovery
 
          $uri = 'mongodb+srv://<hostname>/';
 
+Troubleshooting
+---------------
+
+This section addresses issues that you might encounter when
+connecting to a MongoDB deployment.
+
+Server Selection Errors
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The following code shows possible server selection error
+messages that your application might generate: 
+
+.. code-block:: none
+   :copyable: false
+
+   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']
+
+The {+extension-short+} usually represents these errors as
+:php:`MongoDB\Driver\Exception\ConnectionTimeoutException <mongodb-driver-exception-connectiontimeoutexception>`
+exceptions. However, the exception messages originate from
+``libmongoc``, which is the underlying system library used by the extension. Since
+these messages can take many forms, we recommend breaking down the structure of
+the message so you can better diagnose errors in your application.
+
+Messages typically start with "No suitable servers found". The next part of
+the message indicates *how* server selection failed. The extension
+avoids a server selection loop and makes a single attempt by default, according to
+the ``serverSelectionTryOnce`` connection string option. If the extension is
+configured to use a loop, a message that includes the phrase "serverSelectionTimeoutMS expired"
+indicates that you 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
+previously experienced an error during monitoring will be included in this list. These
+messages typically originate from low-level socket or TLS functions.
+
+The following list describes the possible meanings of common phrases in the last error message
+component: 
+
+- "Connection refused": The remote host might not be not listening on
+  the expected port.
+- "Connection timeout": There might be a routing problem, a firewall error, or
+  a timeout due to latency.
+- "Socket timeout": You likely established an initial connection that
+  was dropped or timed out due to latency.
+- "TLS handshake failed": TLS or OCSP verification did not succeed, and you might
+  be using misconfigured TLS certificates.
+
+In the case of a connection failure, you can use the ``connect`` tool for
+more troubleshooting information. This tool tries to connect to each host in a
+connection string by using socket functions, and then attempts to interact with
+data. If you used Composer to install the library, you can use the following command
+to start the ``connect`` tool:
+
+.. code-block:: none
+
+   php vendor/mongodb/mongodb/tools/connect.php <connection URI>
+
+If the server you are connecting to does not accept connections, the output
+resembles the following code:
+
+.. code-block:: none
+
+   Looking up MongoDB at <connection URI>
+   Found 1 host(s) in the URI. Will attempt to connect to each.
+
+   Could not connect to <host>:<port>: Connection refused
+
+.. note::
+
+   The tool supports only the ``mongodb://`` URI schema. Using the
+   ``mongodb+srv`` scheme is not supported.
+
 API Documentation
 -----------------
 

source/get-started.txt

@@ -355,8 +355,8 @@ This section addresses issues that you might encounter when installing the
 PHP Headers Not Found
 ~~~~~~~~~~~~~~~~~~~~~
 
-You might see a PHP header file error that resembles the following code when installing
-the {+library-short+}
+You might see a header file error that resembles the following code when installing
+the {+library-short+}:
 
 .. code-block:: none
    :copyable: false
@@ -376,7 +376,7 @@ If you install a PHP runtime, the corresponding headers are not always automatic
 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 need to install PHP and its headers by using
-`Homebrew <https://brew.sh/>`__ to build an extension.
+`Homebrew <https://brew.sh/>`__.
 
 Multiple PHP Runtimes Installed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -389,15 +389,15 @@ ensure that you use the correct ``pecl`` or ``pie`` command and modify the appro
 file.
 
 To see which ``php.ini`` file a PHP runtime uses,
-examine the output of :php:`phpinfo() <phpinfo>` for that particular
+view the output of :php:`phpinfo() <phpinfo>` for that particular
 SAPI. Additionally, you can use :php:`php_ini_loaded_file() <php_ini_loaded_file>` and
 :php:`php_ini_scanned_files() <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 accessible to your web server.
-The tool will point out potential issues and installation instructions for your
+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:
 
@@ -438,4 +438,4 @@ inferred from :php:`phpinfo() <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
-appropriate DLL for your PHP environment.
+correct DLL for your PHP environment.