DOP-4904: Inline docs for v1.16

source/faq.txt

@@ -0,0 +1,182 @@
+==========================
+Frequently Asked Questions
+==========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Common Extension Installation Errors
+------------------------------------
+
+PHP Headers Not Found
+~~~~~~~~~~~~~~~~~~~~~
+
+For example:
+
+.. code-block:: none
+
+   /private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
+
+   #include <php.h>
+            ^~~~~~~
+
+This error indicates that PHP's build system cannot find the necessary headers.
+All PHP extensions require headers in order to compile. Additionally, those
+headers must correspond to the PHP runtime for which the extension will be used.
+Generally, the ``phpize`` command (invoked by ``pecl``) will ensure that the
+extension builds with the correct headers.
+
+Note that the mere presence of a PHP runtime does not mean that headers are
+available. On various 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 and users typically need to install PHP (and headers)
+via `Homebrew <https://brew.sh/>`_ in order to build an extension.
+
+Multiple PHP Runtimes Installed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your system has multiple versions of PHP installed, each version will have
+its own ``pecl`` and ``phpize`` commands. Additionally, each PHP runtime may
+have separate ``php.ini`` files for each SAPI (e.g. FPM, CLI). If the extension
+has been installed but is not available at runtime, double-check that you have
+used the correct ``pecl`` command and have modified the appropriate ``php.ini``
+file(s).
+
+If there is any doubt about the ``php.ini`` file being used by a PHP runtime,
+you should examine the output of :php:`phpinfo() <phpinfo>` for that particular
+SAPI. Additionally, :php:`php_ini_loaded_file() <php_ini_loaded_file>` and
+:php:`php_ini_scanned_files() <php_ini_scanned_files>` 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 ``<pre>`` tags to properly format its output:
+
+.. code-block:: php
+
+   <pre><?php require(...); ?></pre>
+
+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() <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.
+
+Server Selection Failures
+-------------------------
+
+The following are all examples of
+:doc:`Server Selection </tutorial/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 <mongodb-driver-exception-connectiontimeoutexception>`
+exception from the driver. The actual exception messages originate from
+libmongoc, which is the underlying library used by the PHP driver. Since these
+messages can take many forms, it's helpful to break down the structure of the
+message so you can better diagnose errors in your application.
+
+Messages will typically start with "No suitable servers found". The next part of
+the message indicates *how* server selection failed. By default, the PHP driver
+avoids a server selection loop and instead makes a single attempt (according to
+the ``serverSelectionTryOnce`` connection string option). If the driver 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.

source/includes/extracts-bucket-option.yaml

@@ -0,0 +1,28 @@
+ref: bucket-option-readConcern
+source:
+  ref: common-option-readConcern
+  file: extracts-common-option.yaml
+replacement:
+  object: bucket
+---
+ref: bucket-option-readPreference
+source:
+  ref: common-option-readPreference
+  file: extracts-common-option.yaml
+replacement:
+  object: bucket
+---
+ref: bucket-option-typeMap
+source:
+  ref: common-option-typeMap
+  file: extracts-common-option.yaml
+replacement:
+  object: bucket
+---
+ref: bucket-option-writeConcern
+source:
+  ref: common-option-writeConcern
+  file: extracts-common-option.yaml
+replacement:
+  object: bucket
+...

source/includes/extracts-bulkwriteexception.yaml

@@ -0,0 +1,21 @@
+ref: bulkwriteexception-result
+content: |
+  If a :php:`MongoDB\Driver\Exception\BulkWriteException
+  <mongodb-driver-exception-bulkwriteexception>` is thrown, users should call
+  :php:`getWriteResult() <mongodb-driver-writeexception.getwriteresult>` and
+  inspect the returned :php:`MongoDB\Driver\WriteResult
+  <mongodb-driver-writeresult>` object to determine the nature of the error.
+
+  For example, a write operation may have been successfully applied to the
+  primary server but failed to satisfy the write concern (e.g. replication took
+  too long). Alternatively, a write operation may have failed outright (e.g.
+  unique key violation).
+---
+ref: bulkwriteexception-ordered
+content: |
+  In the case of a bulk write, the result may indicate multiple successful write
+  operations and/or errors. If the ``ordered`` option is ``true``, some
+  operations may have succeeded before the first error was encountered and the
+  exception thrown. If the ``ordered`` option is ``false``, multiple errors may
+  have been encountered.
+...

source/includes/extracts-client-option.yaml

@@ -0,0 +1,28 @@
+ref: client-option-readConcern
+source:
+  ref: common-option-readConcern
+  file: extracts-common-option.yaml
+replacement:
+  object: client
+---
+ref: client-option-readPreference
+source:
+  ref: common-option-readPreference
+  file: extracts-common-option.yaml
+replacement:
+  object: client
+---
+ref: client-option-typeMap
+source:
+  ref: common-option-typeMap
+  file: extracts-common-option.yaml
+replacement:
+  object: client
+---
+ref: client-option-writeConcern
+source:
+  ref: common-option-writeConcern
+  file: extracts-common-option.yaml
+replacement:
+  object: client
+...

