Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit eea4950

Browse files
author
Chris Cho
authored
DOCSP-35941 connection options (#2892)
* DOCSP-35941: Connection Options docs
1 parent 19bb87f commit eea4950

File tree

3 files changed

+357
-9
lines changed

3 files changed

+357
-9
lines changed

‎docs/fundamentals.txt‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,7 @@ Fundamentals
2222

2323
Learn how to use the {+odm-long+} to perform the following tasks:
2424

25-
- :ref:`Configure Your MongoDB Connection <laravel-fundamentals-connection>`
26-
- :ref:`Databases and Collections <laravel-db-coll>`
27-
- :ref:`Read Operations <laravel-fundamentals-read-ops>`
28-
- :ref:`Write Operations <laravel-fundamentals-write-ops>`
29-
25+
- :ref:`laravel-fundamentals-connection`
26+
- :ref:`laravel-db-coll`
27+
- :ref:`laravel-fundamentals-read-ops`
28+
- :ref:`laravel-fundamentals-write-ops`

‎docs/fundamentals/connection.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Connections
77
.. toctree::
88

99
/fundamentals/connection/connect-to-mongodb
10+
/fundamentals/connection/connection-options
1011

1112
.. contents:: On this page
1213
:local:
@@ -17,9 +18,8 @@ Connections
1718
Overview
1819
--------
1920

20-
Learn how to set up a connection from your Laravel application to a MongoDB
21-
deployment and specify the connection behavior by using {+odm-short+} in the
22-
following sections:
21+
Learn how to use {+odm-short+} to set up a connection to a MongoDB deployment
22+
and specify connection behavior in the following sections:
2323

2424
- :ref:`laravel-connect-to-mongodb`
25-
25+
- :ref:`laravel-fundamentals-connection-options`
Lines changed: 349 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,349 @@
1+
.. _laravel-fundamentals-connection-options:
2+
3+
==================
4+
Connection Options
5+
==================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, data source name, dsn, authentication, configuration, options, driverOptions
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn about connection, authentication, and driver
24+
options and how to specify them in your Laravel application's database
25+
connection configuration. Connection options are passed to the {+php-library+},
26+
which manages your database connections.
27+
28+
To learn more about the {+php-library+}, see the
29+
`{+php-library+} documentation <https://www.mongodb.com/docs/php-library/current/>`__.
30+
31+
This guide covers the following topics:
32+
33+
- :ref:`laravel-connection-auth-options`
34+
- :ref:`laravel-driver-options`
35+
36+
.. _laravel-connection-auth-options:
37+
38+
Connection and Authentication Options
39+
-------------------------------------
40+
41+
Learn how to add common connection and authentication options to your
42+
configuration file in the following sections:
43+
44+
- :ref:`laravel-connection-auth-example`
45+
- :ref:`laravel-connection-auth-descriptions`
46+
47+
.. _laravel-connection-auth-example:
48+
49+
Add Connection and Authentication Options
50+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51+
52+
You can specify connection or authentication options in your Laravel web
53+
application's ``config/database.php`` configuration file by using one of the
54+
following methods:
55+
56+
- Add the setting and value as an array item in the ``options`` array item.
57+
- Append the setting and value as a query string parameter on the connection
58+
string specified in the ``dsn`` array item.
59+
60+
To specify an option in the ``options`` array, add its name and value as an
61+
array item, as shown in the following example:
62+
63+
.. code-block:: php
64+
:emphasize-lines: 6-10
65+
66+
'connections' => [
67+
'mongodb' => [
68+
'dsn' => 'mongodb+srv://mongodb0.example.com/',
69+
'driver' => 'mongodb',
70+
'database' => 'sample_mflix',
71+
'options' => [
72+
'appName' => 'myLaravelApp',
73+
'compressors' => 'zlib',
74+
'zlibCompressionLevel' => 7,
75+
],
76+
],
77+
],
78+
79+
To specify options as parameters in the connection string, use the following
80+
query string syntax formatting:
81+
82+
- Add the question mark character, ``?``, to separate the host information
83+
from the parameters.
84+
- Add the options by formatting them as ``<option>=<value>``.
85+
- Insert the ampersand character, ``&``, between each option and value pair
86+
to separate them.
87+
88+
The following setting example shows the connection string parameter syntax:
89+
90+
.. code-block:: php
91+
92+
'dsn' => 'mongodb+srv://mongodb0.example.com/?appName=myLaravelApp&compressors=zlib',
93+
94+
.. _laravel-connection-auth-descriptions:
95+
96+
Option Descriptions
97+
~~~~~~~~~~~~~~~~~~~
98+
99+
The following table describes a list of connection and authentication options
100+
and their default values:
101+
102+
.. list-table::
103+
:header-rows: 1
104+
:widths: 30 12 12 46
105+
106+
* - Option Name
107+
- Accepted Values
108+
- Default Value
109+
- Description
110+
111+
* - **appName**
112+
- String
113+
- None
114+
- | Specifies the application name that the {+php-library+} sends the
115+
MongoDB deployment as part of the handshake.
116+
| Specifying ``appName`` can help you identify activities related
117+
to that application in the server logs.
118+
119+
* - **authMechanism**
120+
- String
121+
- None
122+
- Specifies which authentication mechanism to use. If you do not
123+
specify this option, the driver uses the default authentication
124+
mechanism. To learn more, see :manual:`Authentication </core/authentication/>`
125+
in the {+server-docs-name+}.
126+
127+
* - **authMechanismProperties**
128+
- String
129+
- None
130+
- Specifies more properties related to the authentication mechanism set in
131+
the ``authMechanism`` option.
132+
133+
* - **authSource**
134+
- String
135+
- See description
136+
- | Specifies the database used to authenticate.
137+
| This option defaults to ``admin`` for SCRAM-based authentication
138+
mechanisms, ``$external`` for the ``MONGODB-X509`` mechanism, and the
139+
database name or ``$external`` for the ``PLAIN`` mechanism.
140+
141+
* - **compressors**
142+
- A comma-separated list of strings
143+
- None
144+
- Specifies data compressors that the {+php-library+} uses to reduce the
145+
amount of network data passed between MongoDB and your application in
146+
the specified order.
147+
148+
* - **connectTimeoutMS**
149+
- Non-negative integer
150+
- ``10000`` (10 seconds)
151+
- Specifies the connection timeout, in milliseconds, passed to each
152+
underlying TCP stream when attempting to connect to the server.
153+
154+
* - **directConnection**
155+
- Boolean
156+
- ``false``
157+
- Specifies whether to directly connect to a single host instead of
158+
discovering and connecting to all servers in the cluster.
159+
160+
* - **heartbeatFrequencyMS**
161+
- Integer greater than or equal to ``500``
162+
- ``10000`` (10 seconds)
163+
- Specifies the time in milliseconds that each monitoring thread
164+
waits between performing server checks.
165+
166+
* - **journal**
167+
- Boolean
168+
- ``false``
169+
- Requests acknowledgment that the operation propagated to the on-disk
170+
journal.
171+
172+
* - **localThresholdMS**
173+
- Non-negative integer
174+
- ``15``
175+
- | Specifies the time in milliseconds that the average round-trip time
176+
between the driver and server can last compared to the shortest
177+
round-trip time of all the suitable servers.
178+
| A value of ``0`` indicates no latency window, so only the server with
179+
the lowest average round-trip time is eligible.
180+
181+
* - **maxIdleTimeMS**
182+
- Non-negative integer
183+
- ``0``
184+
- | Specifies the time in milliseconds that a connection can remain idle
185+
in a connection pool before the server closes it.
186+
| A value of ``0`` indicates that the client does not close idle
187+
connections.
188+
189+
* - **maxStalenessSeconds**
190+
- ``-1``, or any integer greater than or equal to ``90``
191+
- ``-1``
192+
- | Specifies the maximum lag, in seconds, behind the primary node
193+
that a secondary node can be considered for the given operation.
194+
| This option's value must be at least ``90``, or the operation raises
195+
an error. A value of ``-1`` means there is no maximum lag.
196+
197+
* - **maxPoolSize**
198+
- Non-negative integer
199+
- ``10``
200+
- | Specifies the maximum number of connections that the {+php-library+}
201+
can create in a connection pool for a given server.
202+
| If you attempt an operation while the value of ``maxPoolSize``
203+
connections are checked out, the operation waits until an
204+
in-progress operation finishes and the connection returns to the pool.
205+
206+
* - **minPoolSize**
207+
- Non-negative integer
208+
- ``0``
209+
- | Specifies the minimum number of connections available in a server's
210+
connection pool at a given time.
211+
| If fewer than ``minPoolSize`` connections are in the pool,
212+
the server adds connections in the background up to the value of ``minPoolSize``.
213+
214+
* - **readConcernLevel**
215+
- String
216+
- None
217+
- Specifies the default read concern for operations performed by the
218+
{+php-library+}.
219+
To learn more, see :manual:`Read Concern </reference/read-concern/>` in the {+server-docs-name+}.
220+
221+
* - **readPreference**
222+
- String
223+
- ``primary``
224+
- Specifies how the {+php-library+} routes a read operation to replica set
225+
members.
226+
To learn more, see :manual:`Read Preference </core/read-preference>` in the {+server-docs-name+}.
227+
228+
* - **readPreferenceTags**
229+
- A list of comma-separated key-value pairs
230+
- None
231+
- Specifies which replica set members are considered for operations. Each
232+
instance of this key is a separate tag set. The driver checks each tag
233+
set until it finds one or more servers with each tag.
234+
235+
* - **replicaSet**
236+
- String
237+
- None
238+
- Specifies the name of the replica set the {+php-library+} connects to.
239+
240+
* - **retryReads**
241+
- Boolean
242+
- ``true``
243+
- Specifies whether the {+php-library+} retries a read operation if the operation fails.
244+
245+
* - **serverSelectionTimeoutMS**
246+
- Non-negative integer
247+
- ``30000`` (30 seconds)
248+
- Specifies the time in milliseconds that {+php-library+} waits to
249+
select a server for an operation before timing out.
250+
251+
* - **tls**
252+
- Boolean
253+
- ``false``
254+
- | Specifies the TLS configuration for the {+php-library+} to use in its
255+
connections with the server.
256+
| By default, TLS is off.
257+
258+
* - **tlsAllowInvalidCertificates**
259+
- Boolean
260+
- ``false``
261+
- | Specifies whether the {+php-library+} returns an error if the server
262+
presents an invalid certificate.
263+
| We recommend setting this option to ``true`` only in testing
264+
environments to avoid creating security vulnerabilities in your
265+
application.
266+
267+
* - **tlsCAFile**
268+
- String
269+
- See description
270+
- | Specifies the path to the certificate authority (CA) file that
271+
the {+php-library+} uses for TLS.
272+
| If you do not specify this option, the driver uses the Mozilla
273+
root certificates from the ``webpki-roots`` crate.
274+
275+
* - **tlsCertificateKeyFile**
276+
- String
277+
- None
278+
- | Specifies the path to the certificate file that {+php-library+}
279+
presents to the server to verify its identity.
280+
| If you do not set this option, the {+php-library+} does not
281+
attempt to verify its identity with the server.
282+
283+
* - **tlsInsecure**
284+
- Boolean
285+
- ``false``
286+
- | Specifies whether the {+php-library+} returns an error if the server
287+
presents an invalid certificate.
288+
| We recommend setting this option to ``true`` only in testing
289+
environments to avoid creating security vulnerabilities in your
290+
application.
291+
292+
* - **w**
293+
- Non-negative integer or string
294+
- None
295+
- | Requests acknowledgment that the operation has propagated to a
296+
specific number or variety of servers.
297+
| To learn more, see :manual:`Write Concern </reference/write-concern>`
298+
in the Server manual.
299+
300+
* - **wTimeoutMS**
301+
- Non-negative integer
302+
- No timeout
303+
- Specifies a time limit, in milliseconds, of the write concern.
304+
If an operation has not propagated to the requested level within the
305+
time limit, the {+php-library+} raises an error.
306+
307+
* - **zlibCompressionLevel**
308+
- Integer between ``-1`` and ``9`` (inclusive)
309+
- ``-1``
310+
- | Specifies the level field of the ``zlib`` compression if you use that compressor.
311+
| Setting a value of ``-1`` selects the default compression level (``6``).
312+
| Setting a value of ``0`` specifies no compression, and setting
313+
a value of ``9`` specifies maximum compression.
314+
315+
To see a full list of connection options, see the :manual:`Connection String Options
316+
</reference/connection-string/#connection-string-options>` section of the
317+
Connection Strings guide in the {+server-docs-name+}. Select ``PHP`` from the
318+
:guilabel:`Select your language` dropdown menu on the right side of the page.
319+
320+
.. _laravel-driver-options:
321+
322+
Driver Connection Options
323+
-------------------------
324+
325+
Driver options modify the behavior of the {+php-library+}, which manages
326+
connections and all operations between a Laravel application and MongoDB.
327+
328+
You can specify driver options in your Laravel web application's
329+
``config/database.php`` configuration file. To add driver options,
330+
add the setting and value as an array item in the ``driverOptions`` array
331+
item, as shown in the following example:
332+
333+
.. code-block:: php
334+
:emphasize-lines: 6-9
335+
336+
'connections' => [
337+
'mongodb' => [
338+
'dsn' => 'mongodb+srv://mongodb0.example.com/',
339+
'driver' => 'mongodb',
340+
'database' => 'sample_mflix',
341+
'driverOptions' => [
342+
'serverApi' => 1,
343+
'allow_invalid_hostname' => false,
344+
],
345+
],
346+
]
347+
348+
See the `$driverOptions: array <https://www.mongodb.com/docs/php-library/current/reference/method/MongoDBClient__construct/#parameters>`__
349+
section of the {+php-library+} documentation for a list of driver options.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /