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.txt b/source/get-started.txt index 54399028..ac7e9788 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -13,13 +13,33 @@ Get Started with the PHP Library .. 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/ /get-started/create-a-deployment/ /get-started/create-a-connection-string/ - /get-started/next-steps/ \ No newline at end of file + /get-started/next-steps/ + +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 <>`. + diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt new file mode 100644 index 00000000..356830fc --- /dev/null +++ b/source/get-started/download-and-install.txt @@ -0,0 +1,102 @@ +.. _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 `__ 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 + + 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.