DOCSP-43204: Connection landing page

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 <Percent-encoding>` 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 <http://www.faqs.org/rfcs/rfc3986.html>`__.
+   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.
 
@@ -92,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.
@@ -261,13 +288,20 @@ client certificate:
          :start-after: start-key-file-uri
          :end-before: end-key-file-uri
 
+.. important::
+
+   When replacing the ``<password>`` placeholder, ensure that you :wikipedia:`percent-encode
+   <Percent-encoding>` 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 <php-connect-disable-cert>`
+and :ref:`hostname verification <php-connect-disable-hostname>`:
 
 .. tabs::
 
@@ -292,6 +326,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 +363,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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/includes/usage-examples/connect-code-examples.php

@@ -2,30 +2,36 @@
 
 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 = '<Atlas connection string>';
-$client = new Client($uri);
+$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://<replica set member>:<port>/',
+    ['replicaSet' => '<replica set name>'],
+);
+// end-replica-set-client
+
+// Connects to a replica set using a connection URI parameter
+// start-replica-set-uri
 $uri = 'mongodb://<replica set member>:<port>/?replicaSet=<replica set name>';
-$client = new Client($uri);
-// end-replica-set
+$client = new MongoDB\Client($uri);
+// end-replica-set-uri
 
 // Connects to a MongoDB deployment and enables TLS using client
 // options
 // start-enable-tls-client
-$client = new Client(
+$client = new MongoDB\Client(
     'mongodb://<hostname>:<port>/',
     ['tls' => true],
 );
@@ -35,13 +41,13 @@
 // parameters
 // start-enable-tls-uri
 $uri = 'mongodb://<hostname>:<port>/?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://<hostname>:<port>/',
     ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'],
 );
@@ -51,13 +57,13 @@
 // a CA file using connection URI parameters
 // start-ca-file-uri
 $uri = 'mongodb://<hostname>:<port>/?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://<hostname>:<port>/',
     ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true],
 );
@@ -67,13 +73,13 @@
 // using connection URI parameters
 // start-disable-ocsp-uri
 $uri = 'mongodb://<hostname>:<port>/?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://<hostname>:<port>/',
     ['tls' => true],
     ['crl_file' => '/path/to/file.pem'],
@@ -83,7 +89,7 @@
 // Presents a client certificate to prove identity
 // using client options
 // start-client-cert-client
-$client = new Client(
+$client = new MongoDB\Client(
     'mongodb://<hostname>:<port>/',
     ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'],
 );
@@ -93,12 +99,12 @@
 // using connection URI parameters
 // start-client-cert-uri
 $uri = 'mongodb://<hostname>:<port>/?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://<hostname>:<port>/',
     [
         'tls' => true,
@@ -111,13 +117,13 @@
 // Specifies the password for a client certificate using connection URI parameters
 // start-key-file-uri
 $uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword=<password>';
-$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://<hostname>:<port>/',
     ['tls' => true, 'tlsInsecure' => true],
 );
@@ -127,12 +133,12 @@
 // using connection URI parameters
 // start-insecure-tls-uri
 $uri = 'mongodb://<hostname>:<port>/?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://<hostname>:<port>/',
     ['tls' => true, 'tlsAllowInvalidCertificates' => true],
 );
@@ -141,13 +147,13 @@
 // Disables certificate validation using connection URI parameters
 // start-disable-cert-uri
 $uri = 'mongodb://<hostname>:<port>/?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://<hostname>:<port>/',
     ['tls' => true, 'tlsAllowInvalidHostnames' => true],
 );
@@ -157,18 +163,17 @@
 // using connection URI parameters
 // start-disable-hostname-uri
 $uri = 'mongodb://<hostname>:<port>/?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 = '<connection string>';
-$clientOptions = [
-    'serverApi' => [
-        'version' => '1',
-    ],
-];
-$client = new Client($uri, $clientOptions);
+$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi(ServerApi::V1)];
+$client = new MongoDB\Client(
+    'mongodb://<hostname>:<port>/',
+    [],
+    $driverOptions,
+);
 // end-stable-api
 
 ?>

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;
-}
+} catch (MongoDB\Driver\Exception\RuntimeException $e) {
+    printf("Failed to ping the MongoDB server: %s\n", $e->getMessage());
+}