DOCSP-41958 - Connection Targets

snooty.toml

@@ -24,3 +24,6 @@ php-library = "MongoDB PHP Library"
 
 [constants]
 php-library = "MongoDB PHP Library"
+driver-short = "PHP library"
+stable-api = "Stable API"
+mdb-server = "MongoDB Server"

source/connect/connection-targets.txt

@@ -0,0 +1,116 @@
+.. _php-connection-targets:
+
+==========================
+Choose a Connection Target
+==========================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, settings, client, stable api
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use a connection string and ``MongoDB\Client`` object
+to connect to different types of MongoDB deployments.
+
+.. _php-connection-atlas:
+
+Atlas
+-----
+
+To connect to a MongoDB deployment on Atlas, include the following elements
+in your connection string:
+
+- URI of your Atlas cluster
+- MongoDB username
+- MongoDB password
+
+Then, pass your connection string to the ``MongoDB\Client`` constructor.
+
+When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
+breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
+To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page
+<php-stable-api>`.
+
+The following code shows how to use the {+driver-short+} to connect to an Atlas cluster.
+The code also uses the ``serverApi`` option to specify a {+stable-api+} version.
+
+.. literalinclude:: /includes/connect/atlas.php
+   :copyable: true
+   :language: php
+
+.. tip::
+
+   Follow the :atlas:`Atlas driver connection guide </driver-connection>`
+   to retrieve your connection string.
+
+.. _php-connection-local:
+
+Local Deployments
+-----------------
+
+To connect to a local MongoDB deployment, use ``localhost`` as the hostname. By
+default, the ``mongod`` process runs on port 27017, though you can customize this for
+your deployment.
+
+The following code shows how to use the {+driver-short+} to connect to a local MongoDB
+deployment:
+
+.. literalinclude:: /includes/connect/client.php
+   :language: php
+   :copyable: true
+
+.. _php-connection-replica-set:
+
+Replica Sets
+------------
+
+To connect to a replica set, specify the hostnames (or IP addresses) and 
+port numbers of the replica set members in your connection string.
+
+If you aren't able to provide a full list of hosts in the replica set, you can 
+specify one or more of the hosts in the replica set and instruct the {+driver-short+} to 
+perform automatic discovery to find the others. To instruct the driver to perform
+automatic discovery, perform one of the following actions:
+
+- Specify the name of the replica set as the value of the ``replicaSet`` parameter.
+- Specify ``false`` as the value of the ``directConnection`` parameter.
+- Specify more than one host in the replica set.
+
+In the following example, the driver uses a sample connection URI to connect to the 
+MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different
+hosts, including ``host1``:
+
+.. literalinclude:: /includes/connect/replica-set.php
+   :language: php
+   :copyable: true
+
+Initialization
+~~~~~~~~~~~~~~
+
+To initialize a replica set, you must connect directly to a single member. To do so,
+set the ``directConnection`` connection
+option to ``true`` in the connection string. The following code example shows how to
+set this connection option: 
+
+.. literalinclude:: /includes/connect/direct-connection.php
+   :language: php
+   :copyable: true
+
+API Documentation
+-----------------
+
+To learn more about using the ``MongoDB\Client`` class,
+see the following API documentation:
+
+- :ref:`MongoDB\Client <php-api-mongodbclient>`

source/includes/connect/atlas.php

@@ -0,0 +1,25 @@
+<?php
+
+try {
+    // Replace the placeholder with your Atlas connection string
+    $uri = "<connection string>";
+
+    // Create a MongoDB client with server API options
+    $client = new MongoDB\Client($uri, [], [
+        'serverApi' => [
+            'version' => '1'
+        ]
+    ]);
+
+    // Ping the server to verify that the connection works
+    $admin = $client->admin;
+    $command = new MongoDB\Driver\Command(['ping' => 1]);
+    $result = $admin->command($command)->toArray();
+
+    echo json_encode($result), "\n";
+    echo "Pinged your deployment. You successfully connected to MongoDB!\n";
+} catch (Exception $e) {
+    echo "An exception occurred: ", $e->getMessage(), "\n";
+    exit(EXIT_FAILURE);
+}
+?>

source/includes/connect/direct-connection.php

@@ -0,0 +1,7 @@
+<?php
+
+// Replace the placeholders with your actual hostname and port
+$uri = "mongodb://<hostname>:<port>/?directConnection=true";
+
+// Create a MongoDB client
+$client = new MongoDB\Client($uri);

source/includes/connect/replica-set.php

@@ -0,0 +1,7 @@
+<?php
+
+// Replace the placeholder with your connection string
+$uri = "mongodb://host1:27017/?replicaSet=sampleRS";
+
+// Create a MongoDB client
+$client = new MongoDB\Client($uri);

source/reference/class/MongoDBClient.txt

@@ -1,3 +1,5 @@
+.. _php-api-mongodbclient:
+
 =====================
 MongoDB\\Client Class
 =====================