diff --git a/snooty.toml b/snooty.toml index a77d00d6..8383cbf5 100644 --- a/snooty.toml +++ b/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" diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..1047dc6d --- /dev/null +++ b/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 +`. + +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 ` \ 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..29d219d5 --- /dev/null +++ b/source/includes/connect/atlas.php @@ -0,0 +1,19 @@ +"; + +// 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"; + +?> diff --git a/source/includes/connect/direct-connection.php b/source/includes/connect/direct-connection.php new file mode 100644 index 00000000..fd896b3c --- /dev/null +++ b/source/includes/connect/direct-connection.php @@ -0,0 +1,7 @@ +:/?directConnection=true"; + +// Create a MongoDB client +$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 new file mode 100644 index 00000000..6086d425 --- /dev/null +++ b/source/includes/connect/replica-set.php @@ -0,0 +1,6 @@ +