diff --git a/snooty.toml b/snooty.toml index 051763b9..76e5f009 100644 --- a/snooty.toml +++ b/snooty.toml @@ -22,6 +22,7 @@ toc_landing_pages = [ "/reference/class/MongoDBModelDatabaseInfo", "/reference/class/MongoDBModelIndexInfo", "/get-started", + "/connect", "/databases-collections", "/write", "/indexes", diff --git a/source/connect.txt b/source/connect.txt new file mode 100644 index 00000000..cc4ff021 --- /dev/null +++ b/source/connect.txt @@ -0,0 +1,418 @@ +.. _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/tls + +.. TODO: + /connect/connection-options + /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 replace all placeholders in the code examples, such as +````, with the relevant values for your MongoDB deployment. + +.. _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: 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 +---------- + +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 + +.. 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. + +Replica Set +~~~~~~~~~~~ + +The following code shows how to connect to a replica set deployment: + +.. 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 + +.. 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. + +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 + +.. important:: + + 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. + +Allow 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:: + + .. 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. + +.. 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +.. _php-connect-disable-hostname: + +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. + +{+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. + +.. 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 new file mode 100644 index 00000000..cc994df0 --- /dev/null +++ b/source/includes/usage-examples/connect-code-examples.php @@ -0,0 +1,177 @@ +'; +$client = new MongoDB\Client($uri); +// end-atlas + +// 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-uri + +// Connects to a MongoDB deployment and enables TLS using client +// options +// start-enable-tls-client +$client = new MongoDB\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 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 MongoDB\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 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 MongoDB\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 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 MongoDB\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 MongoDB\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 MongoDB\Client($uri); +// end-client-cert-uri + +// Specifies the password for a client certificate using client options +// start-key-file-client +$client = new MongoDB\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 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 MongoDB\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 MongoDB\Client($uri); +// end-insecure-tls-uri + +// Disables certificate validation using client options +// start-disable-cert-client +$client = new MongoDB\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 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 MongoDB\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 MongoDB\Client($uri); +// end-disable-hostname-uri + +// Connects to a MongoDB deployment and enables the stable API +// start-stable-api +$driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; +$client = new MongoDB\Client( + 'mongodb://:/', + [], + $driverOptions, +); +// end-stable-api diff --git a/source/index.txt b/source/index.txt index 7ffdd83a..f8d9c36f 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,6 +11,7 @@ MongoDB PHP Library :titlesonly: Get Started + /connect /databases-collections /read /write