Skip to content

Commit 24fcb11

Browse files
norareidynorareidy
committed
Merge remote-tracking branch 'upstream/php-standardization' into DOCSP-41980-cursor
2 parents f8fa613 + e5973db commit 24fcb11

40 files changed

+2923
-2
lines changed

‎snooty.toml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ php-library = "MongoDB PHP Library"
2525

2626
[constants]
2727
php-library = "MongoDB PHP Library"
28+
driver-short = "PHP library"
29+
stable-api = "Stable API"
2830
mdb-server = "MongoDB Server"
2931
api = "https://www.mongodb.com/docs/php-library/current/reference"
3032
php-manual = "https://www.php.net/manual/en"

‎source/connect/client.txt

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
.. _php-client:
2+
3+
=======================
4+
Create a MongoDB Client
5+
=======================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, Atlas, settings
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
To connect to a MongoDB deployment, you must create the following items:
24+
25+
- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+}
26+
which MongoDB deployment to connect to.
27+
- **MongoDB\\Client** object, which creates the connection to the MongoDB deployment
28+
and lets you perform operations on it.
29+
30+
You can also set options within either or both of these components to
31+
customize the way that the {+driver-short+} behaves
32+
while connected to MongoDB.
33+
34+
This guide describes the components of a connection string and shows how to
35+
use a ``MongoDB\Client`` object to connect to a MongoDB deployment.
36+
37+
.. _php-connection-uri:
38+
39+
Connection URI
40+
--------------
41+
42+
A standard connection string includes the following components:
43+
44+
.. list-table::
45+
:widths: 20 80
46+
:header-rows: 1
47+
48+
* - Component
49+
- Description
50+
51+
* - ``mongodb://``
52+
53+
- Required. A prefix that identifies this as a string in the
54+
standard connection format.
55+
56+
* - ``db_username:db_password``
57+
58+
- Optional. Authentication credentials. If you include these, the client
59+
authenticates the user against the database specified in ``authSource``.
60+
For more information about the ``authSource`` connection option, see
61+
:ref:`php-auth`.
62+
63+
* - ``host[:port]``
64+
65+
- Required. The host and optional port number where MongoDB is running. If you don't
66+
include the port number, the driver uses the default port, ``27017``.
67+
68+
* - ``/defaultauthdb``
69+
70+
- Optional. The authentication database to use if the
71+
connection string includes ``db_username:db_password@``
72+
authentication credentials but not the ``authSource`` option. If you don't include
73+
this component, the client authenticates the user against the ``admin`` database.
74+
75+
* - ``?<options>``
76+
77+
- Optional. A query string that specifies connection-specific
78+
options as ``<name>=<value>`` pairs. See
79+
:ref:`php-connection-options` for a full description of
80+
these options.
81+
82+
To learn more about connection strings, see
83+
:manual:`Connection Strings </reference/connection-string>` in the
84+
Server manual.
85+
86+
Create a MongoDB\Client
87+
-----------------------
88+
89+
To create a connection to MongoDB, pass your connection string when constructing
90+
an instance of the ``MongoDB\Client`` class.
91+
92+
In the following example, the library uses a sample connection URI to connect to a MongoDB
93+
deployment on port ``27017`` of ``localhost``:
94+
95+
.. literalinclude:: /includes/connect/client.php
96+
:language: php
97+
:copyable: true
98+
99+
API Documentation
100+
-----------------
101+
102+
To learn more about creating a ``MongoDB\Client`` object in the {+driver-short+},
103+
see the following API documentation:
104+
105+
- :ref:`MongoDB\Client <php-api-mongodbclient>`

‎source/connect/connection-targets.txt

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. _php-connection-targets:
2+
3+
==========================
4+
Choose a Connection Target
5+
==========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings, client, stable api
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 how to use a connection string and ``MongoDB\Client`` object
24+
to connect to different types of MongoDB deployments.
25+
26+
.. _php-connection-atlas:
27+
28+
Atlas
29+
-----
30+
31+
To connect to a MongoDB deployment on Atlas, include the following elements
32+
in your connection string:
33+
34+
- URI of your Atlas cluster
35+
- Database username
36+
- Database user's password
37+
38+
Then, pass your connection string to the ``MongoDB\Client`` constructor.
39+
40+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
41+
breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
42+
To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page
43+
<php-stable-api>`.
44+
45+
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster.
46+
The code also uses the ``serverApi`` option to specify a {+stable-api+} version.
47+
48+
.. literalinclude:: /includes/connect/atlas.php
49+
:copyable: true
50+
:language: php
51+
52+
.. tip::
53+
54+
Follow the :ref:`php-connection-string` step of the Quick Start
55+
to retrieve your connection string.
56+
57+
.. _php-connection-local:
58+
59+
Local Deployments
60+
-----------------
61+
62+
To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
63+
default, the ``mongod`` process runs on port 27017, though you can customize this for
64+
your deployment.
65+
66+
The following code shows how to use the {+driver-short+} to connect to a local MongoDB
67+
deployment:
68+
69+
.. literalinclude:: /includes/connect/client.php
70+
:language: php
71+
:copyable: true
72+
73+
.. _php-connection-replica-set:
74+
75+
Replica Sets
76+
------------
77+
78+
To connect to a replica set, specify the hostnames (or IP addresses) and
79+
port numbers of the replica set members in your connection string.
80+
81+
If you aren't able to provide a full list of hosts in the replica set, you can
82+
specify one or more of the hosts in the replica set and instruct the {+driver-short+} to
83+
perform automatic discovery to find the others. To instruct the driver to perform
84+
automatic discovery, choose one of the following actions:
85+
86+
- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
87+
- Specify ``false`` as the value of the ``directConnection`` parameter.
88+
- Specify more than one host in the replica set.
89+
90+
In the following example, the driver uses a sample connection URI to connect to the
91+
MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different
92+
hosts, including ``host1``:
93+
94+
.. literalinclude:: /includes/connect/replica-set.php
95+
:language: php
96+
:copyable: true
97+
98+
Initialization
99+
~~~~~~~~~~~~~~
100+
101+
To initialize a replica set, you must connect directly to a single member. To do so,
102+
set the ``directConnection`` connection
103+
option to ``true`` in the connection string. The following code example shows how to
104+
set this connection option:
105+
106+
.. literalinclude:: /includes/connect/direct-connection.php
107+
:language: php
108+
:copyable: true
109+
110+
API Documentation
111+
-----------------
112+
113+
To learn more about using the ``MongoDB\Client`` class,
114+
see the following API documentation:
115+
116+
- :ref:`MongoDB\Client <php-api-mongodbclient>`

0 commit comments

Comments
 (0)