source/includes/extracts-collection-option.yaml

@@ -0,0 +1,41 @@
+ref: collection-option-collation
+content: |
+  :manual:`Collation </reference/collation>` allows users to specify
+  language-specific rules for string comparison, such as rules for lettercase
+  and accent marks. When specifying collation, the ``locale`` field is
+  mandatory; all other collation fields are optional. For descriptions of the
+  fields, see :manual:`Collation Document </reference/collation/#collation-document>`.
+
+  If the collation is unspecified but the collection has a default collation,
+  the operation uses the collation specified for the collection. If no
+  collation is specified for the collection or for the operation, MongoDB uses
+  the simple binary comparison used in prior versions for string comparisons.
+---
+ref: collection-option-readConcern
+source:
+  ref: common-option-readConcern
+  file: extracts-common-option.yaml
+replacement:
+  object: collection
+---
+ref: collection-option-readPreference
+source:
+  ref: common-option-readPreference
+  file: extracts-common-option.yaml
+replacement:
+  object: collection
+---
+ref: collection-option-typeMap
+source:
+  ref: common-option-typeMap
+  file: extracts-common-option.yaml
+replacement:
+  object: collection
+---
+ref: collection-option-writeConcern
+source:
+  ref: common-option-writeConcern
+  file: extracts-common-option.yaml
+replacement:
+  object: collection
+...

source/includes/extracts-common-option.yaml

@@ -0,0 +1,86 @@
+ref: common-option-collation
+content: |
+  :manual:`Collation </reference/collation>` allows users to specify
+  language-specific rules for string comparison, such as rules for lettercase
+  and accent marks. When specifying collation, the ``locale`` field is
+  mandatory; all other collation fields are optional. For descriptions of the
+  fields, see :manual:`Collation Document </reference/collation/#collation-document>`.
+---
+ref: common-option-comment
+content: |
+  Enables users to specify an arbitrary comment to help trace the operation
+  through the :manual:`database profiler </reference/database-profiler>`,
+  :manual:`currentOp </reference/command/currentOp>` output, and
+  :manual:`logs </reference/log-messages>`.
+---
+ref: common-option-comment-string-before-4.4
+content: |
+  The comment can be any valid BSON type since MongoDB 4.4. Earlier server
+  versions only support string values.
+---
+ref: common-option-hint
+content: |
+  The index to use. Specify either the index name as a string or the index key
+  pattern as a document. If specified, then the query system will only consider
+  plans using the hinted index.
+---
+ref: common-option-let
+content: |
+  Map of parameter names and values. Values must be constant or closed
+  expressions that do not reference document fields. Parameters can then be
+  accessed as variables in an aggregate expression context (e.g. ``$$var``).
+
+  This is not supported for server versions prior to 5.0 and will result in an
+  exception at execution time if used.
+---
+ref: common-option-maxTimeMS
+content: |
+  The cumulative time limit in milliseconds for processing operations on the
+  cursor. MongoDB aborts the operation at the earliest following
+  :term:`interrupt point`.
+---
+ref: common-option-readConcern
+content: |
+  :manual:`Read concern </reference/read-concern>` to use for the operation.
+  Defaults to the {{object}}'s read concern.
+replacement:
+  object: object
+---
+ref: common-option-readConcern-transaction
+content: |
+  It is not possible to specify a read concern for individual operations as part
+  of a transaction. Instead, set the ``readConcern`` option when
+  :php:`starting the transaction <mongodb-driver-session.starttransaction>`.
+---
+ref: common-option-readPreference
+content: |
+  :manual:`Read preference </reference/read-preference>` to use for the
+  operation. Defaults to the {{object}}'s read preference.
+replacement:
+  object: object
+---
+ref: common-option-session
+content: |
+  Client session to associate with the operation.
+---
+ref: common-option-typeMap
+content: |
+  The :php:`type map <manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
+  to apply to cursors, which determines how BSON documents are converted to PHP
+  values. Defaults to the {{object}}'s type map.
+replacement:
+  object: object
+---
+ref: common-option-writeConcern
+content: |
+  :manual:`Write concern </reference/write-concern>` to use for the operation.
+  Defaults to the {{object}}'s write concern.
+replacement:
+  object: object
+---
+ref: common-option-writeConcern-transaction
+content: |
+  It is not possible to specify a write concern for individual operations as
+  part of a transaction. Instead, set the ``writeConcern`` option when
+  :php:`starting the transaction <mongodb-driver-session.starttransaction>`.
+...