Merge pull request #228 from rachel-mack/get-started-merge-v1.21

Backport to v1.21 - [PHP] Duplicate Titles - Connect to MongoDB

Author: rachel-mack

source/get-started.txt

@@ -18,14 +18,6 @@ Get Started with the PHP Library
    :description: Learn how to create an app to connect to MongoDB deployment by using the PHP library.
    :keywords: quick start, tutorial, basics
 
-.. toctree::
-
-   Download & Install </get-started/download-and-install/>
-   Create a Deployment </get-started/create-a-deployment/>
-   Create a Connection String </get-started/create-a-connection-string/>
-   Run a Sample Query </get-started/run-sample-query/>
-   Next Steps </get-started/next-steps/>
-
 Overview
 --------
 
@@ -44,3 +36,313 @@ Follow this guide to connect a sample PHP application to a MongoDB Atlas
 deployment. If you prefer to connect to MongoDB using a different driver or
 programming language, see our :driver:`list of official drivers <>`.
 
+.. _php-download-and-install:
+
+Download and Install
+--------------------
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: setup, composer, installation, code example
+
+.. procedure::
+   :style: connected
+
+   .. step:: Install dependencies
+
+      Before you begin developing, ensure that you have the following
+      dependencies installed on your local machine:
+      
+      - :php:`PHP <install>` version 7.4 or later
+      - `Composer <https://getcomposer.org/download/>`__ version 2.0 or later
+    
+   .. step:: Install the MongoDB PHP extension
+
+      Run the following command to install the ``mongodb`` PHP extension:
+      
+      .. code-block:: bash
+
+         sudo pecl install mongodb
+
+   .. step:: Update your PHP configuration file
+
+      To enable the ``mongodb`` extension in your PHP configuration file, add the
+      following line to the top of your ``php.ini`` file:
+
+      .. code-block:: none
+
+         extension=mongodb.so
+
+      .. tip::
+
+         You can locate your ``php.ini`` file by running the following command
+         in your shell:
+
+         .. code-block:: bash
+
+            php --ini
+
+   .. step:: Create a project directory
+
+      From your root directory, run the following command in your shell to create
+      a directory called ``php-quickstart`` for this project:
+
+      .. code-block:: bash
+
+         mkdir php-quickstart
+
+      Select the tab corresponding to your operating system and run the following commands
+      to create a ``quickstart.php`` application file in the ``php-quickstart`` directory:
+
+      .. tabs::
+
+          .. tab:: macOS / Linux
+             :tabid: create-file-mac-linux
+
+             .. code-block:: bash
+
+                cd php-quickstart
+                touch quickstart.php
+
+          .. tab:: Windows
+             :tabid: create-file-windows
+
+             .. code-block:: bash
+
+                cd php-quickstart
+                type nul > quickstart.php
+
+   .. step:: Install the {+php-library+}
+
+      To install the {+php-library+}, run the following command in your ``php-quickstart``
+      directory:
+
+      .. code-block:: bash
+
+         composer require mongodb/mongodb
+      
+      After installing the library, include Composer's ``autoload.php`` file by adding the
+      following code to the top of your ``quickstart.php`` file:
+
+      .. code-block:: php
+
+         <?php
+
+         require_once __DIR__ . '/vendor/autoload.php';
+
+After you complete these steps, you have a new project directory, a
+new application file, and the library dependencies installed.
+
+.. _php-create-deployment:
+
+Create a MongoDB Deployment
+---------------------------
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: cloud, host, atlas
+
+You can create a free tier MongoDB deployment on MongoDB Atlas
+to store and manage your data. MongoDB Atlas hosts and manages
+your MongoDB database in the cloud.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a free MongoDB deployment on Atlas
+
+      Complete the :atlas:`Get Started with Atlas </getting-started>`
+      guide to set up a new Atlas account and load sample data into a new free
+      tier MongoDB deployment.
+      
+   .. step:: Save your credentials
+
+      After you create your database user, save that user's 
+      username and password to a safe location for use in an upcoming step.
+  
+After you complete these steps, you have a new free tier MongoDB
+deployment on Atlas, database user credentials, and sample data loaded
+into your database.
+
+.. _php-connection-string:
+
+Create a Connection String
+--------------------------
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: uri, atlas
+
+You can connect to your MongoDB deployment by providing a
+**connection URI**, also called a *connection string*, which
+instructs the driver on how to connect to a MongoDB deployment
+and how to behave while connected.
+
+The connection string includes the hostname or IP address and 
+port of your deployment, the authentication mechanism, user credentials 
+when applicable, and connection options.
+
+.. TODO:
+ To connect to an instance or deployment not hosted on Atlas, see
+ :ref:`php-connection-targets`.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Find your MongoDB Atlas Connection String
+
+      To retrieve your connection string for the deployment that
+      you created in the :ref:`previous step <php-create-deployment>`,
+      log in to your Atlas account and navigate to the
+      :guilabel:`Database` section and click the :guilabel:`Connect` button
+      for your new deployment.
+
+      .. figure:: /includes/figures/atlas_connection_select_cluster.png
+         :alt: The connect button in the clusters section of the Atlas UI
+
+      Then, select your user from the :guilabel:`Select database user`
+      selection menu. Select "PHP" from the :guilabel:`Driver` selection
+      menu and the version that best matches the version you installed
+      from the :guilabel:`Version` selection menu.
+      
+      Select the :guilabel:`String` tab in the :guilabel:`Add connection string into your application code`
+      step to view only the connection string.
+
+   .. step:: Copy your Connection String
+
+      Click the button on the right of the connection string to copy it
+      to your clipboard, as shown in the following screenshot:
+
+      .. figure:: /includes/figures/atlas_connection_copy_string_php.png
+         :alt: The copy button next to the connection string in the Atlas UI
+
+   .. step:: Update the Placeholders
+
+      Paste this connection string into a file in your preferred text editor
+      and replace the ``<username>`` and ``<password>`` placeholders with
+      your database user's username and password.
+      
+      Save this file to a safe location for use in the next step.
+
+After completing these steps, you have a connection string that
+corresponds to your Atlas cluster.
+
+.. _php-run-sample-query:
+.. _php-connect-to-mongodb:
+
+Run a Sample Query
+------------------
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: test connection, runnable, code example
+
+After retrieving the connection string for your MongoDB Atlas deployment,
+you can connect to the deployment from your PHP application and query
+the Atlas sample datasets.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Edit your PHP application file
+
+      Copy and paste the following code into the ``quickstart.php`` file, which queries
+      the ``movies`` collection in the ``sample_mflix`` database:
+
+      .. literalinclude:: /includes/get-started/quickstart.php
+         :language: php
+         :dedent:
+
+   .. step:: Assign the connection string
+
+      Assign the ``MONGODB_URI`` environment variable to the connection string that you copied
+      from the :ref:`php-connection-string` step of this guide. You can assign this
+      variable by running a shell command or creating a ``.env`` file in your application,
+      as show in the following tabs:
+
+      .. tabs::
+
+         .. tab:: Shell Command
+            :tabid: shell
+
+            .. code-block:: sh
+
+               export MONGODB_URI=<connection string>
+
+         .. tab:: .env File
+            :tabid: dotenv
+
+            .. code-block:: none
+
+               MONGODB_URI=<connection string>
+
+   .. step:: Run your PHP application
+
+      In your project directory, run the following shell command to start the application:
+      
+      .. code-block:: bash
+
+         php quickstart.php
+
+      The command line output contains details about the retrieved movie
+      document:
+
+      .. code-block:: none
+         :copyable: false
+
+         {
+             "_id": {
+                 "$oid": "..."
+             },
+             ...
+            "rated": "R",
+            "metacritic": 80,
+            "title": "The Shawshank Redemption",
+            ...
+         }
+
+      If you encounter an error or see no output, ensure that you assigned the
+      proper connection string to the ``MONGODB_URI`` environment variable and
+      that you loaded the sample data.
+
+After you complete these steps, you have a PHP application that
+connects to your MongoDB deployment, runs a query on the sample
+data, and returns a matching document.
+ 
+.. _php-next-steps:
+
+Next Steps
+----------
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: learn more
+
+Congratulations on completing the quick start tutorial!
+
+.. include:: /includes/get-started/troubleshoot.rst
+
+In this tutorial, you created a PHP application that
+connects to a MongoDB deployment hosted on MongoDB Atlas
+and retrieves a document that matches a query.
+
+
+Learn more about the {+php-library+} from the following resources:
+
+- Learn how to perform read operations in the :ref:`<php-read>` section.
+- Learn how to perform write operations in the :ref:`<php-write>` section.