diff --git a/source/includes/php-frameworks/symfony/Restaurant.php b/source/includes/php-frameworks/symfony/Restaurant.php new file mode 100644 index 000000000..593bcf803 --- /dev/null +++ b/source/includes/php-frameworks/symfony/Restaurant.php @@ -0,0 +1,25 @@ +dm = $dm; + $this->logger = $logger; + } + + #[Route('/', name: 'restaurant_index', methods: ['GET'])] + public function index(Request $request): Response + { + return $this->render('restaurant/index.html.twig'); + } + + #[Route('/restaurant/browse', name: 'restaurant_browse', methods: ['GET'])] + public function browse(Request $request): Response + { + $restaurantRepository = $this->dm->getRepository(Restaurant::class); + $queryBuilder = $restaurantRepository->createQueryBuilder(); + + $restaurants = $queryBuilder + ->field('borough')->equals('Queens') + ->field('name')->equals(new Regex('Moon', 'i')) + ->getQuery() + ->execute(); + + return $this->render('restaurant/browse.html.twig', ['restaurants' => $restaurants]); + } +} diff --git a/source/includes/php-frameworks/symfony/app_render.png b/source/includes/php-frameworks/symfony/app_render.png new file mode 100644 index 000000000..684a2eb9a Binary files /dev/null and b/source/includes/php-frameworks/symfony/app_render.png differ diff --git a/source/includes/php-frameworks/symfony/browse.html.twig b/source/includes/php-frameworks/symfony/browse.html.twig new file mode 100644 index 000000000..069ea44d0 --- /dev/null +++ b/source/includes/php-frameworks/symfony/browse.html.twig @@ -0,0 +1,18 @@ +{# templates/restaurant/browse.html.twig #} + +{% extends 'base.html.twig' %} + +{% block title %} + Search Restaurants +{% endblock %} + +{% block body %} +

Search Restaurants

+ {% for restaurant in restaurants %} +

+ Name: {{ restaurant.name }}
+ Borough: {{ restaurant.borough }}
+ Cuisine: {{ restaurant.cuisine }}
+

