From de8ff22f564b1d5fb034bb4bb446771ad05a1e45 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 11 Mar 2025 13:16:35 -0400 Subject: [PATCH] backport get started merge --- source/get-started.txt | 319 +++++++++++++++++- .../create-a-connection-string.txt | 68 ---- source/get-started/create-a-deployment.txt | 36 -- source/get-started/download-and-install.txt | 102 ------ source/get-started/next-steps.txt | 24 -- source/get-started/run-sample-query.txt | 87 ----- 6 files changed, 311 insertions(+), 325 deletions(-) delete mode 100644 source/get-started/create-a-connection-string.txt delete mode 100644 source/get-started/create-a-deployment.txt delete mode 100644 source/get-started/download-and-install.txt delete mode 100644 source/get-started/next-steps.txt delete mode 100644 source/get-started/run-sample-query.txt diff --git a/source/get-started.txt b/source/get-started.txt index ff8c86cc..f64c8ee4 100644 --- a/source/get-started.txt +++ b/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 - Create a Deployment - Create a Connection String - Run a Sample Query - Next Steps - Overview -------- @@ -43,3 +35,314 @@ connect to a MongoDB cluster hosted on MongoDB Atlas and query data in your clus 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 ` version 7.4 or later + - `Composer `__ 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 + + ` + 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 `, + 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 ```` and ```` 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= + + .. tab:: .env File + :tabid: dotenv + + .. code-block:: none + + MONGODB_URI= + + .. 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:`` section. +- Learn how to perform write operations in the :ref:`` section. \ No newline at end of file diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt deleted file mode 100644 index 52a096c4..00000000 --- a/source/get-started/create-a-connection-string.txt +++ /dev/null @@ -1,68 +0,0 @@ -.. _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 `, - 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 ```` and ```` 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. - -.. include:: /includes/get-started/troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt deleted file mode 100644 index fa72db96..00000000 --- a/source/get-started/create-a-deployment.txt +++ /dev/null @@ -1,36 +0,0 @@ -.. _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 ` - 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. - -.. include:: /includes/get-started/troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt deleted file mode 100644 index d9f15d67..00000000 --- a/source/get-started/download-and-install.txt +++ /dev/null @@ -1,102 +0,0 @@ -.. _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 ` version 7.4 or later - - `Composer `__ 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 - - ` section. -- Learn how to perform write operations in the :ref:`` section. \ No newline at end of file diff --git a/source/get-started/run-sample-query.txt b/source/get-started/run-sample-query.txt deleted file mode 100644 index 14eddd43..00000000 --- a/source/get-started/run-sample-query.txt +++ /dev/null @@ -1,87 +0,0 @@ -.. _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= - - .. tab:: .env File - :tabid: dotenv - - .. code-block:: none - - MONGODB_URI= - - .. 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. - -.. include:: /includes/get-started/troubleshoot.rst