DOCSP-41958 - Connection Targets (#107)

Co-authored-by: Nora Reidy <nora.reidy@mongodb.com>
Co-authored-by: Andreas Braun <git@alcaeus.org>

Author: 3 people

snooty.toml

@@ -27,5 +27,6 @@ php-library = "MongoDB PHP Library"
 
 php-library = "MongoDB PHP Library"
 driver-short = "PHP library"
+stable-api = "Stable API"
 mdb-server = "MongoDB Server"
 api = "https://www.mongodb.com/docs/php-library/current/reference"

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
+- Database username
+- Database user's 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 :ref:`php-connection-string` step of the Quick Start
+   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, choose 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,19 @@
+<?php
+
+// 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' => new MongoDB\Driver\ServerApi('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";
+
+?>

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,6 @@
+<?php
+
+$uri = "mongodb://host1:27017/?replicaSet=sampleRS";
+
+// Create a MongoDB client
+$client = new MongoDB\Client($uri);