Skip to content

Commit 857753b

Browse files
norareidynorareidy
committed
more info
1 parent 3d7ae37 commit 857753b

File tree

3 files changed

+178
-126
lines changed

3 files changed

+178
-126
lines changed

‎source/databases-collections.txt

Lines changed: 1 addition & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -200,116 +200,7 @@ You can change these settings by passing an options array to the
200200
``MongoDB\Database::selectCollection()`` methods.
201201

202202
To learn more about setting a read preference, read concern, and write concern,
203-
see the :ref:`php-crud-write-read-pref` guide.
204-
205-
To change the read preference, read concern, and write concern of your database
206-
or collection, set the following options in the array parameter:
207-
208-
- ``readPreference``: Sets the read preference. For a list of available read
209-
preferences, see :php:`MongoDB\Driver\ReadPreference <mongodb-driver-readpreference>`
210-
in the extension API documentation.
211-
- ``readConcern``: Sets the read concern. For a list of available read
212-
concerns, see :php:`MongoDB\Driver\ReadConcern <mongodb-driver-readconcern>`
213-
in the extension API documentation.
214-
- ``writeConcern``: Sets the write concern. For a list of available write
215-
concerns, see :php:`MongoDB\Driver\WriteConcern <mongodb-driver-writeconcern>`
216-
in the extension API documentation.
217-
218-
.. tip::
219-
220-
To learn more about read preferences and read and write concerns, see the
221-
following guides in the MongoDB Server manual:
222-
223-
- :manual:`Read Preference </core/read-preference/>`
224-
- :manual:`Read Concern </reference/read-concern/>`
225-
- :manual:`Write Concern </reference/write-concern/>`
226-
227-
Database Configuration Example
228-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229-
230-
The following example shows how to set the read preference, read concern, and
231-
write concern of a database called ``test_database`` by passing an options
232-
array to ``selectDatabase()``:
233-
234-
.. literalinclude:: /includes/databases-collections/databases-collections.php
235-
:language: php
236-
:dedent:
237-
:start-after: start-database-settings
238-
:end-before: end-database-settings
239-
240-
Collection Configuration Example
241-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
242-
243-
The following example shows how to set the read preference, read concern, and
244-
write concern of a collection called ``test_collection`` by passing an options
245-
array to ``selectCollection()``:
246-
247-
.. literalinclude:: /includes/databases-collections/databases-collections.php
248-
:language: php
249-
:dedent:
250-
:start-after: start-collection-settings
251-
:end-before: end-collection-settings
252-
253-
Advanced Read Configurations
254-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
255-
256-
Tag Sets
257-
````````
258-
259-
In {+mdb-server+}, you can apply key-value :manual:`tags
260-
</core/read-preference-tags/>` to replica-set
261-
members according to any criteria you choose. You can then use
262-
those tags to target one or more members for a read operation.
263-
264-
By default, the {+php-library+} ignores tags when choosing a member
265-
to read from. To instruct the {+php-library+} to prefer certain tags,
266-
pass them as a parameter to your ``MongoDB\Driver\ReadPreference`` class
267-
constructor. Then, set the ``MongoDB\Driver\ReadPreference`` object as
268-
the value of the ``readPreference`` database option.
269-
270-
This code example sets the ``readPreference`` option to a tag set
271-
that instructs ``test_database`` to prefer reads from secondary replica set
272-
members in the following order:
273-
274-
1. Members from the New York data center (``['dc' => 'ny']``)
275-
#. Members from the San Francisco data center (``['dc' => 'sf']``)
276-
#. Any secondary members (``[]``)
277-
278-
.. literalinclude:: /includes/databases-collections/databases-collections.php
279-
:language: php
280-
:dedent:
281-
:start-after: start-tag-set
282-
:end-before: end-tag-set
283-
284-
Local Threshold
285-
```````````````
286-
287-
If multiple replica-set members match the read preference and tag sets you specify,
288-
the {+php-library+} reads from the nearest replica-set members, chosen according to
289-
their ping time.
290-
291-
By default, the library uses only members whose ping times are within 15 milliseconds
292-
of the nearest member for queries. To distribute reads between members with
293-
higher latencies, pass an options array to the ``MongoDB\Client`` constructor that
294-
sets the ``localThresholdMS`` option.
295-
296-
The following example specifies a local threshold of 35 milliseconds:
297-
298-
.. literalinclude:: /includes/databases-collections/databases-collections.php
299-
:language: php
300-
:dedent:
301-
:start-after: start-local-threshold
302-
:end-before: end-local-threshold
303-
304-
In the preceding example, the {+php-library+} distributes reads among matching members
305-
within 35 milliseconds of the closest member's ping time.
306-
307-
.. note::
308-
309-
The {+php-library+} ignores the value of ``localThresholdMS`` when communicating with a
310-
replica set through a ``mongos`` instance. In this case, use the
311-
:manual:`localThreshold </reference/program/mongos/#std-option-mongos.--localThreshold>`
312-
command-line option.
203+
see the :ref:`php-read-write-pref` guide.
313204

