DOCSP-43204: Connection landing page

source/connect.txt

@@ -0,0 +1,369 @@
+.. _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 <php-connect-sample>` 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 ``<hostname>``, 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: 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.
+
+{+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
+ -------------------