Merge remote-tracking branch 'upstream/php-standardization' into DOCSP-41989-secure-landing

Author: norareidy

snooty.toml

@@ -22,9 +22,11 @@ toc_landing_pages = [
     "/reference/class/MongoDBModelDatabaseInfo",
     "/reference/class/MongoDBModelIndexInfo",
     "/get-started",
+    "/databases-collections",
     "/write",
     "/indexes",
     "/security"
+    "/data-formats"
 ]
 
 sharedinclude_root =  "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -34,7 +36,7 @@ php-library = "MongoDB PHP Library"
 
 [constants]
 php-library = "MongoDB PHP Library"
-driver-short = "PHP library"
+library-short = "PHP library"
 stable-api = "Stable API"
 mdb-server = "MongoDB Server"
 api = "https://www.mongodb.com/docs/php-library/current/reference"

source/compatibility.txt

@@ -44,8 +44,6 @@ The first column lists the version of the library and extension.
 
 .. include:: /includes/language-compatibility-table-php.rst
 
-.. sharedinclude:: dbx/about-driver-compatibility.rst
-
 For more information on how to read the compatibility tables, see our guide on
 :ref:`MongoDB Compatibility Tables <about-driver-compatibility>`.
 

source/connect/client.txt

@@ -22,13 +22,13 @@ Overview
 
 To connect to a MongoDB deployment, you must create the following items:
 
-- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+}
+- **Connection URI**, also known as a *connection string*, which tells the {+library-short+}
   which MongoDB deployment to connect to.
 - **MongoDB\\Client** object, which creates the connection to the MongoDB deployment
   and lets you perform operations on it.
 
 You can also set options within either or both of these components to
-customize the way that the {+driver-short+} behaves
+customize the way that the {+library-short+} behaves
 while connected to MongoDB.
 
 This guide describes the components of a connection string and shows how to
@@ -99,7 +99,7 @@ deployment on port ``27017`` of ``localhost``:
 API Documentation
 -----------------
 
-To learn more about creating a ``MongoDB\Client`` object in the {+driver-short+},
+To learn more about creating a ``MongoDB\Client`` object in the {+library-short+},
 see the following API documentation:
 
 - :ref:`MongoDB\Client <php-api-mongodbclient>`

source/connect/connection-targets.txt

@@ -42,7 +42,7 @@ breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
 To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page
 <php-stable-api>`.
 
-The following code shows how to use the {+driver-short+} to connect to an Atlas cluster.
+The following code shows how to use the {+library-short+} to connect to an Atlas cluster.
 The code also uses the ``serverApi`` option to specify a {+stable-api+} version.
 
 .. literalinclude:: /includes/connect/atlas.php
@@ -63,7 +63,7 @@ To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
 default, the ``mongod`` process runs on port 27017, though you can customize this for
 your deployment.
 
-The following code shows how to use the {+driver-short+} to connect to a local MongoDB
+The following code shows how to use the {+library-short+} to connect to a local MongoDB
 deployment:
 
 .. literalinclude:: /includes/connect/client.php
@@ -79,7 +79,7 @@ To connect to a replica set, specify the hostnames (or IP addresses) and
 port numbers of the replica set members in your connection string.
 
 If you aren't able to provide a full list of hosts in the replica set, you can 
-specify one or more of the hosts in the replica set and instruct the {+driver-short+} to 
+specify one or more of the hosts in the replica set and instruct the {+library-short+} to 
 perform automatic discovery to find the others. To instruct the driver to perform
 automatic discovery, choose one of the following actions:
 

source/connect/tls.txt

@@ -23,7 +23,7 @@ Overview
 In this guide, you can learn how to use the :wikipedia:`TLS <Transport_Layer_Security>`
 protocol to secure your connection to a MongoDB deployment.
 
-When you enable TLS for a connection, the {+driver-short+} performs the following actions:
+When you enable TLS for a connection, the {+library-short+} performs the following actions:
 
 - Uses TLS to connect to the MongoDB deployment
 - Verifies the deployment's certificate
@@ -41,7 +41,7 @@ To learn how to configure your MongoDB deployment for TLS, see the
 
 .. tip::
 
-   The {+driver-short+} delegates most TLS behavior to the MongoDB C Driver.
+   The {+library-short+} delegates most TLS behavior to the MongoDB C Driver.
    For information about how the C driver handles TLS, including configuration steps
    and expected behavior, see
    `Configuring TLS <https://www.mongodb.com/docs/languages/c/c-driver/current/libmongoc/guides/configuring_tls/#supported-libraries>`__