314205
API Documentation
315206
-----------------

‎source/includes/read-write-pref.php

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
use MongoDB\Driver\ReadConcern;
5+
use MongoDB\Driver\ReadPreference;
6+
use MongoDB\Driver\WriteConcern;
7+
use MongoDB\Client;
8+
9+
// start-client-settings
10+
$clientOptions = [
11+
'readPreference' => 'secondary',
12+
'readConcernLevel' => 'local',
13+
'w' => 'majority',
14+
];
15+
16+
$client = new Client('mongodb://localhost:27017', $clientOptions);
17+
// end-client-settings
18+
19+
// start-client-settings-uri
20+
$uri = 'mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=majority';
21+
$client = new Client($uri);
22+
// end-client-settings-uri
23+
24+
// start-session-settings
25+
$sessionOptions = [
26+
'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY),
27+
'readConcern' => new ReadConcern(ReadConcern::LOCAL),
28+
'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
29+
];
30+
31+
$session = $client->startSession($sessionOptions);
32+
// end-session-settings
33+
34+
// start-transaction-settings
35+
$transactionOptions = [
36+
'readPreference' => new ReadPreference(ReadPreference::RP_PRIMARY),
37+
'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
38+
'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
39+
];
40+
41+
// Start the transaction
42+
$session->startTransaction($transactionOptions);
43+
// end-transaction-settings
44+
45+
// Sets read and write settings for the "test_database" database
46+
// start-database-settings
47+
$readPreference = new ReadPreference(ReadPreference::RP_PRIMARY_PREFERRED);
48+
$readConcern = new ReadConcern(ReadConcern::LOCAL);
49+
$writeConcern = new WriteConcern(WriteConcern::MAJORITY);
50+
51+
$db = $client->selectDatabase('test_database', [
52+
'readPreference' => $readPreference,
53+
'readConcern' => $readConcern,
54+
'writeConcern' => $writeConcern,
55+
]);
56+
// end-database-settings
57+
58+
// Sets read and write settings for the "test_collection" collection
59+
// start-collection-settings
60+
$readPreference = new ReadPreference(ReadPreference::RP_PRIMARY);
61+
$readConcern = new ReadConcern(ReadConcern::AVAILABLE);
62+
$writeConcern = new WriteConcern(WriteConcern::MAJORITY);
63+
64+
$collection = $client->selectCollection('test_database', 'test_collection', [
65+
'readPreference' => $readPreference,
66+
'readConcern' => $readConcern,
67+
'writeConcern' => $writeConcern,
68+
]);
69+
70+
// end-collection-settings
71+
72+
// Instructs the library to prefer reads from secondary replica set members
73+
// located in New York, followed by a secondary in San Francisco, and
74+
// lastly fall back to any secondary.
75+
// start-tag-set
76+
$readPreference = new ReadPreference(
77+
ReadPreference::RP_SECONDARY,
78+
[
79+
['dc' => 'ny'],
80+
['dc' => 'sf'],
81+
[],
82+
],
83+
);
84+
85+
$db = $client->selectDatabase(
86+
'test_database',
87+
['readPreference' => $readPreference],
88+
);
89+
90+
// end-tag-set
91+
92+
// Instructs the library to distribute reads between members within 35 milliseconds
93+
// of the closest member's ping time
94+
// start-local-threshold
95+
$options = [
96+
'replicaSet' => 'repl0',
97+
'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED),
98+
'localThresholdMS' => 35,
99+
];
100+
101+
$client = new Client('<connection string>', [], $options);
102+
// end-local-threshold

‎source/read-write-pref.txt

Lines changed: 75 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,18 @@ Configure Read and Write Operations
4747

4848
This section shows how to configure the read preference, read concern, and write
4949
concern at various levels by passing an options array parameter to the following
50-
objects and methods:
51-
52-
- :ref:`MongoDB\\Client <php-read-write-client>`
53-
- :ref:`MongoDB\\Driver\\Session <php-read-write-session>`
54-
- :ref:`MongoDB\\with_transaction() <php-read-write-transaction>`
55-
- :ref:`MongoDB\\Database <php-read-write-database>`
56-
- :ref:`MongoDB\\Collection <php-read-write-collection>`
50+
methods:
51+
52+
- :ref:`MongoDB\\Client::__construct() <php-read-write-client>`: Configures read
53+
and write settings at the client level
54+
- :ref:`MongoDB\\Client::startSession() <php-read-write-session>`: Configures read
55+
and write settings at the session level
56+
- :ref:`MongoDB\\Driver\\Session::startTransaction() <php-read-write-transaction>`:
57+
Configures read and write settings at the transaction level
58+
- :ref:`MongoDB\\Client::selectDatabase() <php-read-write-database>`: Configures read
59+
and write settings at the database level
60+
- :ref:`MongoDB\\Client::selectCollection() <php-read-write-collection>`: Configures read
61+
and write settings at the collection level
5762

5863
In the options parameter, specify the following values:
5964

@@ -67,6 +72,13 @@ In the options parameter, specify the following values:
6772
concerns, see :php:`MongoDB\Driver\WriteConcern <mongodb-driver-writeconcern>`
6873
in the extension API documentation.
6974

75+
.. note::
76+
77+
When setting a write concern at the ``MongoDB\Client`` level, specify the ``w``
78+
value in an options array rather than ``writeConcern.`` You can also specify
79+
read and write settings in the connection URI. For more information,
80+
see the :ref:`php-read-write-client`.
81+
7082
.. _php-read-write-client:
7183

7284
Client Configuration Example
@@ -76,30 +88,59 @@ The following example shows how to set the read preference, read concern, and
7688
write concern of a ``MongoDB\Client`` instance by passing an array to
7789
the constructor:
7890

79-
.. literalinclude:: /includes/databases-collections/databases-collections.php
91+
.. literalinclude:: /includes/read-write-pref.php
8092
:language: php
8193
:dedent:
82-
:start-after: start-database-settings
83-
:end-before: end-database-settings
94+
:start-after: start-client-settings
95+
:end-before: end-client-settings
96+
97+
Alternatively, you can specify the read and write settings in the connection
98+
URI, which is passed as a parameter to the ``MongoDB\Client`` constructor:
99+
100+
.. literalinclude:: /includes/read-write-pref.php
101+
:language: php
102+
:dedent:
103+
:start-after: start-client-settings-uri
104+
:end-before: end-client-settings-uri
84105

85106
.. _php-read-write-session:
86107

87108
Session Configuration Example
88109
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89110

111+
The following example shows how to set the read preference, read concern, and
112+
write concern of a session by passing an array to the ``startSession()``
113+
method:
114+
115+
.. literalinclude:: /includes/read-write-pref.php
116+
:language: php
117+
:dedent:
118+
:start-after: start-session-settings
119+
:end-before: end-session-settings
120+
90121
.. _php-read-write-transaction:
91122

92123
Transaction Configuration Example
93124
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94125

126+
The following example shows how to set the read preference, read concern, and
127+
write concern of a transaction by passing an array to the ``startTransaction()``
128+
method:
129+
130+
.. literalinclude:: /includes/read-write-pref.php
131+
:language: php
132+
:dedent:
133+
:start-after: start-transaction-settings
134+
:end-before: end-transaction-settings
135+
95136
.. _php-read-write-database:
96137

97138
Database Configuration Example
98139
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99140

100141
The following example shows how to set the read preference, read concern, and
101142
write concern of a database called ``test_database`` by passing an options
102-
array to ``selectDatabase()``:
143+
array to the ``selectDatabase()`` method:
103144

104145
.. literalinclude:: /includes/databases-collections/databases-collections.php
105146
:language: php
@@ -114,19 +155,29 @@ Collection Configuration Example
114155

115156
The following example shows how to set the read preference, read concern, and
116157
write concern of a collection called ``test_collection`` by passing an options
117-
array to ``selectCollection()``:
158+
array to the ``selectCollection()`` method:
118159

119160
.. literalinclude:: /includes/databases-collections/databases-collections.php
120161
:language: php
121162
:dedent:
122163
:start-after: start-collection-settings
123164
:end-before: end-collection-settings
124165

166+
.. _php-read-write-advanced:
167+
125168
Advanced Read Configurations
126-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
169+
----------------------------
170+
171+
This section shows how to further customize your read operation
172+
settings in the following ways:
173+
174+
- :ref:`Apply a tag set <php-tag-sets>`
175+
- :ref:`Specify a local threshold <php-local-threshold>`
176+
177+
.. _php-tag-sets:
127178

128179
Tag Sets
129-
````````
180+
~~~~~~~~
130181

131182
In {+mdb-server+}, you can apply key-value :manual:`tags
132183
</core/read-preference-tags/>` to replica-set
@@ -153,8 +204,10 @@ members in the following order:
153204
:start-after: start-tag-set
154205
:end-before: end-tag-set
155206

207+
.. _php-local-threshold:
208+
156209
Local Threshold
157-
```````````````
210+
~~~~~~~~~~~~~~~
158211

159212
If multiple replica-set members match the read preference and tag sets you specify,
160213
the {+php-library+} reads from the nearest replica-set members, chosen according to
@@ -198,4 +251,10 @@ API Documentation
198251
~~~~~~~~~~~~~~~~~
199252

200253
To learn more about any of the methods or types discussed in this
201-
guide, see the following API documentation:
254+
guide, see the following API documentation:
255+
256+
- :phpmethod:`MongoDB\Client::__construct()`
257+
- :phpmethod:`MongoDB\Client::startSession()`
258+
- :php:`MongoDB\Driver\Session::startTransaction()`
259+
- :phpmethod:`MongoDB\Client::selectDatabase()`
260+
- :phpmethod:`MongoDB\Client::selectCollection()`

0 commit comments

Comments
 (0)