+ {% endfor %} +{% endblock %} \ No newline at end of file diff --git a/source/includes/php-frameworks/symfony/doctrine_mongodb.yaml b/source/includes/php-frameworks/symfony/doctrine_mongodb.yaml new file mode 100644 index 000000000..0937bbf8f --- /dev/null +++ b/source/includes/php-frameworks/symfony/doctrine_mongodb.yaml @@ -0,0 +1,18 @@ +doctrine_mongodb: + auto_generate_proxy_classes: true + auto_generate_hydrator_classes: true + connections: + default: + server: "%env(resolve:MONGODB_URL)%" + default_database: "%env(resolve:MONGODB_DB)%" + document_managers: + default: + auto_mapping: true + mappings: + App: + dir: "%kernel.project_dir%/src/Document" + mapping: true + type: attribute + prefix: 'App\Document' + is_bundle: false + alias: App diff --git a/source/includes/php-frameworks/symfony/index.html.twig b/source/includes/php-frameworks/symfony/index.html.twig new file mode 100644 index 000000000..5da8cf206 --- /dev/null +++ b/source/includes/php-frameworks/symfony/index.html.twig @@ -0,0 +1,7 @@ +{# templates/restaurant/index.html.twig #} + +{% extends 'base.html.twig' %} + +{% block body %} +

Welcome to the Symfony MongoDB Quickstart!

+{% endblock %} diff --git a/source/motor.txt b/source/motor.txt index 4f71729fe..2f7df0509 100644 --- a/source/motor.txt +++ b/source/motor.txt @@ -32,7 +32,8 @@ or set up a runnable project by following our tutorials. .. tip:: If you do not need to access MongoDB in a non-blocking manner or from - co-routines, we recommend that you use the :doc:`PyMongo ` + co-routines, we recommend that you use the `PyMongo + `__ driver instead. - `Tutorial on using Motor with Tornado `__ diff --git a/source/php-drivers.txt b/source/php-drivers.txt index 5a645c9dd..f6dfd15f2 100644 --- a/source/php-drivers.txt +++ b/source/php-drivers.txt @@ -20,6 +20,7 @@ MongoDB PHP Driver :titlesonly: Laravel MongoDB + /php-frameworks/symfony /php-libraries .. contents:: On this page diff --git a/source/php-frameworks/symfony.txt b/source/php-frameworks/symfony.txt new file mode 100644 index 000000000..43f9c096a --- /dev/null +++ b/source/php-frameworks/symfony.txt @@ -0,0 +1,332 @@ +.. _php-symfony-integration: + +=========================== +Symfony MongoDB Integration +=========================== + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :keywords: php framework, doctrine odm, web app + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about the Symfony MongoDB integration and +how to use this framework to build a simple PHP web application. You can +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. + +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 +a MongoDB collection. + +The :ref:`php-symfony-resources` section contains links to resources and +documentation for further learning. + +Why Use MongoDB in a Symfony Application? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By using MongoDB as a data store in a Symfony web application, you can +leverage the document data model to build rich query expressions, +allowing you to easily interact with data. You can also customize your +connections to persist and access data to and from multiple databases +and collections. + +In your applications, you can implement the **Doctrine MongoDB ODM**, +which is an Object-Document Mapper (ODM) for MongoDB and PHP. It +provides a way to work with MongoDB in Symfony, using the same +principles as Doctrine ORM for relational databases. + +Doctrine ODM allows you to map PHP objects to MongoDB documents +and query MongoDB by using a builder API. This mapping enables you to +use other MongoDB features such as flexible schema design and advanced +searches. To learn more about this library, see the +:ref:`php-symfony-resources` section. + +.. _php-symfony-qs: + +Quick Start +----------- + +This tutorial shows you how to build a web application by using Symfony, a +PHP framework. It includes instructions on connecting to a MongoDB cluster hosted +on MongoDB Atlas and accessing and displaying data from your database. + +By using MongoDB as a data store in a Symfony web application, you can +leverage the document data model to build rich query expressions, +allowing you to easily interact with data. + +.. tip:: + + If you prefer to connect to MongoDB by using the MongoDB PHP Library without + Symfony, see `Connecting to MongoDB + `__ + in the MongoDB PHP Library documentation. + +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. + +This guide uses Doctrine ODM to allow you to map PHP objects to +MongoDB documents and query MongoDB by using a builder API. + +Follow the steps in this guide to create a sample Symfony web application +that connects to a MongoDB deployment and performs a query on the +database. + +Prerequisites +~~~~~~~~~~~~~ + +To create the Quick Start application, you need the following software +installed in your development environment: + +- `PHP `__ +- `Composer `__ +- `Symfony CLI `__ +- A terminal app and shell. For MacOS users, use Terminal or a similar app. + For Windows users, use PowerShell. + +.. _php-symfony-atlas-cluster: + +Create a MongoDB Atlas Cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must create a MongoDB cluster where you can store and manage your +data. Complete the :atlas:`Get Started with Atlas ` +guide to set up a new Atlas account and create a free tier MongoDB +cluster. This tutorial also demonstrates how to load sample datasets +into your cluster, including the data that is used in this tutorial. + +You provide instructions to the driver on where and how to connect to your +MongoDB cluster by providing it with a connection string. To retrieve +your connection string, follow the instructions in the :atlas:`Connect +to Your Cluster ` tutorial in the +Atlas documentation. + +.. tip:: + + Save your connection string in a secure location. + +Install MongoDB Extension +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To learn more about installing the MongoDB extension, see `Installing the Extension +`__ +in the PHP Library Manual. + +Initialize a Symfony Project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run the following command to create a skeleton Symfony project called +``restaurants``: + +.. code-block:: bash + + composer create-project symfony/skeleton restaurants + +Install PHP Driver and Doctrine ODM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enter your project directory, then add the MongoDB PHP driver and the +Doctrine ODM bundle to your application. The bundle integrates +the ODM library into Symfony so that you can read from and write objects +to MongoDB. Installing the bundle also automatically adds the driver to +your project. To learn more, see the :ref:`php-symfony-resources` section +of this guide. + +Run the following commands to install the ODM: + +.. code-block:: bash + + composer require doctrine/mongodb-odm-bundle + +.. tip:: + + After running the preceding commands, you might see the + following prompt: + + .. code-block:: bash + :copyable: false + + Do you want to execute this recipe? + + Select ``yes`` from the response options to add the ODM library to your + application. + +To ensure that Doctrine ODM is enabled in your project, verify that your +``config/bundles.php`` file contains the highlighted entry in the +following code: + +.. code-block:: php + :caption: config/bundles.php + :emphasize-lines: 3 + + return [ + // ... + Doctrine\Bundle\MongoDBBundle\DoctrineMongoDBBundle::class => ['all' => true], + ]; + +Configure the ODM +````````````````` + +In the ``config/packages`` directory, replace the contents of your +``doctrine_mongodb.yaml`` file with the following code: + +.. literalinclude:: /includes/php-frameworks/symfony/doctrine_mongodb.yaml + :caption: config/packages/doctrine_mongodb.yaml + :language: yaml + +Install Frontend Dependency +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This project uses ``twig``, the default template engine for Symfony, to +generate templates in this application. Run the following command to +install the ``twig`` bundle: + +.. code-block:: + + composer require symfony/twig-bundle + +.. note:: + + This step might result in an error message about unset environment + variables, but this issue is resolved in the following steps. + +Modify Project Files +~~~~~~~~~~~~~~~~~~~~ + +This section demonstrates how to modify the files in your +``restaurants`` project to create a Symfony web application that displays +restaurants that match the specified criteria. + +Set Environment Variables +````````````````````````` + +In the root directory, navigate to the ``.env`` file and define the +following environment variables to set your connection string and target +database: + +.. code-block:: none + :caption: .env + + ... + + MONGODB_URL= + MONGODB_DB=sample_restaurants + +To retrieve your connection string, see the +:ref:`php-symfony-atlas-cluster` step. + +Create Restaurant Entity and Controller +``````````````````````````````````````` + +Create the ``Restaurant.php`` file in the ``src/Document`` directory and +paste the following code to create an entity that represents documents in +the ``restaurants`` collection: + +.. literalinclude:: /includes/php-frameworks/symfony/Restaurant.php + :caption: src/Document/Restaurant.php + :language: php + +Next, create the ``RestaurantController.php`` file in the +``src/Controller`` directory and paste the following code to handle the +endpoints in your application: + +.. literalinclude:: /includes/php-frameworks/symfony/RestaurantController.php + :caption: src/Controller/RestaurantController.php + :language: php + +The controller file defines the ``index()`` method, which displays text on +the web app's front page. The file also defines the ``browse()`` method, +which finds documents in which the ``borough`` +field is ``'Queens'`` and the ``name`` field contains the string ``'Moon'``. +This method then displays the documents at the ``/restaurant/browse/`` route. The +``browse()`` method uses the ``QueryBuilder`` class to construct the query. + +Customize Templates +``````````````````` + +Next, create templates to customize the web app's appearance. + +Create the ``templates/restaurant`` directory and populate it with the +following files: + +- ``index.html.twig`` +- ``browse.html.twig`` + +Paste the following code into the ``index.html.twig`` file: + +.. literalinclude:: /includes/php-frameworks/symfony/index.html.twig + :caption: templates/restaurant/index.html.twig + :language: html + +Paste the following code into the ``browse.html.twig`` file: + +.. literalinclude:: /includes/php-frameworks/symfony/browse.html.twig + :caption: templates/restaurant/browse.html.twig + :language: html + +Start your Symfony Application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run the following command from the application root directory to start +your PHP built-in web server: + +.. code-block:: bash + + symfony server:start + +After the server starts, it outputs the following message: + +.. code-block:: none + :copyable: false + + [OK] Web server listening + The Web server is using PHP FPM 8.3.4 + http://127.0.0.1:8000 + +Open the URL http://127.0.0.1:8000/restaurant/browse in your web browser. +The page shows a list of restaurants and details about each of them, as +displayed in the following screenshot: + +.. figure:: /includes/php-frameworks/symfony/app_render.png + :alt: Restaurants web app screenshot + +Congratulations on completing the Quick Start tutorial! + +After you complete these steps, you have a Symfony web application that +connects to your MongoDB deployment, runs a query on the sample data, +and renders a retrieved result. + +.. _php-symfony-resources: + +Resources +--------- + +Learn more about Symfony and MongoDB by viewing the following resources: + +- `Build PHP Symfony Apps with MongoDB Atlas Workshop + `__ +- `Symfony Documentation `__ +- `Doctrine MongoDB ODM Documentation + `__ +- `Doctrine MongoDB Bundle Documentation + `__ + +.. + - `Doctrine MongoDB ODM GitHub Repository `__ + - `Doctrine MongoDB ODM Bundle GitHub Repository `__ diff --git a/source/php-libraries.txt b/source/php-libraries.txt index a7b4725c0..86dc40a34 100644 --- a/source/php-libraries.txt +++ b/source/php-libraries.txt @@ -68,6 +68,10 @@ Framework Integrations - Symfony + - :ref:`php-symfony-integration` describes the benefits of using MongoDB + as a data store in a Symfony application and includes a tutorial to + build a web application that uses this integration. + - You can configure the `Lock `__ and the `Session `__ to use MongoDB as a data store.