@@ -78,7 +78,7 @@ signed by a well-known CA (certificate authority), and your application relies o
 to validate the certificate.
 
 During testing, however, you might want to act as your own CA.
-In this case, you must instruct the {+driver-short+} to
+In this case, you must instruct the {+library-short+} to
 use your CA certificates instead of ones signed by another CA.
 
 To do so, use the ``tlsCAFile`` connection option to specify the path to a ``.pem`` file
@@ -95,7 +95,7 @@ Specify a CA Directory
 
 If you are using OpenSSL or LibreSSL (``libtls``) for TLS support, you can also use
 the ``ca_dir`` option to instruct
-the {+driver-short+} to search for a CA file within a directory. The driver searches this
+the {+library-short+} to search for a CA file within a directory. The driver searches this
 directory if it doesn't find a CA file at the path specified in the ``tlsCAFile`` option.
 
 The following code example shows how to use the ``driverOptions`` parameter to specify the
@@ -119,7 +119,7 @@ Check Certificate Revocation
 ----------------------------
 
 When an X.509 certificate is no longer trustworthy—for example, if its private key
-has been compromised—the CA revokes the certificate. The {+driver-short+} includes two ways
+has been compromised—the CA revokes the certificate. The {+library-short+} includes two ways
 to check whether a server's certificate has been revoked.
 
 .. _php-disable-ocsp:
@@ -131,15 +131,15 @@ The Online Certificate Status Protocol (OCSP) process varies depending on the ve
 {+mdb-server+} you're connecting to:
 
 - **MongoDB v4.4 or later:** The server staples a
-  time-stamped OCSP response to its certificate. The {+driver-short+} validates the certificate
+  time-stamped OCSP response to its certificate. The {+library-short+} validates the certificate
   against the OCSP response. If the CA has revoked the certificate, or if the OCSP response
   is otherwise invalid, the TLS handshake fails.
-- **MongoDB v4.3 or earlier:** The server supplies an OCSP endpoint, which the {+driver-short+}
-  contacts directly. The {+driver-short+} then validates the certificate against the OCSP
+- **MongoDB v4.3 or earlier:** The server supplies an OCSP endpoint, which the {+library-short+}
+  contacts directly. The {+library-short+} then validates the certificate against the OCSP
   response. If the CA hasn't revoked the certificate, the TLS handshake continues, even if
   the OCSP response is invalid or malformed.
 
-To stop the {+driver-short+} from contacting the OCSP endpoint, set the
+To stop the {+library-short+} from contacting the OCSP endpoint, set the
 ``tlsDisableOCSPEndpointCheck`` connection option to ``true``.
 You can do this in two ways: by passing an argument to the
 ``MongoDB\Client`` constructor or through a parameter in your connection string.
@@ -148,15 +148,15 @@ You can do this in two ways: by passing an argument to the
 
 .. note::
 
-   Even if the ``tlsDisableOCSPEndpointCheck`` option is set to ``true``, the {+driver-short+}
+   Even if the ``tlsDisableOCSPEndpointCheck`` option is set to ``true``, the {+library-short+}
    still verifies any OCSP response stapled to a server's certificate.
 
 .. _php-crl:
 
 Certificate Revocation List
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Instead of using OCSP, you can use the instruct the {+driver-short+}
+Instead of using OCSP, you can use the instruct the {+library-short+}
 to check the server's certificate
 against a Certificate Revocation List (CRL) published by the CA. To do so, set the
 ``crl_file`` option to the file path of the CRL. Include this option in the
