DOCSP-41965: Read and write settings (#146)

* DOCSP-41965: Read and write settings

* more info

* edits

* edits

* headers

* fix link

* fix

* RR feedback

* api docs

* fix

* fix

Author: norareidy

source/databases-collections.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/includes/read-write-pref.php

@@ -0,0 +1,93 @@
+<?php
+require 'vendor/autoload.php';
+
+use MongoDB\Driver\ReadConcern;
+use MongoDB\Driver\ReadPreference;
+use MongoDB\Driver\WriteConcern;
+use MongoDB\Client;
+
+// start-client-settings
+$clientOptions = [
+    'readPreference' => 'secondary',
+    'readConcernLevel' => 'local',
+    'w' => '2',
+];
+
+$client = new Client('mongodb://localhost:27017', $clientOptions);
+// end-client-settings
+
+// start-client-settings-uri
+$uri = 'mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=2';
+$client = new Client($uri);
+// end-client-settings-uri
+
+// start-session-settings
+$sessionOptions = [
+    'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED),
+    'readConcern' => new ReadConcern(ReadConcern::LOCAL),
+    'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
+];
+
+$session = $client->startSession($sessionOptions);
+// end-session-settings
+
+// start-transaction-settings
+$transactionOptions = [
+    'readPreference' => new ReadPreference(ReadPreference::PRIMARY),
+    'readConcern' => new ReadConcern(ReadConcern::MAJORITY),
+    'writeConcern' => new WriteConcern(1),
+];
+
+$session->startTransaction($transactionOptions);
+// end-transaction-settings
+
+// Sets read and write settings for the "test_database" database
+// start-database-settings
+$db = $client->selectDatabase('test_database', [
+    'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED),
+    'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
+    'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
+]);
+// end-database-settings
+
+// Sets read and write settings for the "test_collection" collection
+// start-collection-settings
+$collection = $client->selectCollection('test_database', 'test_collection', [
+    'readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED),
+    'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
+    'writeConcern' => new WriteConcern(0),
+]);
+
+// end-collection-settings
+
+// Instructs the library to prefer reads from secondary replica set members
+// located in New York, followed by a secondary in San Francisco, and
+// lastly fall back to any secondary.
+// start-tag-set
+$readPreference = new ReadPreference(
+    ReadPreference::RP_SECONDARY,
+    [
+        ['dc' => 'ny'],
+        ['dc' => 'sf'],
+        [],
+    ],
+);
+
+$db = $client->selectDatabase(
+    'test_database',
+    ['readPreference' => $readPreference],
+);
+
+// end-tag-set
+
+// Instructs the library to distribute reads between members within 35 milliseconds
+// of the closest member's ping time
+// start-local-threshold
+$options = [
+    'replicaSet' => 'repl0',
+    'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED),
+    'localThresholdMS' => 35,
+];
+
+$client = new Client('mongodb://localhost:27017', [], $options);
+// end-local-threshold

source/index.txt

@@ -18,6 +18,7 @@ MongoDB PHP Library
    /indexes
    /monitoring
    /security
+   /read-write-pref
    /tutorial
    /upgrade
    /reference