From 4bc98569e871b21beda8ad4e35a5d5a79a774a98 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 19 Aug 2024 10:43:29 -0500 Subject: [PATCH 1/8] first draft --- snooty.toml | 3 + source/connect/connection-targets.txt | 117 ++++++++++++++++++ source/includes/connect/atlas.php | 29 +++++ source/includes/connect/direct-connection.php | 7 ++ source/includes/connect/replica-set.php | 7 ++ source/reference/class/MongoDBClient.txt | 2 + 6 files changed, 165 insertions(+) create mode 100644 source/connect/connection-targets.txt create mode 100644 source/includes/connect/atlas.php create mode 100644 source/includes/connect/direct-connection.php create mode 100644 source/includes/connect/replica-set.php diff --git a/snooty.toml b/snooty.toml index a08a8d41..e873e4b9 100644 --- a/snooty.toml +++ b/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" diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..09bb0717 --- /dev/null +++ b/source/connect/connection-targets.txt @@ -0,0 +1,117 @@ +.. _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 +`. + +The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. + +The code also uses the ``server_api_opts`` option to specify a {+stable-api+} version. + +.. literalinclude:: /includes/connect/atlas.php + :copyable: true + :language: php + +.. tip:: + + Follow the :atlas:`Atlas driver connection guide ` + 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 ` \ No newline at end of file diff --git a/source/includes/connect/atlas.php b/source/includes/connect/atlas.php new file mode 100644 index 00000000..809a0978 --- /dev/null +++ b/source/includes/connect/atlas.php @@ -0,0 +1,29 @@ +"; + + // Create a MongoDB client with server API options + $client = new 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); +} +?> \ No newline at end of file diff --git a/source/includes/connect/direct-connection.php b/source/includes/connect/direct-connection.php new file mode 100644 index 00000000..7770946f --- /dev/null +++ b/source/includes/connect/direct-connection.php @@ -0,0 +1,7 @@ +:/?directConnection=true"; + +// Create a MongoDB client +$client = new Client($uri); \ No newline at end of file diff --git a/source/includes/connect/replica-set.php b/source/includes/connect/replica-set.php new file mode 100644 index 00000000..3b3a921d --- /dev/null +++ b/source/includes/connect/replica-set.php @@ -0,0 +1,7 @@ + Date: Mon, 19 Aug 2024 10:53:08 -0500 Subject: [PATCH 2/8] fixes --- source/connect/connection-targets.txt | 4 ++-- source/includes/connect/atlas.php | 4 ---- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 09bb0717..3464e2a8 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -68,8 +68,8 @@ The following code shows how to use the {+driver-short+} to connect to a local M deployment: .. literalinclude:: /includes/connect/client.php - :language: php - :copyable: true + :language: php + :copyable: true .. _php-connection-replica-set: diff --git a/source/includes/connect/atlas.php b/source/includes/connect/atlas.php index 809a0978..b849913e 100644 --- a/source/includes/connect/atlas.php +++ b/source/includes/connect/atlas.php @@ -1,8 +1,4 @@ Date: Mon, 19 Aug 2024 10:55:07 -0500 Subject: [PATCH 3/8] fixes --- source/connect/connection-targets.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 3464e2a8..9f2bc7df 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -43,8 +43,7 @@ To learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} pag `. The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. - -The code also uses the ``server_api_opts`` option to specify a {+stable-api+} version. +The code also uses the ``serverApi`` option to specify a {+stable-api+} version. .. literalinclude:: /includes/connect/atlas.php :copyable: true From 4ef5647a886d8c87241b525e63d88aecaedd5808 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 19 Aug 2024 11:01:45 -0500 Subject: [PATCH 4/8] qualify type names --- source/includes/connect/atlas.php | 2 +- source/includes/connect/direct-connection.php | 2 +- source/includes/connect/replica-set.php | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/connect/atlas.php b/source/includes/connect/atlas.php index b849913e..4d0991cf 100644 --- a/source/includes/connect/atlas.php +++ b/source/includes/connect/atlas.php @@ -5,7 +5,7 @@ $uri = ""; // Create a MongoDB client with server API options - $client = new Client($uri, [], [ + $client = new MongoDB\Client($uri, [], [ 'serverApi' => [ 'version' => '1' ] diff --git a/source/includes/connect/direct-connection.php b/source/includes/connect/direct-connection.php index 7770946f..fd896b3c 100644 --- a/source/includes/connect/direct-connection.php +++ b/source/includes/connect/direct-connection.php @@ -4,4 +4,4 @@ $uri = "mongodb://:/?directConnection=true"; // Create a MongoDB client -$client = new Client($uri); \ No newline at end of file +$client = new MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/replica-set.php b/source/includes/connect/replica-set.php index 3b3a921d..d517f0e7 100644 --- a/source/includes/connect/replica-set.php +++ b/source/includes/connect/replica-set.php @@ -4,4 +4,4 @@ $uri = "mongodb://host1:27017/?replicaSet=sampleRS"; // Create a MongoDB client -$client = new Client($uri); \ No newline at end of file +$client = new MongoDB\Client($uri); \ No newline at end of file From 3b15c2653054ee89a42d9894d470d42cf7427d75 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 19 Aug 2024 12:14:33 -0500 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Nora Reidy --- source/connect/connection-targets.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 9f2bc7df..1047dc6d 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -32,8 +32,8 @@ 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 +- Database username +- Database user's password Then, pass your connection string to the ``MongoDB\Client`` constructor. @@ -51,7 +51,7 @@ The code also uses the ``serverApi`` option to specify a {+stable-api+} version. .. tip:: - Follow the :atlas:`Atlas driver connection guide ` + Follow the :ref:`php-connection-string` step of the Quick Start to retrieve your connection string. .. _php-connection-local: @@ -81,7 +81,7 @@ 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: +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. From 6c9011aa02e23395537aa5f6d14cfc6414394ae1 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 19 Aug 2024 12:15:17 -0500 Subject: [PATCH 6/8] nr feedback --- source/includes/connect/replica-set.php | 1 - 1 file changed, 1 deletion(-) diff --git a/source/includes/connect/replica-set.php b/source/includes/connect/replica-set.php index d517f0e7..6086d425 100644 --- a/source/includes/connect/replica-set.php +++ b/source/includes/connect/replica-set.php @@ -1,6 +1,5 @@ Date: Wed, 28 Aug 2024 11:18:22 -0500 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Andreas Braun --- source/includes/connect/atlas.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/source/includes/connect/atlas.php b/source/includes/connect/atlas.php index 4d0991cf..a80ea8cc 100644 --- a/source/includes/connect/atlas.php +++ b/source/includes/connect/atlas.php @@ -6,9 +6,7 @@ // Create a MongoDB client with server API options $client = new MongoDB\Client($uri, [], [ - 'serverApi' => [ - 'version' => '1' - ] + 'serverApi' => new MongoDB\Driver\ServerApi('1') ]); // Ping the server to verify that the connection works From e19330cd26dbf2b1a0485ad2a266293c929781a1 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 28 Aug 2024 11:39:08 -0500 Subject: [PATCH 8/8] feedback --- source/includes/connect/atlas.php | 32 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/source/includes/connect/atlas.php b/source/includes/connect/atlas.php index a80ea8cc..29d219d5 100644 --- a/source/includes/connect/atlas.php +++ b/source/includes/connect/atlas.php @@ -1,23 +1,19 @@ "; +// Replace the placeholder with your Atlas connection string +$uri = ""; - // Create a MongoDB client with server API options - $client = new MongoDB\Client($uri, [], [ - 'serverApi' => new MongoDB\Driver\ServerApi('1') - ]); +// 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(); +// 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); -} -?> \ No newline at end of file +echo json_encode($result), "\n"; +echo "Pinged your deployment. You successfully connected to MongoDB!\n"; + +?>