@@ -177,7 +177,7 @@ Present a Client Certificate
 ----------------------------
 
 Some MongoDB deployments require every connecting application to present a client certificate
-that proves its identity. To specify the client certificate for the {+driver-short+} to
+that proves its identity. To specify the client certificate for the {+library-short+} to
 present, set the ``tleCertificateKeyFile`` option to the file path of the ``.pem`` file that
 contains your certificate and private key.
 
@@ -214,7 +214,7 @@ of the ``MongoDB\Client`` constructor or through a parameter in your connection
 Allow Insecure TLS
 ------------------
 
-When TLS is enabled, the {+driver-short+} automatically verifies the certificate that
+When TLS is enabled, the {+library-short+} automatically verifies the certificate that
 the server presents. When testing your code, you can disable this verification.
 This is known as *insecure TLS.*
 
@@ -262,7 +262,7 @@ To disable only hostname verification, set the ``tlsAllowInvalidHostnames`` opti
 API Documentation
 -----------------
 
-To learn more about configuring TLS for the {+driver-short+},
+To learn more about configuring TLS for the {+library-short+},
 see the following API documentation:
 
-- :ref:`MongoDB\Client <php-mongodb-client>`
+- :phpclass:`MongoDB\Client`

source/data-formats.txt

@@ -0,0 +1,40 @@
+.. _php-data-formats:
+
+========================
+Specialized Data Formats
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: store, bson, codec
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /data-formats/custom-types
+   /data-formats/codecs
+   /data-formats/decimal128
+   /data-formats/modeling-bson-data
+
+
+Overview
+--------
+
+You can use several types of specialized data formats in your {+library-short+}
+application. To learn how to work with these data formats, see the following
+guides:
+
+- :ref:`php-custom-types`
+- :ref:`php-codecs`
+- :ref:`php-decimal128`
+- :ref:`php-bson`

source/tutorial/codecs.txt renamed to source/data-formats/codecs.txt

@@ -1,3 +1,5 @@
+.. _php-custom-types:
+
 =================
 Custom Data-Types
 =================

source/tutorial/custom-types.txt renamed to source/data-formats/custom-types.txt

@@ -1,3 +1,5 @@
+.. _php-decimal128:
+
 ==========
 Decimal128
 ==========

source/tutorial/decimal128.txt renamed to source/data-formats/decimal128.txt

@@ -1,3 +1,5 @@
+.. _php-bson:
+
 ==================
 Modeling BSON Data
 ==================

source/tutorial/modeling-bson-data.txt renamed to source/data-formats/modeling-bson-data.txt

@@ -193,10 +193,8 @@ The following example deletes the ``test_collection`` collection:
 Configure Read and Write Operations
 -----------------------------------
 
-You can control how the library routes read operations by setting a **read preference**.
-You can also control options for how the library waits for acknowledgment of
-read and write operations on a replica set by setting a **read concern** and a
-**write concern**.
+You can control how read and write operations run on replica sets
+by specifying a read preference, read concern, or write concern.
 
 By default, databases inherit read and write settings from the ``MongoDB\Client``
 instance. Collections inherit these settings from the ``MongoDB\Client`` or
@@ -205,114 +203,8 @@ You can change these settings by passing an options array to the
 ``MongoDB\Client::selectDatabase()``, ``MongoDB\Client::selectCollection()``, or
 ``MongoDB\Database::selectCollection()`` methods.
 
