DOCSP-41957 - Mongo Client

snooty.toml

@@ -24,3 +24,4 @@ php-library = "MongoDB PHP Library"
 
 [constants]
 php-library = "MongoDB PHP Library"
+driver-short = "PHP library"

source/connect/client.txt

@@ -0,0 +1,110 @@
+.. _php-client:
+
+=======================
+Create a MongoDB Client
+=======================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: connection string, URI, server, Atlas, settings
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+To connect to a MongoDB deployment, you must create the following items:
+
+- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+}
+  which MongoDB deployment to connect to.
+- **MongoDB\\Client** object, which creates the connection to the MongoDB deployment
+  and lets you perform operations on it.
+
+You can also set options within either or both of these components to
+customize the way that the {+driver-short+} behaves
+while connected to MongoDB.
+
+This guide describes the components of a connection string and shows how to
+ use a ``MongoDB\Client`` object to connect to a MongoDB deployment.
+
+.. _php-connection-uri:
+
+Connection URI
+--------------
+
+A standard connection string includes the following components:
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Component
+     - Description
+
+   * - ``mongodb://``
+
+     - Required. A prefix that identifies this as a string in the
+       standard connection format.
+
+   * - ``db_username:db_password``
+
+     - Optional. Authentication credentials. If you include these, the client
+       authenticates the user against the database specified in ``authSource``.
+       For more information about the ``authSource`` connection option, see
+       :ref:`php-auth`. 
+
+   * - ``host[:port]``
+
+     - Required. The host and optional port number where MongoDB is running. If you don't
+       include the port number, the driver uses the default port, ``27017``.
+
+   * - ``/defaultauthdb``
+
+     - Optional. The authentication database to use if the
+       connection string includes ``db_username:db_password@``
+       authentication credentials but not the ``authSource`` option. If you don't include 
+       this component, the client authenticates the user against the ``admin`` database.
+
+   * - ``?<options>``
+
+     - Optional. A query string that specifies connection-specific
+       options as ``<name>=<value>`` pairs. See
+       :ref:`php-connection-options` for a full description of
+       these options.
+
+To learn more about connection strings, see
+:manual:`Connection Strings </reference/connection-string>` in the
+Server manual.
+
+Create a MongoDB\Client
+-----------------------
+
+To create a connection to MongoDB, pass your connection string when constructing
+an instance of the ``MongoDB\Client`` class.
+
+In the following example, the library uses a sample connection URI to connect to a MongoDB 
+deployment on port ``27017`` of ``localhost``:
+
+.. literalinclude:: /includes/connect/client.php
+   :language: php
+   :copyable: true
+
+.. tip:: Reuse Your Client
+
+   Because each ``MongoDB\Client`` object represents a pool of connections to the
+   database, you can use a single instance of the class across multiple requests.
+
+API Documentation
+-----------------
+
+To learn more about creating a ``MongoDB\Client`` object in the {+driver-short+},
+see the following API documentation:
+
+- :ref:`MongoDB\Client <php-api-mongodbclient>`

source/includes/connect/client.php

@@ -0,0 +1,3 @@
+<?php
+
+$client = new MongoDB\Client("mongodb://localhost:27017");

source/reference/class/MongoDBClient.txt

@@ -1,3 +1,5 @@
+.. _php-api-mongodbclient:
+
 =====================
 MongoDB\\Client Class
 =====================
@@ -62,4 +64,4 @@ Methods
 - :phpmethod:`MongoDB\Client::selectCollection()`
 - :phpmethod:`MongoDB\Client::selectDatabase()`
 - :phpmethod:`MongoDB\Client::startSession()`
-- :phpmethod:`MongoDB\Client::watch()`
+- :phpmethod:`MongoDB\Client::watch()`