From c2636b0cf9a7b5813ab7342a76aa26256f0aa959 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Mar 2025 12:21:14 -0400 Subject: [PATCH 1/6] DOCSP-39181: drupal integration page --- source/php-drivers.txt | 53 +++++--------- source/php-frameworks/drupal.txt | 110 ++++++++++++++++++++++++++++++ source/php-frameworks/symfony.txt | 6 +- source/php-libraries.txt | 4 ++ 4 files changed, 135 insertions(+), 38 deletions(-) create mode 100644 source/php-frameworks/drupal.txt diff --git a/source/php-drivers.txt b/source/php-drivers.txt index d625a119b..2714c12d9 100644 --- a/source/php-drivers.txt +++ b/source/php-drivers.txt @@ -20,8 +20,9 @@ MongoDB PHP Driver :titlesonly: Laravel MongoDB - /php-frameworks/symfony - /php-libraries + Symfony Integration + Drupal Integration + Libraries, Frameworks, & Tools .. contents:: On this page :local: @@ -36,44 +37,32 @@ Welcome to the documentation site for the official MongoDB PHP driver. You can add the driver to your application to work with MongoDB in PHP. The MongoDB PHP Driver consists of the following components: -- The `extension `__, which - provides a low-level API and mainly serves to integrate - `libmongoc and libbson `__ with - PHP. +- `Extension `__: + Provides a low-level API and mainly serves to integrate + the `C Driver `__ + `libmongoc `__ and + `libbson `__ libraries with PHP. -- The `library `__, which - provides a high-level API for working with MongoDB +- `Library `__: + Provides a high-level API for working with MongoDB databases consistent with other MongoDB language drivers. While it is possible to use the extension alone, MongoDB recommends using both the extension and the library together. To learn more about -the components of the PHP driver, see the :ref:`Driver Architecture -` section of this page. +the components of the PHP driver, see the :ref:`php-driver-arch` section +of this page. Navigate through the following links to learn more about the driver and access tutorial content on setting up a runnable project: -- `Tutorials `__ +- `Get Started with the PHP Library `__ +- `Connect to MongoDB `__ -- `Extension Architecture and Internals `__ +Reference +~~~~~~~~~ -- Documentation - - - `Library `__ - - - `Extension `__ - -- Changelog - - - `Library `__ - - - `Extension `__ - -- Source Code - - - `Library `__ - - - `Extension `__ +- :github:`Release Notes ` +- :github:`Driver Source Code ` .. _php-driver-arch: @@ -245,9 +234,3 @@ The first column lists the driver versions. .. include:: /includes/about-driver-compatibility.rst .. include:: /includes/help-links-php.rst - -See Also --------- - -- :ref:`php-libraries-frameworks-and-tools` - diff --git a/source/php-frameworks/drupal.txt b/source/php-frameworks/drupal.txt new file mode 100644 index 000000000..2e937f66f --- /dev/null +++ b/source/php-frameworks/drupal.txt @@ -0,0 +1,110 @@ +.. _php-drupal-integration: + +========================== +Drupal MongoDB Integration +========================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, code example, CMS, web app, authentication + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about the benefits of using MongoDB Atlas +as the database for Drupal sites and navigate to a tutorial that +demonstrates how to set up the MongoDB driver for Drupal. + +`Drupal `__ is an open-source web content +management system (CMS) written in PHP. Drupal provides simple content +authoring, composability, and robust authentication features. + +The :ref:`php-drupal-tutorial` section of this guide links to a tutorial +which you can follow to set up a Drupal site that connects to MongoDB Atlas. + +The :ref:`php-drupal-resources` section contains links to resources and +documentation for further learning. + +Why Use MongoDB as the Database for Drupal Sites? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Websites that seek to provide personalized user experiences must contain +robust capabilities for user authentication. Sites that have many +authenticated users might face performance impacts due to the complexity +of retrieving entity data from multiple tables in a relational database. +MongoDB supports eliminates the need for complicated table joins and +thus increases data retrieval speed, enhancing user experience with +components such as personalized dashboards and dynamic content feeds. + +When you use MongoDB as your site's database, Drupal stores entity +instances as JSON objects that contain all revisions, translations, and +field data. This flexible data structure decreases latency and allows +Drupal to support personalized, user-focused experiences. + +MongoDB offers the following features that improve your Drupal sites: + +- Horizontal scaling: Distribute loads across multiple + servers, making your database scalable for large user bases. + +- Integrated file storage: Store user files directly in the + database instead of on the web server, simplifying hosting. + +- Full-Text search: Avoid implementing separate search + solutions by leveraging the :atlas:`Atlas Search + ` feature. + +- AI capabilities: Perform vector searches and integrate AI services by + using the :atlas:`Atlas Vector Search + ` feature. + +.. _php-drupal-tutorial: + +Tutorial +-------- + +To learn how to install the MongoDB driver for Drupal and set up a site +that uses MongoDB Atlas as its database, see the +`How to Run Drupal on MongoDB `__ +tutorial on the DEV Community website. + +This tutorial demonstrates how to perform the following steps: + +1. Setting up a MongoDB Atlas account and deployment. + +#. Setting up an AWS EC2 medium instance. + +#. Connecting the EC2 instance to Atlas. + +#. Installing the following components: + + - Apache web server + - MongoDB PHP Extension + - Drupal web server + - Drupal core patch + +#. Connecting your Drupal site to Atlas. + +#. Adding content to Drupal and viewing how it is stored in Atlas. + +#. Safely shutting down your web server. + +.. _php-drupal-resources: + +Resources +--------- + +Learn more about Drupal and MongoDB by viewing the following resources: + +- `MongoDB module suite for Drupal `__ +- `Drupal CMS User Guide `__ +- :website:`Podcast: PHP, Drupal and MongoDB with David Bekker + ` diff --git a/source/php-frameworks/symfony.txt b/source/php-frameworks/symfony.txt index 43f9c096a..765da2a24 100644 --- a/source/php-frameworks/symfony.txt +++ b/source/php-frameworks/symfony.txt @@ -26,9 +26,9 @@ read about the benefits of using Symfony to build web applications with MongoDB as your database and practice using libraries that simplify querying MongoDB. -Symfony is a flexible and highly configurable framework for building PHP -applications. You can use this framework to create reusable components -to streamline your web app. +`Symfony `__ is a flexible and highly configurable +framework for building PHP applications. You can use this framework to +create reusable components to streamline your web app. The :ref:`php-symfony-qs` section of this guide contains a tutorial which you can follow to build a single page app that accesses data from diff --git a/source/php-libraries.txt b/source/php-libraries.txt index 587c79776..5f35f47f3 100644 --- a/source/php-libraries.txt +++ b/source/php-libraries.txt @@ -58,6 +58,10 @@ Framework Integrations types of Drupal data in MongoDB. The ``mongodb`` extension supports Drupal 8 and later. + - :ref:`php-drupal-integration` describes the benefits of using MongoDB + as a data store in a Drupal site and provides useful links to learn + about using this integration. + - Laravel - `Laravel MongoDB `__ From c79a3eec64e8f23c1a9a675aac992e0f3333af23 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Mar 2025 12:24:45 -0400 Subject: [PATCH 2/6] wip: --- source/php-frameworks/drupal.txt | 6 +++--- source/php-frameworks/symfony.txt | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/php-frameworks/drupal.txt b/source/php-frameworks/drupal.txt index 2e937f66f..46f3d3882 100644 --- a/source/php-frameworks/drupal.txt +++ b/source/php-frameworks/drupal.txt @@ -9,7 +9,7 @@ Drupal MongoDB Integration :values: tutorial .. meta:: - :keywords: php framework, code example, CMS, web app, authentication + :keywords: php framework, CMS, web app, authentication, Atlas .. contents:: On this page :local: @@ -45,7 +45,7 @@ MongoDB supports eliminates the need for complicated table joins and thus increases data retrieval speed, enhancing user experience with components such as personalized dashboards and dynamic content feeds. -When you use MongoDB as your site's database, Drupal stores entity +When you use MongoDB Atlas as your site's database, Drupal stores entity instances as JSON objects that contain all revisions, translations, and field data. This flexible data structure decreases latency and allows Drupal to support personalized, user-focused experiences. @@ -87,7 +87,7 @@ This tutorial demonstrates how to perform the following steps: #. Installing the following components: - Apache web server - - MongoDB PHP Extension + - `MongoDB PHP extension `__ - Drupal web server - Drupal core patch diff --git a/source/php-frameworks/symfony.txt b/source/php-frameworks/symfony.txt index 765da2a24..9b1e6ea29 100644 --- a/source/php-frameworks/symfony.txt +++ b/source/php-frameworks/symfony.txt @@ -124,9 +124,9 @@ Atlas documentation. Install MongoDB Extension ~~~~~~~~~~~~~~~~~~~~~~~~~ -To learn more about installing the MongoDB extension, see `Installing the Extension -`__ -in the PHP Library Manual. +To learn more about installing the MongoDB extension, see the `Get +Started with the PHP Library +`__ tutorial. Initialize a Symfony Project ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From e1fe3f38f9fa88ecc82b183d54b5a3b1f0a55dd9 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Mar 2025 16:42:49 -0400 Subject: [PATCH 3/6] MW PR fixes 1 --- source/php-drivers.txt | 107 ++----------------------------- source/php-frameworks/drupal.txt | 11 ++-- 2 files changed, 9 insertions(+), 109 deletions(-) diff --git a/source/php-drivers.txt b/source/php-drivers.txt index 2714c12d9..8e957d046 100644 --- a/source/php-drivers.txt +++ b/source/php-drivers.txt @@ -39,20 +39,19 @@ The MongoDB PHP Driver consists of the following components: - `Extension `__: Provides a low-level API and mainly serves to integrate - the `C Driver `__ - `libmongoc `__ and + the `libmongoc `__ and `libbson `__ libraries with PHP. - `Library `__: Provides a high-level API for working with MongoDB databases consistent with other MongoDB language drivers. -While it is possible to use the extension alone, MongoDB recommends -using both the extension and the library together. To learn more about +While it is possible to use only the extension, we recommend +using the extension and the library together. To learn more about the components of the PHP driver, see the :ref:`php-driver-arch` section of this page. -Navigate through the following links to learn more about the driver and access +View the following guides to learn more about the driver and access tutorial content on setting up a runnable project: - `Get Started with the PHP Library `__ @@ -102,104 +101,6 @@ provides the following functionality: To learn more about the system libraries, see the `C Driver `__ documentation. -Connect to a Compatible MongoDB Deployment ------------------------------------------- - -You can use the PHP driver to connect to deployments hosted in the -following environments: - -.. include:: /includes/fact-environments.rst - -Installation ------------- - -First, make sure you have a recent version of PHP installed on your -system. See the -`official PHP manual `__ -for download and installation instructions. - -Install the PHP MongoDB Extension before installing the PHP Library for -MongoDB. You can install the extension using -`PECL `__ on -the command line: - -.. code-block:: sh - - $ sudo pecl install mongodb - -Finally, add the following line to your ``php.ini`` file: - -.. code-block:: text - - extension=mongodb.so - -.. note:: - - On some systems, there may be multiple INI files for individual SAPIs (e.g. - CLI, FPM). Make sure to enable the extension in all SAPIs that you need. - -The preferred method of installing the PHP library is with -`Composer `__ by running the following 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 - - `__. - -.. _connect-atlas-php-driver: - -Connect to MongoDB Atlas ------------------------- - -You can use the following connection snippet to test your connection to -your MongoDB deployment on Atlas: - -.. literalinclude:: /includes/connection-snippets/scram/php-connection.php - :language: php - -This connection snippet uses the {+stable-api+} feature, which you can -enable when using the PHP driver v1.9 and later to connect to MongoDB Server -v5.0 and later. When you use this feature, you can update your driver or server without -worrying about backward compatibility issues with any commands covered by the -{+stable-api+}. - -To learn more about the {+stable-api+} feature, see -:manual:`{+stable-api+} ` in the Server manual. - -.. include:: /includes/stable-api-notice.rst - -.. _connect-atlas-no-stable-api-php-driver: - -Connect to MongoDB Atlas Without the Stable API ------------------------------------------------ - -If you are using a version of MongoDB or the driver that doesn't support the -{+stable-api+} feature, you can use the following code snippet to test your connection -to your MongoDB deployment on Atlas: - -.. literalinclude:: /includes/connection-snippets/scram/php-connection-no-stableapi.php - :language: php - -Connect to a MongoDB Server on Your Local Machine -------------------------------------------------- - -.. include:: /includes/localhost-connection.rst - -To test whether you can connect to your server, replace the connection -string in the :ref:`Connect to MongoDB Atlas ` code -example and run it. - Compatibility ------------- diff --git a/source/php-frameworks/drupal.txt b/source/php-frameworks/drupal.txt index 46f3d3882..f2027fe00 100644 --- a/source/php-frameworks/drupal.txt +++ b/source/php-frameworks/drupal.txt @@ -21,15 +21,14 @@ Overview -------- In this guide, you can learn about the benefits of using MongoDB Atlas -as the database for Drupal sites and navigate to a tutorial that -demonstrates how to set up the MongoDB driver for Drupal. +as the database for Drupal sites. `Drupal `__ is an open-source web content management system (CMS) written in PHP. Drupal provides simple content authoring, composability, and robust authentication features. The :ref:`php-drupal-tutorial` section of this guide links to a tutorial -which you can follow to set up a Drupal site that connects to MongoDB Atlas. +that you can follow to set up a Drupal site that connects to MongoDB Atlas. The :ref:`php-drupal-resources` section contains links to resources and documentation for further learning. @@ -41,8 +40,8 @@ Websites that seek to provide personalized user experiences must contain robust capabilities for user authentication. Sites that have many authenticated users might face performance impacts due to the complexity of retrieving entity data from multiple tables in a relational database. -MongoDB supports eliminates the need for complicated table joins and -thus increases data retrieval speed, enhancing user experience with +MongoDB eliminates the need for complicated table joins and +thus increases data retrieval speed, enhancing user experience of components such as personalized dashboards and dynamic content feeds. When you use MongoDB Atlas as your site's database, Drupal stores entity @@ -58,7 +57,7 @@ MongoDB offers the following features that improve your Drupal sites: - Integrated file storage: Store user files directly in the database instead of on the web server, simplifying hosting. -- Full-Text search: Avoid implementing separate search +- Full-text search: Avoid implementing separate search solutions by leveraging the :atlas:`Atlas Search ` feature. From e5c1c39bf9c5226dd0e43bba471e6aa81cb57c87 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Mar 2025 16:48:25 -0400 Subject: [PATCH 4/6] wip --- source/php-drivers.txt | 59 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/source/php-drivers.txt b/source/php-drivers.txt index 8e957d046..e8025f452 100644 --- a/source/php-drivers.txt +++ b/source/php-drivers.txt @@ -101,6 +101,65 @@ provides the following functionality: To learn more about the system libraries, see the `C Driver `__ documentation. +Connect to a Compatible MongoDB Deployment +------------------------------------------ + +You can use the PHP driver to connect to deployments hosted in the +following environments: + +.. include:: /includes/fact-environments.rst + +Installation +------------ + +Make sure you have a recent version of PHP installed on your +system. See the `PHP manual `__ +for download and installation instructions. + +Install the PHP MongoDB Extension before you install the MongoDB PHP +Library. You can install the extension by using `PECL +`__ on the +command line: + +.. code-block:: sh + + sudo pecl install mongodb + +After installation completes, add the following line to your ``php.ini`` +file: + +.. code-block:: text + + extension=mongodb.so + +.. note:: + + On some systems, there might be multiple ``.ini`` files for + individual SAPIs (e.g. CLI, FPM). Make sure to enable the extension + in all SAPIs that you use. + +Then, install the PHP library by using `Composer +`__. Run the following command from your +project directory: + +.. code-block:: sh + + composer require mongodb/mongodb + +After installation completes, ensure that your application includes +Composer's autoloader as shown in the following example: + +.. code-block:: php + + `__ contains reference +materials and tutorials that demonstrate how to interact with your +MongoDB data. + Compatibility ------------- From dc3821f98835b2ab5c417d75bb0ab3781441b69e Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Mar 2025 16:49:55 -0400 Subject: [PATCH 5/6] remove unused files --- .../scram/php-connection-no-stableapi.php | 18 --------------- .../scram/php-connection.php | 22 ------------------- 2 files changed, 40 deletions(-) delete mode 100644 source/includes/connection-snippets/scram/php-connection-no-stableapi.php delete mode 100644 source/includes/connection-snippets/scram/php-connection.php diff --git a/source/includes/connection-snippets/scram/php-connection-no-stableapi.php b/source/includes/connection-snippets/scram/php-connection-no-stableapi.php deleted file mode 100644 index af349e934..000000000 --- a/source/includes/connection-snippets/scram/php-connection-no-stableapi.php +++ /dev/null @@ -1,18 +0,0 @@ -'; - -// Create a new client and connect to the server -$client = new MongoDB\Client($uri); - -try { - // Send a ping to confirm a successful connection - $client->selectDatabase('admin')->command(['ping' => 1]); - echo "Pinged your deployment. You successfully connected to MongoDB!\n"; -} catch (Exception $e) { - printf($e->getMessage()); -} \ No newline at end of file diff --git a/source/includes/connection-snippets/scram/php-connection.php b/source/includes/connection-snippets/scram/php-connection.php deleted file mode 100644 index 75c84abdc..000000000 --- a/source/includes/connection-snippets/scram/php-connection.php +++ /dev/null @@ -1,22 +0,0 @@ -'; - -// Specify Stable API version 1 -$apiVersion = new ServerApi(ServerApi::V1); - -// Create a new client and connect to the server -$client = new MongoDB\Client($uri, [], ['serverApi' => $apiVersion]); - -try { - // Send a ping to confirm a successful connection - $client->selectDatabase('admin')->command(['ping' => 1]); - echo "Pinged your deployment. You successfully connected to MongoDB!\n"; -} catch (Exception $e) { - printf($e->getMessage()); -} \ No newline at end of file From 84260c637f2c463910ecfebd633df3bdc6b0815b Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Mar 2025 16:56:09 -0400 Subject: [PATCH 6/6] vale fix --- source/php-drivers.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/php-drivers.txt b/source/php-drivers.txt index e8025f452..0351997e1 100644 --- a/source/php-drivers.txt +++ b/source/php-drivers.txt @@ -135,7 +135,7 @@ file: .. note:: On some systems, there might be multiple ``.ini`` files for - individual SAPIs (e.g. CLI, FPM). Make sure to enable the extension + individual SAPIs, such as CLI, FPM. Make sure to enable the extension in all SAPIs that you use. Then, install the PHP library by using `Composer