-To change the read preference, read concern, and write concern of your database
-or collection, set the following options in the array parameter:
-
-- ``readPreference``: Sets the read preference. For a list of available read
-  preferences, see :php:`MongoDB\Driver\ReadPreference <mongodb-driver-readpreference>`
-  in the extension API documentation.
-- ``readConcern``: Sets the read concern. For a list of available read
-  concerns, see :php:`MongoDB\Driver\ReadConcern <mongodb-driver-readconcern>`
-  in the extension API documentation.
-- ``writeConcern``: Sets the write concern. For a list of available write
-  concerns, see :php:`MongoDB\Driver\WriteConcern <mongodb-driver-writeconcern>`
-  in the extension API documentation.
-
-.. tip::
-
-   To learn more about read preferences and read and write concerns, see the
-   following guides in the MongoDB Server manual:
-
-   - :manual:`Read Preference </core/read-preference/>`
-   - :manual:`Read Concern </reference/read-concern/>`
-   - :manual:`Write Concern </reference/write-concern/>`
-
-Database Configuration Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following example shows how to set the read preference, read concern, and
-write concern of a database called ``test_database`` by passing an options
-array to ``selectDatabase()``:
-
-.. literalinclude:: /includes/databases-collections/databases-collections.php
-    :language: php
-    :dedent:
-    :start-after: start-database-settings
-    :end-before: end-database-settings
-
-Collection Configuration Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following example shows how to set the read preference, read concern, and
-write concern of a collection called ``test_collection`` by passing an options
-array to ``selectCollection()``:
-
-.. literalinclude:: /includes/databases-collections/databases-collections.php
-    :language: php
-    :dedent:
-    :start-after: start-collection-settings
-    :end-before: end-collection-settings
-
-Advanced Read Configurations 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Tag Sets
-````````
-
-In {+mdb-server+}, you can apply key-value :manual:`tags
-</core/read-preference-tags/>` to replica-set
-members according to any criteria you choose. You can then use
-those tags to target one or more members for a read operation.
-
-By default, the {+php-library+} ignores tags when choosing a member
-to read from. To instruct the {+php-library+} to prefer certain tags,
-pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class
-constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as
-the value of the ``readPreference`` database option.
-
-This code example sets the ``readPreference`` option to a tag set
-that instructs ``test_database`` to prefer reads from secondary replica set
-members in the following order:
-
-1. Members from the New York data center (``['dc' => 'ny']``)
-#. Members from the San Francisco data center (``['dc' => 'sf']``)
-#. Any secondary members (``[]``)
-
-.. literalinclude:: /includes/databases-collections/databases-collections.php
-    :language: php
-    :dedent:
-    :start-after: start-tag-set
-    :end-before: end-tag-set
-
-Local Threshold
-```````````````
-
-If multiple replica-set members match the read preference and tag sets you specify,
-the {+php-library+} reads from the nearest replica-set members, chosen according to
-their ping time.
-
-By default, the library uses only members whose ping times are within 15 milliseconds
-of the nearest member for queries. To distribute reads between members with
-higher latencies, pass an options array to the ``MongoDB\Client`` constructor that
-sets the ``localThresholdMS`` option.
-
-The following example specifies a local threshold of 35 milliseconds:
-
-.. literalinclude:: /includes/databases-collections/databases-collections.php
-    :language: php
-    :dedent:
-    :start-after: start-local-threshold
-    :end-before: end-local-threshold
-
-In the preceding example, the {+php-library+} distributes reads among matching members
-within 35 milliseconds of the closest member's ping time.
-
-.. note::
-  
-   The {+php-library+} ignores the value of ``localThresholdMS`` when communicating with a
-   replica set through a ``mongos`` instance. In this case, use the
-   :manual:`localThreshold </reference/program/mongos/#std-option-mongos.--localThreshold>`
-   command-line option.
+To learn more about setting a read preference, read concern, and write concern,
+see the :ref:`php-read-write-pref` guide.
 
 API Documentation
 -----------------

source/databases-collections.txt

@@ -1,3 +1,5 @@
+.. _php-faq:
+
 ==========================
 Frequently Asked Questions
 ==========================