diff --git a/snooty.toml b/snooty.toml index c97fe021..28b89f14 100644 --- a/snooty.toml +++ b/snooty.toml @@ -25,5 +25,6 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" +driver-short = "PHP library" mdb-server = "MongoDB Server" -api = "https://www.mongodb.com/docs/php-library/current/reference" +api = "https://www.mongodb.com/docs/php-library/current/reference" \ No newline at end of file diff --git a/source/connect/client.txt b/source/connect/client.txt new file mode 100644 index 00000000..421f6fa2 --- /dev/null +++ b/source/connect/client.txt @@ -0,0 +1,105 @@ +.. _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. + + * - ``?`` + + - Optional. A query string that specifies connection-specific + options as ``=`` pairs. See + :ref:`php-connection-options` for a full description of + these options. + +To learn more about connection strings, see +:manual:`Connection Strings ` 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 + +API Documentation +----------------- + +To learn more about creating a ``MongoDB\Client`` object in the {+driver-short+}, +see the following API documentation: + +- :ref:`MongoDB\Client ` \ No newline at end of file diff --git a/source/includes/connect/client.php b/source/includes/connect/client.php new file mode 100644 index 00000000..48d40f4e --- /dev/null +++ b/source/includes/connect/client.php @@ -0,0 +1,3 @@ +