From 945bfacb7c92db65a3bac96dec0e118628f57966 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 16:24:52 -0400 Subject: [PATCH 01/11] DOCSP-43204: Connection landing page --- source/connect.txt | 426 ++++++++++++++++++ .../usage-examples/connect-code-examples.php | 204 +++++++++ .../usage-examples/connect-sample-app.php | 19 + source/index.txt | 1 + 4 files changed, 650 insertions(+) create mode 100644 source/connect.txt create mode 100644 source/includes/usage-examples/connect-code-examples.php create mode 100644 source/includes/usage-examples/connect-sample-app.php diff --git a/source/connect.txt b/source/connect.txt new file mode 100644 index 00000000..ced3d882 --- /dev/null +++ b/source/connect.txt @@ -0,0 +1,426 @@ +.. _php-connect: + +================== +Connect to MongoDB +================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use the PHP library to connect to MongoDB. + :keywords: client, ssl + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /connect/client + /connect/connection-targets + /connect/connection-options + /connect/tls + /connect/stable-api + +Overview +-------- + +This page contains code examples that show how to connect your PHP application +to MongoDB with various settings. + +.. tip:: + + To learn more about the connection options on this page, see the link + provided in each section. + +To use a connection example from this page, copy the code example into the +:ref:`sample application ` or your own application. +Make sure to set the ``MONGODB_URI`` environment variable to the +connection string for your MongoDB deployment, and replace the +```` and ```` placeholders with values for your +target namespace. + +.. _php-connect-sample: + +.. include:: /includes/usage-examples/sample-app-intro.rst + +.. literalinclude:: /includes/usage-examples/connect-sample-app.php + :language: php + :copyable: true + :linenos: + :emphasize-lines: 8-10 + +Connection +---------- + +Atlas +~~~~~ + +The following code shows how to connect to a MongoDB Atlas deployment: + +.. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-atlas + :end-before: end-atlas + +To learn more about connecting to an Atlas deployment, see :ref:`php-connection-atlas` +in the Connection Targets guide. + +Local Deployment +~~~~~~~~~~~~~~~~ + +The following code shows how to connect to a local MongoDB deployment: + +.. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-local + :end-before: end-local + +To learn more about connecting to a local deployment, see :ref:`php-connection-local` +in the Connection Targets guide. + +Replica Set +~~~~~~~~~~~ + +The following code shows how to connect to a replica set deployment: + +.. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-replica-set + :end-before: end-replica-set + +To learn more about connecting to a replica set, see :ref:`php-connection-replica-set` +in the Connection Targets guide. + +Transport Layer Security (TLS) +------------------------------ + +Enable TLS +~~~~~~~~~~ + +The following code shows how to enable TLS for the connection to your +MongoDB instance: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-enable-tls-client + :end-before: end-enable-tls-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-enable-tls-uri + :end-before: end-enable-tls-uri + +To learn more about enabling TLS, see :ref:`php-enable-tls` in +the TLS configuration guide. + +Specify a Certificate Authority (CA) File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to specify the path to your CA file +for the connection to your MongoDB instance: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-ca-file-client + :end-before: end-ca-file-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-ca-file-uri + :end-before: end-ca-file-uri + +To learn more about specifying a CA file, see :ref:`php-specify-ca-file` in +the TLS configuration guide. + +Disable OCSP Checks +~~~~~~~~~~~~~~~~~~~ + +The following code shows how to prevent the driver from contacting +the OCSP endpoint: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-disable-ocsp-client + :end-before: end-disable-ocsp-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-disable-ocsp-uri + :end-before: end-disable-ocsp-uri + +To learn more about disabling OCSP checks, see :ref:`php-disable-ocsp` in +the TLS configuration guide. + +Specify a Certificate Revocation List (CRL) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to instruct the driver to verify the server's +certificate against a CRL: + +.. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-crl + :end-before: end-crl + +To learn more about specifying a CRL, see :ref:`php-crl` in the TLS +configuration guide. + +Present a Client Certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to specify the client certificate that +the driver presents to your MongoDB deployment: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-client-cert-client + :end-before: end-client-cert-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-client-cert-uri + :end-before: end-client-cert-uri + +To learn more about specifying a client certificate, see :ref:`php-client-cert` in +the TLS configuration guide. + +Provide a Certificate Key File Password +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to specify the password for your +client certificate: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-key-file-client + :end-before: end-key-file-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-key-file-uri + :end-before: end-key-file-uri + +To learn more about providing a key file password, see :ref:`php-key-file-password` in +the TLS configuration guide. + +Allow Insecure TLS +~~~~~~~~~~~~~~~~~~ + +The following code shows how to disable certificate verification: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-insecure-tls-client + :end-before: end-insecure-tls-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-insecure-tls-uri + :end-before: end-insecure-tls-uri + +To learn more about allowing insecure TLS, see :ref:`php-insecure-tls` in +the TLS configuration guide. + +Disable Certificate Validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to disable certificate validation: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-disable-cert-client + :end-before: end-disable-cert-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-disable-cert-uri + :end-before: end-disable-cert-uri + +To learn more about disabling certificate validation, see :ref:`php-insecure-tls` in +the TLS configuration guide. + +Disable Hostname Verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to disable hostname verification: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-disable-hostname-client + :end-before: end-disable-hostname-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-disable-hostname-uri + :end-before: end-disable-hostname-uri + +To learn more about disabling hostname verification, see :ref:`php-insecure-tls` in +the TLS configuration guide. + +Network Compression +------------------- + +Compression Algorithms +~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to enable compression for the connection +to your MongoDB instance by specifying each compression algorithm: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-compression-all-client + :end-before: end-compression-all-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-compression-all-uri + :end-before: end-compression-all-uri + +To learn more about specifying compression algorithms, see +:ref:`php-enable-compression` in the Network Compression guide. + +zlib Compression Level +~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to specify the ``zlib`` compression algorithm +and set its compression level: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-compression-zlib-client + :end-before: end-compression-zlib-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-compression-zlib-uri + :end-before: end-compression-zlib-uri + +To learn more about setting the zlib compression level, see +:ref:`php-enable-compression` in the Network Compression guide. + +{+stable-api+} +-------------- + +The following code shows how to enable the {+stable-api+} for the +connection to your MongoDB instance: + +.. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-stable-api + :end-before: end-stable-api + +To learn more about the {+stable-api+}, see the :ref:`php-stable-api` guide. + + diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php new file mode 100644 index 00000000..4aabd080 --- /dev/null +++ b/source/includes/usage-examples/connect-code-examples.php @@ -0,0 +1,204 @@ +'; +$client = new Client($uri); +// end-atlas + +// Connects to a replica set +// start-replica-set +$uri = 'mongodb://:/?replicaSet='; +$client = new Client($uri); +// end-replica-set + +// Connects to a MongoDB deployment and enables TLS using client +// options +// start-enable-tls-client +$client = new Client( + 'mongodb://:/', + ['tls' => true], +); +// end-enable-tls-client + +// Connects to a MongoDB deployment and enables TLS using connection URI +// parameters +// start-enable-tls-uri +$uri = 'mongodb://:/?tls=true'; +$client = new Client($uri); +// end-enable-tls-uri + +// Connects to a MongoDB deployment, enables TLS, and specifies the path to +// a CA file using client options +// start-ca-file-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'], +); +// end-ca-file-client + +// Connects to a MongoDB deployment, enables TLS, and specifies the path to +// a CA file using connection URI parameters +// start-ca-file-uri +$uri = 'mongodb://:/?tls=true&tlsCAFile=/path/to/ca.pem'; +$client = new Client($uri); +// end-ca-file-uri + +// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks +// using client options +// start-disable-ocsp-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true], +); +// end-disable-ocsp-client + +// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks +// using connection URI parameters +// start-disable-ocsp-uri +$uri = 'mongodb://:/?tls=true&tlsDisableOCSPEndpointCheck=true'; +$client = new Client($uri); +// end-disable-ocsp-uri + +// Connects to a TLS-enabled deployment and instructs the driver to check the +// server certificate against a CRL +// start-crl +$client = new Client( + 'mongodb://:/', + ['tls' => true], + ['crl_file' => '/path/to/file.pem'], +); +// end-crl + +// Presents a client certificate to prove identity +// using client options +// start-client-cert-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'], +); +// end-client-cert-client + +// Presents a client certificate to prove identity +// using connection URI parameters +// start-client-cert-uri +$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem'; +$client = new Client($uri); +// end-client-cert-uri + +// Specifies the password for a client certificate using client options +// start-key-file-client +$client = new Client( + 'mongodb://:/', + [ + 'tls' => true, + 'tlsCertificateKeyFile' => '/path/to/client.pem', + 'tlsCertificateKeyFilePassword' => '' + ], +); +// end-key-file-client + +// Specifies the password for a client certificate using connection URI parameters +// start-key-file-uri +$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword='; +$client = new Client($uri); +// end-key-file-uri + +// Connects to a TLS-enabled deployment and disables server certificate verification +// using client options +// start-insecure-tls-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'tlsInsecure' => true], +); +// end-insecure-tls-client + +// Connects to a TLS-enabled deployment and disables server certificate verification +// using connection URI parameters +// start-insecure-tls-uri +$uri = 'mongodb://:/?tls=true&tlsInsecure=true'; +$client = new Client($uri); +// end-insecure-tls-uri + +// Disables certificate validation using client options +// start-disable-cert-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'tlsAllowInvalidCertificates' => true], +); +// end-disable-cert-client + +// Disables certificate validation using connection URI parameters +// start-disable-cert-uri +$uri = 'mongodb://:/?tls=true&tlsAllowInvalidCertificates=true'; +$client = new Client($uri); +// end-disable-cert-uri + +// Connects to a TLS-enabled deployment and disables hostname verification +// using client options +// start-disable-hostname-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'tlsAllowInvalidHostnames' => true], +); +// end-disable-hostname-client + +// Connects to a TLS-enabled deployment and disables hostname verification +// using connection URI parameters +// start-disable-hostname-uri +$uri = 'mongodb://:/?tls=true&tlsAllowInvalidHostnames=true'; +$client = new Client($uri); +// end-disable-hostname-uri + +// Enables compression for a MongoDB connection and specifies each compression algorithm +// using client options +// start-compression-all-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'compressors' => 'snappy,zstd,zlib'], +); +// end-compression-all-client + +// Enables compression for a MongoDB connection and specifies each compression algorithm +// using connection URI parameters +// start-compression-all-uri +$uri = 'mongodb://:/?compressors=snappy,zstd,zlib'; +$client = new Client($uri); +// end-compression-all-uri + +// Enables zlib compression for a MongoDB connection using client options +// start-compression-zlib-client +$client = new Client( + 'mongodb://:/', + ['tls' => true, 'compressors' => 'zlib', 'zlibCompressionLevel' => 1], +); +// end-compression-zlib-client + +// Enables zlib compression for a MongoDB connection using connection URI parameters +// start-compression-zlib-uri +$uri = 'mongodb://:/?compressors=zlib&zlibCompressionLevel=1'; +$client = new Client($uri); +// end-compression-zlib-uri + +// Connects to a MongoDB deployment and enables the stable API +// start-stable-api +$uri = ''; +$clientOptions = [ + 'serverApi' => [ + 'version' => '1' + ] +]; +$client = new Client($uri, $clientOptions); +// end-stable-api + +?> \ No newline at end of file diff --git a/source/includes/usage-examples/connect-sample-app.php b/source/includes/usage-examples/connect-sample-app.php new file mode 100644 index 00000000..588b8aaa --- /dev/null +++ b/source/includes/usage-examples/connect-sample-app.php @@ -0,0 +1,19 @@ +admin; +$result = $admin->command(['ping' => 1]); + +if ($result) { + echo 'Successfully pinged the MongoDB server.', PHP_EOL; +} else { + echo 'Ping to MongoDB server failed.', PHP_EOL; +} \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 0a589f6e..419c9efc 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,6 +11,7 @@ MongoDB PHP Library :titlesonly: Get Started + /connect /databases-collections /read /write From fd44093a6aa2d03fd530cc69e62d188568bdf758 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 16:32:51 -0400 Subject: [PATCH 02/11] toc edit --- source/connect.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/connect.txt b/source/connect.txt index ced3d882..cc0ac7f3 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -24,8 +24,10 @@ Connect to MongoDB /connect/client /connect/connection-targets - /connect/connection-options /connect/tls + +.. TODO: + /connect/connection-options /connect/stable-api Overview From e74febe8e11caf68be991f36f1e3ffb374a8673d Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 16:37:52 -0400 Subject: [PATCH 03/11] edits --- source/connect.txt | 22 +++++++++---------- .../usage-examples/connect-code-examples.php | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index cc0ac7f3..7a8a6688 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -44,9 +44,9 @@ to MongoDB with various settings. To use a connection example from this page, copy the code example into the :ref:`sample application ` or your own application. Make sure to set the ``MONGODB_URI`` environment variable to the -connection string for your MongoDB deployment, and replace the -```` and ```` placeholders with values for your -target namespace. +connection string for your MongoDB deployment and replace all placeholders +in the code examples, such as ````, with the relevant values for your +MongoDB deployment. .. _php-connect-sample: @@ -133,7 +133,7 @@ MongoDB instance: :end-before: end-enable-tls-uri To learn more about enabling TLS, see :ref:`php-enable-tls` in -the TLS configuration guide. +the TLS Configuration guide. Specify a Certificate Authority (CA) File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -162,7 +162,7 @@ for the connection to your MongoDB instance: :end-before: end-ca-file-uri To learn more about specifying a CA file, see :ref:`php-specify-ca-file` in -the TLS configuration guide. +the TLS Configuration guide. Disable OCSP Checks ~~~~~~~~~~~~~~~~~~~ @@ -191,7 +191,7 @@ the OCSP endpoint: :end-before: end-disable-ocsp-uri To learn more about disabling OCSP checks, see :ref:`php-disable-ocsp` in -the TLS configuration guide. +the TLS Configuration guide. Specify a Certificate Revocation List (CRL) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -235,7 +235,7 @@ the driver presents to your MongoDB deployment: :end-before: end-client-cert-uri To learn more about specifying a client certificate, see :ref:`php-client-cert` in -the TLS configuration guide. +the TLS Configuration guide. Provide a Certificate Key File Password ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -264,7 +264,7 @@ client certificate: :end-before: end-key-file-uri To learn more about providing a key file password, see :ref:`php-key-file-password` in -the TLS configuration guide. +the TLS Configuration guide. Allow Insecure TLS ~~~~~~~~~~~~~~~~~~ @@ -292,7 +292,7 @@ The following code shows how to disable certificate verification: :end-before: end-insecure-tls-uri To learn more about allowing insecure TLS, see :ref:`php-insecure-tls` in -the TLS configuration guide. +the TLS Configuration guide. Disable Certificate Validation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -320,7 +320,7 @@ The following code shows how to disable certificate validation: :end-before: end-disable-cert-uri To learn more about disabling certificate validation, see :ref:`php-insecure-tls` in -the TLS configuration guide. +the TLS Configuration guide. Disable Hostname Verification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -348,7 +348,7 @@ The following code shows how to disable hostname verification: :end-before: end-disable-hostname-uri To learn more about disabling hostname verification, see :ref:`php-insecure-tls` in -the TLS configuration guide. +the TLS Configuration guide. Network Compression ------------------- diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index 4aabd080..836c8cd7 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -195,8 +195,8 @@ $uri = ''; $clientOptions = [ 'serverApi' => [ - 'version' => '1' - ] + 'version' => '1', + ], ]; $client = new Client($uri, $clientOptions); // end-stable-api From 74813fdcc73284d25ff4f307a33758fd9f2ce2fd Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 16:40:28 -0400 Subject: [PATCH 04/11] remove compression --- source/connect.txt | 65 +------------------ .../usage-examples/connect-code-examples.php | 30 --------- 2 files changed, 3 insertions(+), 92 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 7a8a6688..22479bbd 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -350,67 +350,6 @@ The following code shows how to disable hostname verification: To learn more about disabling hostname verification, see :ref:`php-insecure-tls` in the TLS Configuration guide. -Network Compression -------------------- - -Compression Algorithms -~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to enable compression for the connection -to your MongoDB instance by specifying each compression algorithm: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-compression-all-client - :end-before: end-compression-all-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-compression-all-uri - :end-before: end-compression-all-uri - -To learn more about specifying compression algorithms, see -:ref:`php-enable-compression` in the Network Compression guide. - -zlib Compression Level -~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to specify the ``zlib`` compression algorithm -and set its compression level: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-compression-zlib-client - :end-before: end-compression-zlib-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-compression-zlib-uri - :end-before: end-compression-zlib-uri - -To learn more about setting the zlib compression level, see -:ref:`php-enable-compression` in the Network Compression guide. - {+stable-api+} -------------- @@ -425,4 +364,6 @@ connection to your MongoDB instance: To learn more about the {+stable-api+}, see the :ref:`php-stable-api` guide. - +.. TODO: + Network Compression + ------------------- \ No newline at end of file diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index 836c8cd7..d3f4f5fe 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -160,36 +160,6 @@ $client = new Client($uri); // end-disable-hostname-uri -// Enables compression for a MongoDB connection and specifies each compression algorithm -// using client options -// start-compression-all-client -$client = new Client( - 'mongodb://:/', - ['tls' => true, 'compressors' => 'snappy,zstd,zlib'], -); -// end-compression-all-client - -// Enables compression for a MongoDB connection and specifies each compression algorithm -// using connection URI parameters -// start-compression-all-uri -$uri = 'mongodb://:/?compressors=snappy,zstd,zlib'; -$client = new Client($uri); -// end-compression-all-uri - -// Enables zlib compression for a MongoDB connection using client options -// start-compression-zlib-client -$client = new Client( - 'mongodb://:/', - ['tls' => true, 'compressors' => 'zlib', 'zlibCompressionLevel' => 1], -); -// end-compression-zlib-client - -// Enables zlib compression for a MongoDB connection using connection URI parameters -// start-compression-zlib-uri -$uri = 'mongodb://:/?compressors=zlib&zlibCompressionLevel=1'; -$client = new Client($uri); -// end-compression-zlib-uri - // Connects to a MongoDB deployment and enables the stable API // start-stable-api $uri = ''; From 70f6162678e67ee2b07583e9e6b8a291904e4da0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 16:46:14 -0400 Subject: [PATCH 05/11] fix --- source/connect.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect.txt b/source/connect.txt index 22479bbd..1f217704 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -269,7 +269,7 @@ the TLS Configuration guide. Allow Insecure TLS ~~~~~~~~~~~~~~~~~~ -The following code shows how to disable certificate verification: +The following code shows how to enable insecure TLS: .. tabs:: From 0bedb02d9f06b1fff7134aa16ba84ccfa9fbd453 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 16:48:16 -0400 Subject: [PATCH 06/11] sample app --- source/connect.txt | 8 +++----- source/includes/usage-examples/connect-sample-app.php | 3 --- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 1f217704..73e45718 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -43,10 +43,8 @@ to MongoDB with various settings. To use a connection example from this page, copy the code example into the :ref:`sample application ` or your own application. -Make sure to set the ``MONGODB_URI`` environment variable to the -connection string for your MongoDB deployment and replace all placeholders -in the code examples, such as ````, with the relevant values for your -MongoDB deployment. +Make sure to replace all placeholders in the code examples, such as +````, with the relevant values for your MongoDB deployment. .. _php-connect-sample: @@ -56,7 +54,7 @@ MongoDB deployment. :language: php :copyable: true :linenos: - :emphasize-lines: 8-10 + :emphasize-lines: 5-7 Connection ---------- diff --git a/source/includes/usage-examples/connect-sample-app.php b/source/includes/usage-examples/connect-sample-app.php index 588b8aaa..5920acc2 100644 --- a/source/includes/usage-examples/connect-sample-app.php +++ b/source/includes/usage-examples/connect-sample-app.php @@ -2,9 +2,6 @@ require __DIR__ . '/../vendor/autoload.php'; -$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); -$client = new MongoDB\Client($uri); - // Start example code here // End example code here From 67a3b4f4f5d34c14da07218b4e2ea05e0a29cb41 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 23 Sep 2024 16:48:53 -0400 Subject: [PATCH 07/11] snooty --- snooty.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/snooty.toml b/snooty.toml index 938cdc0d..7ab4ab33 100644 --- a/snooty.toml +++ b/snooty.toml @@ -22,6 +22,7 @@ toc_landing_pages = [ "/reference/class/MongoDBModelDatabaseInfo", "/reference/class/MongoDBModelIndexInfo", "/get-started", + "/connect", "/write", "/indexes" ] From 54aa80a467717d13304512dbfbe328946ff6ca22 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 25 Sep 2024 10:17:39 -0400 Subject: [PATCH 08/11] JM feedback --- source/connect.txt | 33 ++++++++++- .../usage-examples/connect-code-examples.php | 55 +++++++++---------- .../usage-examples/connect-sample-app.php | 12 ++-- 3 files changed, 63 insertions(+), 37 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 73e45718..9628b0ab 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -56,6 +56,14 @@ Make sure to replace all placeholders in the code examples, such as :linenos: :emphasize-lines: 5-7 +.. important:: Percent-Encoding + + You must :wikipedia:`percent-encode ` a username and password before + you include them in a MongoDB URI. You can use the ``rawurlencode()`` method to encode + these values according to the URI syntax specified in `RFC 3986 `__. + Don't percent-encode the username or password when passing them in an options array + parameter to the ``MongoDB\Client`` constructor. + Connection ---------- @@ -84,6 +92,11 @@ The following code shows how to connect to a local MongoDB deployment: :start-after: start-local :end-before: end-local +.. note:: + + If you don't specify the ``$uri`` parameter, the connection URI defaults to + ``'mongodb://127.0.0.1:27017'``. + To learn more about connecting to a local deployment, see :ref:`php-connection-local` in the Connection Targets guide. @@ -261,13 +274,20 @@ client certificate: :start-after: start-key-file-uri :end-before: end-key-file-uri +.. important:: + + When replacing the ```` placeholder, ensure that you :wikipedia:`percent-encode + ` the value. + To learn more about providing a key file password, see :ref:`php-key-file-password` in the TLS Configuration guide. Allow Insecure TLS ~~~~~~~~~~~~~~~~~~ -The following code shows how to enable insecure TLS: +The following code shows how to relax TLS constraints, which has the same +effect as disabling both :ref:`certificate validation ` +and :ref:`hostname verification `: .. tabs:: @@ -292,6 +312,15 @@ The following code shows how to enable insecure TLS: To learn more about allowing insecure TLS, see :ref:`php-insecure-tls` in the TLS Configuration guide. +.. warning:: + + Setting the ``tlsInsecure`` option to ``true`` might expose your application + to security risks. Enabling this option makes your application insecure and + potentially vulnerable to expired certificates and to foreign processes posing + as valid client instances. + +.. _php-connect-disable-cert: + Disable Certificate Validation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -320,6 +349,8 @@ The following code shows how to disable certificate validation: To learn more about disabling certificate validation, see :ref:`php-insecure-tls` in the TLS Configuration guide. +.. _php-connect-disable-hostname: + Disable Hostname Verification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index d3f4f5fe..b0f1b1f6 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -2,30 +2,28 @@ require 'vendor/autoload.php'; -use MongoDB\Client; - // Connects to a local MongoDB deployment // start-local $uri = 'mongodb://localhost:27017/'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-local // Connects to a MongoDB Atlas deployment // start-atlas $uri = ''; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-atlas // Connects to a replica set // start-replica-set $uri = 'mongodb://:/?replicaSet='; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-replica-set // Connects to a MongoDB deployment and enables TLS using client // options // start-enable-tls-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true], ); @@ -35,13 +33,13 @@ // parameters // start-enable-tls-uri $uri = 'mongodb://:/?tls=true'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-enable-tls-uri // Connects to a MongoDB deployment, enables TLS, and specifies the path to // a CA file using client options // start-ca-file-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'], ); @@ -51,13 +49,13 @@ // a CA file using connection URI parameters // start-ca-file-uri $uri = 'mongodb://:/?tls=true&tlsCAFile=/path/to/ca.pem'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-ca-file-uri // Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks // using client options // start-disable-ocsp-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true], ); @@ -67,13 +65,13 @@ // using connection URI parameters // start-disable-ocsp-uri $uri = 'mongodb://:/?tls=true&tlsDisableOCSPEndpointCheck=true'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-disable-ocsp-uri // Connects to a TLS-enabled deployment and instructs the driver to check the // server certificate against a CRL // start-crl -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true], ['crl_file' => '/path/to/file.pem'], @@ -83,7 +81,7 @@ // Presents a client certificate to prove identity // using client options // start-client-cert-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'], ); @@ -93,12 +91,12 @@ // using connection URI parameters // start-client-cert-uri $uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-client-cert-uri // Specifies the password for a client certificate using client options // start-key-file-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', [ 'tls' => true, @@ -111,13 +109,13 @@ // Specifies the password for a client certificate using connection URI parameters // start-key-file-uri $uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword='; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-key-file-uri // Connects to a TLS-enabled deployment and disables server certificate verification // using client options // start-insecure-tls-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true, 'tlsInsecure' => true], ); @@ -127,12 +125,12 @@ // using connection URI parameters // start-insecure-tls-uri $uri = 'mongodb://:/?tls=true&tlsInsecure=true'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-insecure-tls-uri // Disables certificate validation using client options // start-disable-cert-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true, 'tlsAllowInvalidCertificates' => true], ); @@ -141,13 +139,13 @@ // Disables certificate validation using connection URI parameters // start-disable-cert-uri $uri = 'mongodb://:/?tls=true&tlsAllowInvalidCertificates=true'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-disable-cert-uri // Connects to a TLS-enabled deployment and disables hostname verification // using client options // start-disable-hostname-client -$client = new Client( +$client = new MongoDB\Client( 'mongodb://:/', ['tls' => true, 'tlsAllowInvalidHostnames' => true], ); @@ -157,18 +155,17 @@ // using connection URI parameters // start-disable-hostname-uri $uri = 'mongodb://:/?tls=true&tlsAllowInvalidHostnames=true'; -$client = new Client($uri); +$client = new MongoDB\Client($uri); // end-disable-hostname-uri // Connects to a MongoDB deployment and enables the stable API // start-stable-api -$uri = ''; -$clientOptions = [ - 'serverApi' => [ - 'version' => '1', - ], -]; -$client = new Client($uri, $clientOptions); +$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi(ServerApi::V1)]; +$client = new MongoDB\Client( + 'mongodb://:/', + [], + $driverOptions, +); // end-stable-api ?> \ No newline at end of file diff --git a/source/includes/usage-examples/connect-sample-app.php b/source/includes/usage-examples/connect-sample-app.php index 5920acc2..d89319ff 100644 --- a/source/includes/usage-examples/connect-sample-app.php +++ b/source/includes/usage-examples/connect-sample-app.php @@ -6,11 +6,9 @@ // End example code here -$admin = $client->admin; -$result = $admin->command(['ping' => 1]); - -if ($result) { +try { + $client->test->command(['ping' => 1]); echo 'Successfully pinged the MongoDB server.', PHP_EOL; -} else { - echo 'Ping to MongoDB server failed.', PHP_EOL; -} \ No newline at end of file +} catch (MongoDB\Driver\Exception\RuntimeException $e) { + printf("Failed to ping the MongoDB server: %s\n", $e->getMessage()); +} From 5f06c440defa1c89a035a19bfaa8a78cac177a98 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 25 Sep 2024 10:24:53 -0400 Subject: [PATCH 09/11] replica set --- source/connect.txt | 24 +++++++++++++++---- .../usage-examples/connect-code-examples.php | 14 ++++++++--- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 9628b0ab..3030f52c 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -105,11 +105,25 @@ Replica Set The following code shows how to connect to a replica set deployment: -.. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-replica-set - :end-before: end-replica-set +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-replica-set-client + :end-before: end-replica-set-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-replica-set-uri + :end-before: end-replica-set-uri To learn more about connecting to a replica set, see :ref:`php-connection-replica-set` in the Connection Targets guide. diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index b0f1b1f6..1f5ea2d2 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -14,11 +14,19 @@ $client = new MongoDB\Client($uri); // end-atlas -// Connects to a replica set -// start-replica-set +// Connects to a replica set using client options +// start-replica-set-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['replicaSet' => ''], +); +// end-replica-set-client + +// Connects to a replica set using a connection URI parameter +// start-replica-set-uri $uri = 'mongodb://:/?replicaSet='; $client = new MongoDB\Client($uri); -// end-replica-set +// end-replica-set-uri // Connects to a MongoDB deployment and enables TLS using client // options From 17ca25887f2a5f6eb7ee3e2345d785ac690b8afa Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 25 Sep 2024 17:04:04 -0400 Subject: [PATCH 10/11] JM feedback 2 --- source/connect.txt | 10 ++++++++-- .../includes/usage-examples/connect-code-examples.php | 2 +- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 3030f52c..cc4ff021 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -125,6 +125,12 @@ The following code shows how to connect to a replica set deployment: :start-after: start-replica-set-uri :end-before: end-replica-set-uri +.. tip:: + + To maintain your connection to a replica set deployment when one + host is down, you can provide multiple replica set members in the + connection URI. + To learn more about connecting to a replica set, see :ref:`php-connection-replica-set` in the Connection Targets guide. @@ -290,8 +296,8 @@ client certificate: .. important:: - When replacing the ```` placeholder, ensure that you :wikipedia:`percent-encode - ` the value. + When replacing the ```` placeholder in the connection URI, ensure + that you :wikipedia:`percent-encode ` the value. To learn more about providing a key file password, see :ref:`php-key-file-password` in the TLS Configuration guide. diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index 1f5ea2d2..e8fb9fff 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -168,7 +168,7 @@ // Connects to a MongoDB deployment and enables the stable API // start-stable-api -$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi(ServerApi::V1)]; +$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; $client = new MongoDB\Client( 'mongodb://:/', [], From 4c38673036aff4fc81b4ff664cdbaf0d5d76a6d7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 26 Sep 2024 13:05:47 -0400 Subject: [PATCH 11/11] JM last feedback --- source/includes/usage-examples/connect-code-examples.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index e8fb9fff..cc994df0 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -175,5 +175,3 @@ $driverOptions, ); // end-stable-api - -?> \ No newline at end of file