Skip to content

Commit 45739f4

Browse files
mongoKartmongoKart
committed
wip
1 parent e994533 commit 45739f4

File tree

5 files changed

+658
-0
lines changed

5 files changed

+658
-0
lines changed

‎snooty.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,6 @@ php-library = "MongoDB PHP Library"
2525
[constants]
2626
php-library = "MongoDB PHP Library"
2727
api = "https://www.mongodb.com/docs/php-library/current/reference"
28+
string-data-type = "``string``"
29+
bool-data-type = "``bool``"
30+
int-data-type = "``int``"

‎source/connect/connection-options.txt

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,346 @@
1+
.. _php-connection-options:
2+
3+
==========================
4+
Specify Connection Options
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: connection string, URI, server, Atlas, settings, configure
19+
20+
Overview
21+
--------
22+
23+
This page describes the MongoDB connection and authentication options
24+
available in the {+driver-short+}.
25+
26+
Set Connection Options
27+
----------------------
28+
29+
You can configure your connection by specifying options in the connection URI or by
30+
passing them to the ``MongoDB\Client`` constructor.
31+
32+
.. TODO:
33+
how uri object overrides uri
34+
- finish intro text
35+
36+
.. _php-connection-uri:
37+
38+
Using the Connection URI
39+
~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+
If you pass a connection URI to the ``MongoDB\Client`` constructor, you can include
42+
connection options in the URI as ``<name>=<value>`` pairs. In the following example,
43+
the connection URI contains the ``tls`` option with a value of ``true`` and the
44+
``tlsCertificateKeyFile`` option with a value of ``/path/to/file.pem``:
45+
46+
.. literalinclude:: /includes/connect/connection-options.php
47+
:language: php
48+
:copyable: true
49+
:start-after: // start-connection-uri
50+
:end-before: // end-connection-uri
51+
:emphasize-lines: 8
52+
53+
.. _php-client-object:
54+
55+
Using a MongoDB\Client Object
56+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57+
58+
You can pass connection options to the ``MongoDB\Client`` constructor
59+
instead of including them in your connection URI.
60+
Configuring the connection this way makes it easier to
61+
change settings at runtime and helps you catch errors during compilation.
62+
63+
The following example shows how to use the the ``$uriOptions`` parameter of the
64+
``MongoDB\Client`` constructor to set connection options:
65+
66+
.. literalinclude:: /includes/connect/connection-options.php
67+
:language: php
68+
:copyable: true
69+
:start-after: // start-client-options
70+
:end-before: // end-client-options
71+
:emphasize-lines: 8-12, 15
72+
73+
Connection URI Options
74+
----------------------
75+
76+
The following sections describe the options that you can set for your connection to
77+
MongoDB. Each connection option links to its corresponding
78+
entry in the {+mdb-server+} manual.
79+
80+
Replica Set Options
81+
~~~~~~~~~~~~~~~~~~~
82+
83+
.. list-table::
84+
:header-rows: 1
85+
:stub-columns: 1
86+
87+
* - Connection Option
88+
- Data Type
89+
- Syntax
90+
91+
* - :manual:`directConnection </reference/connection-string/#mongodb-urioption-urioption.directConnection>`
92+
- {+bool-data-type+}
93+
- | **MongoDB\Client**: ``$uriOptions = [ 'directConnection' => true ];``
94+
| **Connection URI**: ``directConnection=true``
95+
96+
* - :manual:`replicaSet </reference/connection-string/#mongodb-urioption-urioption.replicaSet>`
97+
- {+string-data-type+}
98+
- | **MongoDB\Client**: ``$uriOptions = [ 'replicaSet' => 'replicaSetName' ];``
99+
| **Connection URI**: ``replicaSet=replicaSetName``
100+
101+
Connection Options
102+
~~~~~~~~~~~~~~~~~~
103+
104+
TLS Options
105+
```````````
106+
To learn about the TLS options available in the {+driver-short+}, see the
107+
:ref:`TLS <php-tls>` page.
108+
109+
Timeout Options
110+
```````````````
111+
112+
.. list-table::
113+
:header-rows: 1
114+
:stub-columns: 1
115+
116+
* - Connection Option
117+
- Data Type
118+
- Syntax
119+
120+
* - :manual:`connectTimeoutMS </reference/connection-string/#mongodb-urioption-urioption.connecttimeoutms>`
121+
- {+int-data-type+}
122+
- | **MongoDB\Client**: ``$uriOptions = [ 'connectTimeoutMS' => 20000 ];``
123+
| **Connection URI**: ``connectTimeoutMS=20000``
124+
125+
* - :manual:`socketTimeoutMS </reference/connection-string/#mongodb-urioption-urioption.sockettimeoutms>`
126+
- {+int-data-type+}
127+
- | **MongoDB\Client**: ``$uriOptions = [ 'socketTimeoutMS' => 400000 ];``
128+
| **Connection URI**: ``socketTimeoutMS=400000``
129+
130+
.. _php-compression-options:
131+
132+
Compression Options
133+
```````````````````
134+
135+
.. list-table::
136+
:header-rows: 1
137+
:stub-columns: 1
138+
139+
* - Connection Option
140+
- Data Type
141+
- Syntax
142+
143+
* - :manual:`compressors </reference/connection-string/#mongodb-urioption-urioption.compressors>`
144+
- {+string-data-type+}
145+
- | **MongoDB\Client**: ``$uriOptions = [ 'compressors' => 'snappy,zstd,zlib' ];``
146+
| **Connection URI**: ``compressors=snappy,zstd,zlib``
147+
148+
* - :manual:`zlibCompressionLevel </reference/connection-string/#mongodb-urioption-urioption.zlibcompressionlevel>`
149+
- {+int-data-type+}
150+
- | **MongoDB\Client**: ``$uriOptions = [ 'compressors' => 'snappy,zstd,zlib', 'zlibCompressionLevel' => 3 ];``
151+
| **Connection URI**: ``compressors=snappy,zstd,zlib&zlibCompressionLevel=3``
152+
153+
Connection Pool Options
154+
~~~~~~~~~~~~~~~~~~~~~~~
155+
156+
.. list-table::
157+
:header-rows: 1
158+
:stub-columns: 1
159+
160+
* - Connection Option
161+
- Data Type
162+
- Syntax
163+
164+
* - :manual:`maxPoolSize </reference/connection-string/#mongodb-urioption-urioption.maxpoolsize>`
165+
- {+int-data-type+}
166+
- | **Connection URI**: ``maxPoolSize=75``
167+
168+
* - :manual:`waitQueueTimeoutMS </reference/connection-string/#mongodb-urioption-urioption.waitqueuetimeoutms>`
169+
- {+int-data-type+}
170+
- | **Connection URI**: ``waitQueueTimeoutMS=10000``
171+
172+
Write Concern Options
173+
~~~~~~~~~~~~~~~~~~~~~
174+
175+
.. list-table::
176+
:header-rows: 1
177+
:stub-columns: 1
178+
179+
* - Connection Option
180+
- Data Type
181+
- Syntax
182+
183+
* - :manual:`w </reference/connection-string/#mongodb-urioption-urioption.w>`
184+
- {+string-data-type+}
185+
- | **MongoDB\Client**: ``$uriOptions = [ 'w' => 'majority' ];``
186+
| **Connection URI**: ``w=majority``
187+
188+
* - :manual:`wTimeoutMS </reference/connection-string/#mongodb-urioption-urioption.wtimeoutms>`
189+
- {+int-data-type+}
190+
- | **MongoDB\Client**: ``$uriOptions = [ 'wTimeoutMS' => 10000 ];``
191+
| **Connection URI**: ``wTimeoutMS=10000``
192+
193+
* - :manual:`journal </reference/connection-string/#mongodb-urioption-urioption.journal>`
194+
- {+bool-data-type+}
195+
- | **MongoDB\Client**: ``$uriOptions = [ 'journal' => true ];``
196+
| **Connection URI**: ``journal=true``
197+
198+
Read Concern Options
199+
~~~~~~~~~~~~~~~~~~~~
200+
201+
.. list-table::
202+
:header-rows: 1
203+
:stub-columns: 1
204+
205+
* - Connection Option
206+
- Data Type
207+
- Syntax
208+
209+
* - :manual:`readConcernLevel </reference/connection-string/#mongodb-urioption-urioption.readconcernlevel>`
210+
- {+string-data-type+}
211+
- | **MongoDB\Client**: ``$uriOptions = [ 'readConcernLevel' => 'majority' ];``
212+
| **Connection URI**: ``readConcernLevel=majority``
213+
214+
Read Preference Options
215+
~~~~~~~~~~~~~~~~~~~~~~~
216+
217+
.. list-table::
218+
:header-rows: 1
219+
:stub-columns: 1
220+
221+
* - Connection Option
222+
- Data Type
223+
- Syntax
224+
225+
* - :manual:`readPreference </reference/connection-string/#mongodb-urioption-urioption.readpreference>`
226+
- `MongoDB\Driver\ReadPreference <https://www.php.net/manual/en/class.mongodb-driver-readpreference.php>`__
227+
- | **MongoDB\Client**: ``$uriOptions = [ 'readPreference' => MongoDB\Driver\ReadPreference.RP_SECONDARY_PREFERRED ];``
228+
| **Connection URI**: ``readPreference=secondaryPreferred``
229+
230+
* - :manual:`maxStalenessSeconds </reference/connection-string/#mongodb-urioption-urioption.maxstalenessseconds>`
231+
- {+int-data-type+}
232+
- | **MongoDB\Client**: ``$uriOptions = [ 'maxStalenessSeconds' => 30 ];``
233+
| **Connection URI**: ``maxStalenessSeconds=30``
234+
235+
* - :manual:`readPreferenceTags </reference/connection-string/#mongodb-urioption-urioption.readpreferencetags>`
236+
- ``array``
237+
- | **MongoDB\Client**: ``$uriOptions = [ 'readPreferenceTags' => [[ 'region' => 'east' ], [ 'region' => 'west']];``
238+
| **Connection URI**: ``readPreferenceTags=region:east,region:west``
239+
240+
241+
Authentication Options
242+
~~~~~~~~~~~~~~~~~~~~~~
243+
244+
.. list-table::
245+
:header-rows: 1
246+
:stub-columns: 1
247+
248+
* - Connection Option
249+
- Data Type
250+
- Syntax
251+
252+
* - :manual:`authMechanism </reference/connection-string/#mongodb-urioption-urioption.authmechanism>`
253+
- {+string-data-type+}
254+
- | **MongoDB\Client**: ``$uriOptions = [ 'authMechanism' => 'MONGODB-X509' ];``
255+
| **Connection URI**: ``authMechanism=MONGODB-X509``
256+
257+
* - :manual:`authMechanismProperties </reference/connection-string/#mongodb-urioption-urioption.authmechanismproperties>`
258+
- {+string-data-type+}
259+
- | **MongoDB\Client**: ``$uriOptions = [ 'authMechanism' => 'MONGODB-AWS', 'authMechanismProperties' => 'AWS_SESSION_TOKEN:12345' ];``
260+
| **Connection URI**: ``authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:12345``
261+
262+
* - :manual:`authSource </reference/connection-string/#mongodb-urioption-urioption.authsource>`
263+
- {+string-data-type+}
264+
- | **MongoDB\Client**: ``$uriOptions = [ 'authSource' => 'admin' ];``
265+
| **Connection URI**: ``authSource=admin``
266+
267+
Server Selection and Discovery Options
268+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
269+
270+
.. list-table::
271+
:header-rows: 1
272+
:stub-columns: 1
273+
274+
* - Connection Option
275+
- Data Type
276+
- Syntax
277+
278+
* - :manual:`localThresholdMS </reference/connection-string/#mongodb-urioption-urioption.localthresholdms>`
279+
- {+int-data-type+}
280+
- | **MongoDB\Client**: ``$uriOptions = [ 'localThresholdMS' => 20 ];``
281+
| **Connection URI**: ``localThresholdMS=20``
282+
283+
* - :manual:`serverSelectionTimeoutMS </reference/connection-string/#mongodb-urioption-urioption.serverselectiontimeoutms>`
284+
- {+int-data-type+}
285+
- | **MongoDB\Client**: ``$uriOptions = [ 'serverSelectionTimeoutMS' => 40000 ];``
286+
| **Connection URI**: ``serverSelectionTimeoutMS=40000``
287+
288+
* - :manual:`serverSelectionTryOnce </reference/connection-string/#mongodb-urioption-urioption.serverselectiontryonce>`
289+
- {+bool-data-type+}
290+
- | **MongoDB\Client**: ``$uriOptions = [ 'serverSelectionTryOnce' => false ];``
291+
| **Connection URI**: ``serverSelectionTryOnce=false``
292+
293+
* - :manual:`heartbeatFrequencyMS </reference/connection-string/#mongodb-urioption-urioption.heartbeatfrequencyms>`
294+
- {+int-data-type+}
295+
- | **MongoDB\Client**: ``$uriOptions = [ 'heartbeatFrequencyMS' => 50000 ];``
296+
| **Connection URI**: ``heartbeatFrequencyMS=50000``
297+
298+
* - :manual:`socketCheckIntervalMS </reference/connection-string/#mongodb-urioption-urioption.socketcheckintervalms>`
299+
- {+int-data-type+}
300+
- | **MongoDB\Client**: ``$uriOptions = [ 'socketCheckIntervalMS' => 4000 ];``
301+
| **Connection URI**: ``socketCheckIntervalMS=4000``
302+
303+
Miscellaneous Configuration
304+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
305+
306+
.. list-table::
307+
:header-rows: 1
308+
:stub-columns: 1
309+
310+
* - Connection Option
311+
- Data Type
312+
- Syntax
313+
314+
* - :manual:`appName </reference/connection-string/#mongodb-urioption-urioption.appname>`
315+
- {+string-data-type+}
316+
- | **MongoDB\Client**: ``$uriOptions = [ 'appName' => 'myApp' ];``
317+
| **Connection URI**: ``appName=myApp``
318+
319+
* - :manual:`retryReads </reference/connection-string/#mongodb-urioption-urioption.retryreads>`
320+
- {+bool-data-type+}
321+
- | **MongoDB\Client**: ``$uriOptions = [ 'retryReads' => false ];``
322+
| **Connection URI**: ``retryReads=false``
323+
324+
* - :manual:`retryWrites </reference/connection-string/#mongodb-urioption-urioption.retrywrites>`
325+
- {+bool-data-type+}
326+
- | **MongoDB\Client**: ``$uriOptions = [ 'retryWrites' => false ];``
327+
| **Connection URI**: ``retryWrites=false``
328+
329+
* - :manual:`loadBalanced </reference/connection-string/#mongodb-urioption-urioption.loadbalanced>`
330+
- {+bool-data-type+}
331+
- | **MongoDB\Client**: ``$uriOptions = [ 'loadBalanced' => true ];``
332+
| **Connection URI**: ``loadBalanced=false``
333+
334+
* - :manual:`srvMaxHosts </reference/connection-string/#mongodb-urioption-urioption.srvmaxhosts>`
335+
- {+int-data-type+}
336+
- | **MongoDB\Client**: ``$uriOptions = [ 'srvMaxHosts' => 5 ];``
337+
| **Connection URI**: ``srvMaxHosts=5``
338+
339+
API Documentation
340+
-----------------
341+
342+
For more information about the types used on this page, see the following API
343+
documentation:
344+
345+
- :ref:`MongoDB\Client <php-mongodbclient>`
346+
- `MongoDB\Driver\ReadPreference <https://www.php.net/manual/en/class.mongodb-driver-readpreference.php>`__

0 commit comments

Comments
 (0)