Merge remote-tracking branch 'upstream/comp-cov' into DOCSP-47063-logging

Author: norareidy

config/redirects

@@ -25,7 +25,7 @@ raw: ${prefix}/stable -> ${base}/current/
 # redirects in standardized docs
 [v1.20-*]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/${version}/get-started/
 [v1.20-*]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/${version}/connect/
-[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/monitoring/cluster-monitoring/
+[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/monitoring-logging/monitoring/
 [v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/
 [v1.20-*]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/${version}/data-formats/codecs/
 [v1.20-*]: ${prefix}/${version}/tutorial/collation/ -> ${base}/${version}/
@@ -45,7 +45,7 @@ raw: ${prefix}/stable -> ${base}/current/
 # note: this mapping does not account for all of the new pages
 [*-v1.19]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/v1.x/get-started/
 [*-v1.19]: ${prefix}/${version}/tutorial/connecting/ -> ${base}/v1.x/connect/
-[*-v1.19]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/v1.x/monitoring/cluster-monitoring/
+[*-v1.19]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/v1.x/monitoring-logging/monitoring/
 [*-v1.19]: ${prefix}/${version}/tutorial/crud/ -> ${base}/v1.x/read/
 [*-v1.19]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/v1.x/data-formats/codecs/
 [*-v1.19]: ${prefix}/${version}/tutorial/collation/ -> ${base}/v1.x/
@@ -84,7 +84,7 @@ raw: ${prefix}/stable -> ${base}/current/
 [*-master]: ${prefix}/${version}/data-formats/codecs/ -> ${base}/${version}/data-formats/custom-types/codecs/
 [*-master]: ${prefix}/${version}/databases-collections/time-series/ -> ${base}/${version}/data-formats/time-series/
 [*-master]: ${prefix}/${version}/read/change-streams/ -> ${base}/${version}/monitoring-logging/change-streams/
-[*-master]: ${prefix}/${version}/monitoring/cluster-monitoring/ -> ${base}/${version}/monitoring-logging/cluster-monitoring/
+[*-master]: ${prefix}/${version}/monitoring/cluster-monitoring/ -> ${base}/${version}/monitoring-logging/monitoring/
 [*-master]: ${prefix}/${version}/compatibility/ -> ${base}/${version}/references/compatibility/
 [*-master]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/references/release-notes/
 [*-master]: ${prefix}/${version}/upgrade/ -> ${base}/${version}/references/upgrade/

snooty.toml

@@ -28,6 +28,7 @@ toc_landing_pages = [
     "/indexes",
     "/security",
     "/upgrade",
+    "/security/authentication",
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/connect/connection-options.txt

@@ -248,6 +248,8 @@ Authentication Options
 To learn about the authentication options available in the {+driver-short+}, see
 :ref:`Authentication Mechanisms. <php-auth>`
 
+.. _php-selection-discovery-options:
+
 Server Selection and Discovery Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/crud/read-write-pref.txt

@@ -208,7 +208,7 @@ This section shows how to further customize your read operation
 settings in the following ways:
 
 - :ref:`Apply a tag set <php-tag-sets>`
-- :ref:`Specify a local threshold <php-local-threshold>`
+- :ref:`Configure load balancing behavior <php-load-balancing>`
 
 .. _php-tag-sets:
 
@@ -241,19 +241,51 @@ to prefer reads from secondary replica set members in the following order:
    :start-after: start-tag-set
    :end-before: end-tag-set
 
+.. _php-load-balancing:
+
+Load Balancing
+~~~~~~~~~~~~~~
+
+When connecting to a sharded cluster or a replica set, the {+library-short+} uses
+**load balancing** to handle read and write requests. Load balancing allows the library to
+distribute these requests across multiple servers to avoid overwhelming
+any one server and ensure optimal performance.
+
+When connecting to a sharded cluster, the {+library-short+} determines the closest ``mongos``
+instance by calculating which one has the lowest network round-trip time. Then, the library
+determines the latency window by adding this ``mongos``'s average round-trip time to the
+:ref:`localThresholdMS value <php-local-threshold>`. The library load balances requests
+across up to two random ``mongos`` instances that fall within the latency window. For each request,
+the library chooses the server with the lower operation load by determining its ``operationCount``
+value.
+
+When connecting to a replica set, the {+library-short+} first selects replica set members
+according to your read preference. Then, the library follows the same process as 
+described in the preceding paragraph. After calculating the latency window, the library
+selects up to two random replica set members that fall within the window and chooses
+the member with the lower ``operationCount`` value to receive the request.
+
+.. tip::
+
+   To learn more about load balancing, see :manual:`Sharded Cluster Balancer
+   </core/sharding-balancer-administration/>` in the {+mdb-server+} manual.
+
+   To learn how to customize the library's server selection behavior, see
+   :ref:`php-selection-discovery-options` in the Specify Connection Options guide.
+
 .. _php-local-threshold:
 
 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.
+The {+library-short+} uses the local threshold value to calculate the
+latency window for server selection. This value determines the servers
+that are eligible to receive read and write requests.
 
-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.
+By default, the library uses only ``mongos`` instances or replica set members whose
+ping times are within 15 milliseconds of the nearest server. To
+distribute reads among servers 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:
 

source/data-formats.txt

@@ -25,6 +25,7 @@ Specialized Data Formats
    Decimal128 </data-formats/decimal128>
    BSON </data-formats/modeling-bson-data>
    Time Series </data-formats/time-series>
+   Extended JSON </data-formats/extended-json>
 
 Overview
 --------
@@ -36,4 +37,5 @@ guides:
 - :ref:`php-custom-types`
 - :ref:`php-decimal128`
 - :ref:`php-bson`
-- :ref:`php-time-series`
+- :ref:`php-time-series`
+- :ref:`php-extended-json`

source/data-formats/extended-json.txt

@@ -0,0 +1,203 @@
+.. _php-extended-json:
+
+============================
+Work with Extended JSON Data
+============================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: code examples, bson, relaxed, canonical
+
+Overview
+--------
+
+In this guide, you can learn how to use the **Extended JSON** data format
+when interacting with MongoDB documents.
+
+JSON is a human-readable data format that represents the values of objects,
+arrays, numbers, strings, booleans, and nulls. This format supports only a
+subset of BSON data types, which is the format that MongoDB uses to store data. The
+Extended JSON format supports more BSON types, defining a reserved
+set of keys prefixed with "``$``" to represent field type information that
+directly corresponds to each type in BSON.
+
+Extended JSON Formats
+---------------------
+
+MongoDB Extended JSON features two string formats to represent BSON data.
+Each format conforms to the `JSON RFC <https://www.rfc-editor.org/rfc/rfc8259>`__
+and meets specific use cases.
+
+The following table describes each Extended JSON format:
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 10 40
+
+   * - Name
+     - Description
+
+   * - **Canonical** or **Extended**
+     - | A string format that avoids loss of BSON type information during data conversions.
+       | This format prioritizes type preservation at the loss of human-readability and
+         interoperability with older formats.
+
+   * - **Relaxed Mode**
+     - | A string format that describes BSON documents with some type information loss.
+       | This format prioritizes human-readability and interoperability at the loss of
+         certain type information.
+
+To learn more about JSON, BSON, and Extended JSON, see the
+`JSON and BSON <https://www.mongodb.com/resources/basics/json-and-bson>`__ resource
+and :manual:`Extended JSON </reference/mongodb-extended-json/>` {+mdb-server+} manual
+entry.
+
+.. _php-extended_json_example:
+
+Extended JSON Examples
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following example shows a document containing an ``ObjectId``, date, and long
+number field represented in the Extended JSON format. Select the :guilabel:`Canonical`
+or the :guilabel:`Relaxed Mode` tab to view the sample document in each Extended
+JSON format:
+
+.. tabs::
+
+   .. tab:: Canonical
+      :tabid: canonical-format
+
+      .. code-block:: json
+
+         {
+           "_id": { "$oid": "573a1391f29313caabcd9637" },
+           "createdAt": { "$date": { "$numberLong": "1601499609" }},
+           "numViews": { "$numberLong": "36520312" }
+         }
+
+   .. tab:: Relaxed Mode
+      :tabid: relaxed-mode-format
+
+      .. code-block:: json
+
+         {
+           "_id": { "$oid": "573a1391f29313caabcd9637" },
+           "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
+           "numViews": 36520312
+         }
+
+Write Extended JSON
+-------------------
+
+You can write an Extended JSON string from a BSON document object by using the
+``toRelaxedExtendedJSON()`` and ``toCanonicalExtendedJSON()`` methods.
+
+The following example outputs a BSON document in both Relaxed and Canonical
+Extended JSON formats:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/extended-json.php
+      :start-after: start-write-extended
+      :end-before: end-write-extended
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      Relaxed format: { "foo" : [ 1, 2 ], "bar" : { "hello" : "world" }, "code" :
+      { "$code" : "function x() { return 1; }", "$scope" : { } }, "date" : { } }
+      Canonical format: { "foo" : [ { "$numberInt" : "1" }, { "$numberInt" : "2" } ],
+      "bar" : { "hello" : "world" }, "code" : { "$code" : "function x() { return 1; }",
+      "$scope" : { } }, "date" : { } }
+
+Read Extended JSON
+------------------
+
+You can read an Extended JSON string into a PHP value by calling
+the ``json_decode()`` method, which converts Extended JSON to a
+PHP array or object. Pass the following arguments to ``json_decode()``:
+
+- Extended JSON string to read.
+- Boolean value that indicates whether you want to return
+  an array value. If set to ``false``, the method returns an
+  object value.
+
+The following example converts an Extended JSON string value
+to a PHP array:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/extended-json.php
+      :start-after: start-read-extended
+      :end-before: end-read-extended
+      :language: php
+      :dedent:
+
+   .. output:: 
+      :visible: false
+
+      Array
+      (
+          [foo] => Array
+              (
+                  [0] => Array
+                      (
+                        [$numberInt] => 1
+                      )
+
+                  [1] => Array
+                      (
+                          [$numberInt] => 2
+                      )
+
+              )
+
+          [bar] => Array
+              (
+                  [hello] => world
+              )
+
+          [code] => Array
+              (
+                  [$code] => function x() { return 1; }
+                  [$scope] => Array
+                      (
+                      )
+
+              )
+
+          [bin] => Array
+              (
+                  [$binary] => Array
+                      (
+                          [base64] => AQIDBA==
+                          [subType] => 00
+                      )
+  
+              )
+
+      )
+
+API Documentation
+-----------------
+
+To learn more about the methods discussed on this page, see
+the following {+extension-short+} API documentation:
+
+- :php:`MongoDB\BSON\Document::toRelaxedExtendedJSON() <mongodb-bson-document.torelaxedextendedjson>`
+- :php:`MongoDB\BSON\Document::toCanonicalExtendedJSON() <mongodb-bson-document.tocanonicalextendedjson>`
+- :php:`json_decode() <function.json-decode>`

source/includes/authentication.php

@@ -2,6 +2,24 @@
 
 require __DIR__ . '/../vendor/autoload.php';
 
+// start-default-client
+$uriOptions = [
+    'username' => '<username>',
+    'password' => '<password>',
+    'authSource' => '<authentication database>',
+];
+
+$client = new MongoDB\Client(
+    'mongodb://<hostname>:<port>',
+    $uriOptions,
+);
+// end-default-client
+
+// start-default-uri
+$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin';
+$client = new MongoDB\Client($uri);
+// end-default-uri
+
 // start-scram-sha-256-client
 $uriOptions = [
     'username' => '<username>',

source/includes/extended-json.php

@@ -0,0 +1,33 @@
+<?php
+
+require 'vendor/autoload.php';
+
+// start-write-extended
+$doc = [
+    'foo' => [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