From 5bec0259aeb9e7b089cea0228e1997976ea7bec4 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 15 Aug 2024 12:35:35 -0500 Subject: [PATCH 1/8] first draft --- snooty.toml | 1 + source/connect/client.txt | 110 +++++++++++++++++++++++++++++ source/includes/connect/client.php | 3 + 3 files changed, 114 insertions(+) create mode 100644 source/connect/client.txt create mode 100644 source/includes/connect/client.php diff --git a/snooty.toml b/snooty.toml index a08a8d41..549d0cfc 100644 --- a/snooty.toml +++ b/snooty.toml @@ -24,3 +24,4 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" +driver-short = "PHP library" diff --git a/source/connect/client.txt b/source/connect/client.txt new file mode 100644 index 00000000..ce0911a2 --- /dev/null +++ b/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 need two things: + +- A **connection URI**, also known as a *connection string*, which tells the {+driver-short+} + which MongoDB deployment to connect to. +- A **MongoDB\Client** object, which creates the connection to the MongoDB deployment + and lets you perform operations on it. + +You can also use either of these components to customize the way the {+driver-short+} behaves +while connected to MongoDB. + +This guide shows you how to create a connection string and use a ``MongoDB\Client`` object +to connect to MongoDB. + +.. _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. + + * - ``username: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 ``username: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. + +For more information about creating a connection string, see +:manual:`Connection Strings ` in the +MongoDB Server documentation. + +Create a ``MongoDB\Client`` +--------------------------- + +To create a connection to MongoDB, construct an instance of the ``MongoDB\Client`` class, +passing the connection URI as a string to the constructor. + +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, most applications require only a single instance of + ``MongoDB\Client``, even 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 `__ \ 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..02144279 --- /dev/null +++ b/source/includes/connect/client.php @@ -0,0 +1,3 @@ + Date: Thu, 15 Aug 2024 13:37:29 -0500 Subject: [PATCH 2/8] fixes --- source/connect/client.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connect/client.txt b/source/connect/client.txt index ce0911a2..21f7ab9c 100644 --- a/source/connect/client.txt +++ b/source/connect/client.txt @@ -24,7 +24,7 @@ To connect to a MongoDB deployment, you need two things: - A **connection URI**, also known as a *connection string*, which tells the {+driver-short+} which MongoDB deployment to connect to. -- A **MongoDB\Client** object, which creates the connection to the MongoDB deployment +- A **MongoDB\\Client** object, which creates the connection to the MongoDB deployment and lets you perform operations on it. You can also use either of these components to customize the way the {+driver-short+} behaves @@ -107,4 +107,4 @@ 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 +- :ref:`MongoDB\Client ` \ No newline at end of file From d5e4422ea6bdfccfb7d4c70219a5d636a0d6d2a5 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 16 Aug 2024 09:46:21 -0500 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> --- source/connect/client.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/connect/client.txt b/source/connect/client.txt index 21f7ab9c..c4de0c0e 100644 --- a/source/connect/client.txt +++ b/source/connect/client.txt @@ -20,11 +20,11 @@ Create a MongoDB Client Overview -------- -To connect to a MongoDB deployment, you need two things: +To connect to a MongoDB deployment, you must create the following items: -- A **connection URI**, also known as a *connection string*, which tells the {+driver-short+} +- **Connection URI**, also known as a *connection string*, which tells the {+driver-short+} which MongoDB deployment to connect to. -- A **MongoDB\\Client** object, which creates the connection to the MongoDB deployment +- **MongoDB\\Client** object, which creates the connection to the MongoDB deployment and lets you perform operations on it. You can also use either of these components to customize the way the {+driver-short+} behaves @@ -78,15 +78,15 @@ A standard connection string includes the following components: :ref:`php-connection-options` for a full description of these options. -For more information about creating a connection string, see +To learn more about connection strings, see :manual:`Connection Strings ` in the MongoDB Server documentation. Create a ``MongoDB\Client`` --------------------------- -To create a connection to MongoDB, construct an instance of the ``MongoDB\Client`` class, -passing the connection URI as a string to the constructor. +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``: From e02bfd7f0bf5d2e63877904bdf479dba9f9e50b2 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 16 Aug 2024 11:46:49 -0500 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> --- source/connect/client.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/connect/client.txt b/source/connect/client.txt index c4de0c0e..76b62b1e 100644 --- a/source/connect/client.txt +++ b/source/connect/client.txt @@ -27,7 +27,8 @@ To connect to a MongoDB deployment, you must create the following items: - **MongoDB\\Client** object, which creates the connection to the MongoDB deployment and lets you perform operations on it. -You can also use either of these components to customize the way the {+driver-short+} behaves +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 shows you how to create a connection string and use a ``MongoDB\Client`` object @@ -80,13 +81,13 @@ A standard connection string includes the following components: To learn more about connection strings, see :manual:`Connection Strings ` in the -MongoDB Server documentation. +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. +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``: From 60bac62a3c2012304550f3de32c0e81433115bb2 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 16 Aug 2024 11:57:36 -0500 Subject: [PATCH 5/8] feedback --- source/connect/client.txt | 11 +++++------ source/reference/class/MongoDBClient.txt | 4 +++- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/source/connect/client.txt b/source/connect/client.txt index 76b62b1e..d968bb2e 100644 --- a/source/connect/client.txt +++ b/source/connect/client.txt @@ -53,7 +53,7 @@ A standard connection string includes the following components: - Required. A prefix that identifies this as a string in the standard connection format. - * - ``username:password`` + * - ``db_username:db_password`` - Optional. Authentication credentials. If you include these, the client authenticates the user against the database specified in ``authSource``. @@ -68,7 +68,7 @@ A standard connection string includes the following components: * - ``/defaultauthdb`` - Optional. The authentication database to use if the - connection string includes ``username:password@`` + 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. @@ -83,8 +83,8 @@ To learn more about connection strings, see :manual:`Connection Strings ` in the Server manual. -Create a ``MongoDB\Client`` ---------------------------- +Create a MongoDB\Client +----------------------- To create a connection to MongoDB, pass your connection string when constructing an instance of the ``MongoDB\Client`` class. @@ -99,8 +99,7 @@ deployment on port ``27017`` of ``localhost``: .. tip:: Reuse Your Client Because each ``MongoDB\Client`` object represents a pool of connections to the - database, most applications require only a single instance of - ``MongoDB\Client``, even across multiple requests. + database, you can use a single instance of the class across multiple requests. API Documentation ----------------- diff --git a/source/reference/class/MongoDBClient.txt b/source/reference/class/MongoDBClient.txt index d5145c65..c7c74f33 100644 --- a/source/reference/class/MongoDBClient.txt +++ b/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()` \ No newline at end of file From a1597a8faf9fc9a8283cb4dfb560d91693047eb0 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 16 Aug 2024 13:18:30 -0500 Subject: [PATCH 6/8] Apply suggestions from code review Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> --- source/connect/client.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connect/client.txt b/source/connect/client.txt index d968bb2e..6e87e1e2 100644 --- a/source/connect/client.txt +++ b/source/connect/client.txt @@ -31,8 +31,8 @@ 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 shows you how to create a connection string and use a ``MongoDB\Client`` object -to connect 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: From 8ba01bfa9f7f5996de18641c6669692069856b43 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Tue, 27 Aug 2024 15:28:35 -0500 Subject: [PATCH 7/8] feedback --- source/connect/client.txt | 5 ----- source/includes/connect/client.php | 2 +- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/source/connect/client.txt b/source/connect/client.txt index 6e87e1e2..786fb4ac 100644 --- a/source/connect/client.txt +++ b/source/connect/client.txt @@ -96,11 +96,6 @@ deployment on port ``27017`` of ``localhost``: :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 ----------------- diff --git a/source/includes/connect/client.php b/source/includes/connect/client.php index 02144279..48d40f4e 100644 --- a/source/includes/connect/client.php +++ b/source/includes/connect/client.php @@ -1,3 +1,3 @@ Date: Tue, 27 Aug 2024 15:30:39 -0500 Subject: [PATCH 8/8] space --- source/connect/client.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/client.txt b/source/connect/client.txt index 786fb4ac..421f6fa2 100644 --- a/source/connect/client.txt +++ b/source/connect/client.txt @@ -32,7 +32,7 @@ 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. +use a ``MongoDB\Client`` object to connect to a MongoDB deployment. .. _php-connection-uri: