From 6418d931e4a16e1d165c33a5acd488a54459c909 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 6 Aug 2024 11:32:31 -0400 Subject: [PATCH 1/7] DOCSP-41952: Download and Install --- source/get-started.txt | 41 +++++++++ source/get-started/download-and-install.txt | 87 ++++++++++++++++++++ source/includes/get-started/troubleshoot.rst | 6 ++ source/index.txt | 1 + 4 files changed, 135 insertions(+) create mode 100644 source/get-started.txt create mode 100644 source/get-started/download-and-install.txt create mode 100644 source/includes/get-started/troubleshoot.rst diff --git a/source/get-started.txt b/source/get-started.txt new file mode 100644 index 00000000..1acdf3b9 --- /dev/null +++ b/source/get-started.txt @@ -0,0 +1,41 @@ +.. _php-get-started: + +================================ +Get Started with the PHP Library +================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :description: Learn how to create an app to connect to MongoDB deployment by using the PHP library. + :keywords: quick start, tutorial, basics + +.. toctree:: + + /get-started/download-and-install/ + +Overview +-------- + +The {+php-library+} is a high-level abstraction for the MongoDB PHP extension, which +you can use to connect to MongoDB and interact with data stored in your deployment. +This guide shows you how to create an application that uses the {+php-library+} to +connect to a MongoDB cluster hosted on MongoDB Atlas and query data in your cluster. + +.. tip:: + + MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB + deployments. You can create your own free (no credit card required) MongoDB Atlas + deployment by following the steps in this guide. + +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 <>`. \ No newline at end of file diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt new file mode 100644 index 00000000..628920ad --- /dev/null +++ b/source/get-started/download-and-install.txt @@ -0,0 +1,87 @@ +.. _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 `__ + - `Composer `__ + + .. step:: Install the MongoDB 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, add the following line to your + ``php.ini`` file: + + .. code-block:: bash + + extension=mongodb.so + + .. tip:: + + You can locate your ``php.ini`` file by running the following command + from 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 + + Run the following commands to create a ``quickstart.php`` application file in + the ``php-quickstart`` directory: + + .. code-block:: bash + + cd php-quickstart + touch quickstart.php + + .. step:: Install the {+php-library+} + + To install the {+php-library+}, run the following command from 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 line to ``quickstart.php``: + + .. code-block:: bash + + require_once __DIR__ . '/vendor/autoload.php'; + +After you complete these steps, you have a new project directory +and the driver dependencies installed. + +.. include:: /includes/get-started/troubleshoot.rst diff --git a/source/includes/get-started/troubleshoot.rst b/source/includes/get-started/troubleshoot.rst new file mode 100644 index 00000000..08d6e428 --- /dev/null +++ b/source/includes/get-started/troubleshoot.rst @@ -0,0 +1,6 @@ +.. note:: + + If you run into issues on this step, ask for help in the + :community-forum:`MongoDB Community Forums ` + or submit feedback by using the :guilabel:`Rate this page` + tab on the right or bottom right side of this page. \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 1c5c6e72..7c8abf5c 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,6 +11,7 @@ MongoDB PHP Library :titlesonly: Installation + /get-started /tutorial /upgrade /reference From 5ef0ac6b66b93ef87ea3f347d4179d74261d46bb Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 6 Aug 2024 11:40:06 -0400 Subject: [PATCH 2/7] edits --- .gitignore | 1 - source/get-started/download-and-install.txt | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index b42a4f24..85d69aa9 100644 --- a/.gitignore +++ b/.gitignore @@ -3,5 +3,4 @@ build/* build *~ *giza.log -source/* backups/* diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 628920ad..93b1efb5 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -14,7 +14,7 @@ Download and Install .. procedure:: :style: connected - .. step:: Install Dependencies + .. step:: Install dependencies Before you begin developing, ensure that you have the following dependencies installed on your local machine: @@ -22,7 +22,7 @@ Download and Install - `PHP `__ - `Composer `__ - .. step:: Install the MongoDB Extension + .. step:: Install the MongoDB extension Run the following command to install the ``mongodb`` PHP extension: @@ -30,7 +30,7 @@ Download and Install sudo pecl install mongodb - .. step:: Update your PHP Configuration File + .. step:: Update your PHP configuration file To enable the ``mongodb`` extension, add the following line to your ``php.ini`` file: From 005d8301a29855422faf93153033b54adf6326d1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 6 Aug 2024 11:51:57 -0400 Subject: [PATCH 3/7] toc, fixes --- snooty.toml | 1 + source/get-started/download-and-install.txt | 6 +++--- source/index.txt | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/snooty.toml b/snooty.toml index a08a8d41..b80d3e72 100644 --- a/snooty.toml +++ b/snooty.toml @@ -17,6 +17,7 @@ toc_landing_pages = [ "/reference/class/MongoDBModelCollectionInfo", "/reference/class/MongoDBModelDatabaseInfo", "/reference/class/MongoDBModelIndexInfo", + "/get-started", ] [substitutions] diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 93b1efb5..581d833f 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -32,8 +32,8 @@ Download and Install .. step:: Update your PHP configuration file - To enable the ``mongodb`` extension, add the following line to your - ``php.ini`` file: + To enable the ``mongodb`` extension, add the following line to the top of + your ``php.ini`` file: .. code-block:: bash @@ -82,6 +82,6 @@ Download and Install require_once __DIR__ . '/vendor/autoload.php'; After you complete these steps, you have a new project directory -and the driver dependencies installed. +and the library dependencies installed. .. include:: /includes/get-started/troubleshoot.rst diff --git a/source/index.txt b/source/index.txt index 7c8abf5c..244f3eb2 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,7 +11,7 @@ MongoDB PHP Library :titlesonly: Installation - /get-started + Get Started /tutorial /upgrade /reference From cc32aa5adf41435bf711826ddce871703718bb3f Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 6 Aug 2024 15:13:54 -0400 Subject: [PATCH 4/7] AS feedback --- source/get-started/download-and-install.txt | 47 ++++++++++++++------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 581d833f..2ae72121 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -19,10 +19,10 @@ Download and Install Before you begin developing, ensure that you have the following dependencies installed on your local machine: - - `PHP `__ - - `Composer `__ + - `PHP `__ version 7.4 or later + - `Composer `__ version 2.0 or later - .. step:: Install the MongoDB extension + .. step:: Install the MongoDB PHP extension Run the following command to install the ``mongodb`` PHP extension: @@ -32,17 +32,17 @@ Download and Install .. step:: Update your PHP configuration file - To enable the ``mongodb`` extension, add the following line to the top of - your ``php.ini`` 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:: bash + .. code-block:: none extension=mongodb.so .. tip:: You can locate your ``php.ini`` file by running the following command - from your shell: + in your shell: .. code-block:: bash @@ -57,13 +57,26 @@ Download and Install mkdir php-quickstart - Run the following commands to create a ``quickstart.php`` application file in - the ``php-quickstart`` directory: + Select the tab corresponding to your operating system and run following commands + to create a ``quickstart.php`` application file in the ``php-quickstart`` directory: - .. code-block:: bash + .. tabs:: + + .. tab:: macOS / Linux + :tabid: create-file-mac-linux + + .. code-block:: bash + + cd php-quickstart + touch quickstart.php - 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+} @@ -75,13 +88,15 @@ Download and Install composer require mongodb/mongodb After installing the library, include Composer's ``autoload.php`` file by adding the - following line to ``quickstart.php``: + following code to the top of your ``quickstart.php`` file: - .. code-block:: bash + .. code-block:: php + + Date: Wed, 7 Aug 2024 10:18:07 -0400 Subject: [PATCH 5/7] AS feedback 2 --- source/get-started/download-and-install.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 2ae72121..4236d7f6 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -80,7 +80,7 @@ Download and Install .. step:: Install the {+php-library+} - To install the {+php-library+}, run the following command from your ``php-quickstart`` + To install the {+php-library+}, run the following command in your ``php-quickstart`` directory: .. code-block:: bash From 48abf5f09084f8a179f213633b4a054f93f0cdbe Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 7 Aug 2024 11:37:18 -0400 Subject: [PATCH 6/7] typo --- source/get-started/download-and-install.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 4236d7f6..356830fc 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -57,7 +57,7 @@ Download and Install mkdir php-quickstart - Select the tab corresponding to your operating system and run following commands + 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:: From 05827360b1d52158ab822c053858d362d8ea2970 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 Aug 2024 11:51:03 -0400 Subject: [PATCH 7/7] JT feedback --- source/index.txt | 3 +- source/tutorial/install-php-library.txt | 99 ------------------------- 2 files changed, 1 insertion(+), 101 deletions(-) delete mode 100644 source/tutorial/install-php-library.txt diff --git a/source/index.txt b/source/index.txt index 244f3eb2..eadbb1cc 100644 --- a/source/index.txt +++ b/source/index.txt @@ -10,7 +10,6 @@ MongoDB PHP Library .. toctree:: :titlesonly: - Installation Get Started /tutorial /upgrade @@ -38,7 +37,7 @@ New to the PHP Library? If you have some experience with MongoDB but are new to the PHP library, the following pages should help you get started: -- :doc:`/tutorial/install-php-library` +- :ref:`php-download-and-install` - :doc:`/tutorial/connecting` diff --git a/source/tutorial/install-php-library.txt b/source/tutorial/install-php-library.txt deleted file mode 100644 index 913a945e..00000000 --- a/source/tutorial/install-php-library.txt +++ /dev/null @@ -1,99 +0,0 @@ -========================= -Install the |php-library| -========================= - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -The |php-library| is a high-level abstraction for the -:php:`mongodb extension `. This page will briefly explain how to -install both the ``mongodb`` extension and the |php-library|. - -Installing the Extension ------------------------- - -Linux, Unix, and macOS users can either -:php:`install the extension with PECL ` -(recommended) or -:php:`manually compile from source `. -The following command may be used to install the extension with PECL: - -.. code-block:: sh - - sudo pecl install mongodb - -.. note:: - - If the build process for either installation method fails to find a TLS - library, check that the development packages (e.g. ``libssl-dev``) and - `pkg-config `_ are both installed. - -Once the extension is installed, add the following line to your ``php.ini`` -file: - -.. code-block:: ini - - extension=mongodb.so - -Windows users can download precompiled binaries of the extension from its -`GitHub releases `__. -After downloading the appropriate archive for your PHP environment, extract the -``php_mongodb.dll`` file to PHP's extension directory and add the following line -to your ``php.ini`` file: - -.. code-block:: ini - - extension=php_mongodb.dll - -See :php:`Installing the MongoDB PHP Driver on Windows ` -for additional information. - -Installing the Library ----------------------- - -Using Composer -~~~~~~~~~~~~~~ - -The preferred method of installing the |php-library| is with -`Composer `_ by running the following command from -your project root: - -.. code-block:: sh - - composer require mongodb/mongodb - -Once you have installed the library, ensure that your application includes -Composer's autoloader as in the following example: - -.. code-block:: php - - `_ for more -information about setting up autoloading. - -Manual Installation Without Composer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -While not recommended, you may also manually install the library using a source -archive attached to the -`GitHub releases `__. -When installing the library without Composer, you must ensure that all library -classes *and* functions are loaded for your application: - -#. If you are using a `PSR-4 `_ autoloader, - map the top-level ``MongoDB\`` namespace to the ``src/`` directory. If you - are not using an autoloader, manually require _all_ class files found - recursively within the ``src/`` directory. - -#. Regardless of whether you are using an autoloader, manually require the - ``src/functions.php`` file. This is necessary because PHP does not support - autoloading for functions.