DOCSP-35892: Quick Start docs

docs/includes/quick-start/troubleshoot.rst

@@ -0,0 +1,7 @@
+.. 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:`Share Feedback` tab on the right or bottom right side of the
+   page.
+

docs/index.txt

@@ -13,7 +13,7 @@ Laravel MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   /install
+   /quick-start
    /eloquent-models
    /query-builder
    /user-authentication
@@ -37,11 +37,12 @@ Laravel Eloquent and Query Builder syntax to work with your MongoDB data.
    maintained by MongoDB, Inc. and is compatible with Laravel 10.x and
    later.
 
-Getting Started
----------------
+Quick Start
+-----------
 
-Learn how to install and configure your app to MongoDB by using the
-{+odm-short+} in the :ref:`laravel-install` section.
+Learn how to add {+odm-short+} to a Laravel web application, connect to
+MongoDB hosted on MongoDB Atlas, and begin working with data in the
+:ref:`laravel-quick-start` section.
 
 Fundamentals
 ------------
@@ -73,7 +74,7 @@ Reporting Issues
 We are lucky to have a vibrant PHP community that includes users of varying
 experience with MongoDB PHP Library and {+odm-short+}. To get support for
 general questions, search or post in the
-`MongoDB Community Forums <https://www.mongodb.com/community/forums/>`__.
+:community-forum:`MongoDB Community Forums <>`.
 
 To learn more about MongoDB support options, see the
 `Technical Support <https://www.mongodb.org/about/support>`__ page.

docs/quick-start.txt

@@ -0,0 +1,71 @@
+.. _laravel-quick-start:
+
+===========
+Quick Start
+===========
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: php framework, odm
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+This guide shows you how to add {+odm-long+} to a new Laravel web application,
+connect to a MongoDB cluster hosted on MongoDB Atlas, and how to perform
+read and write operations on the data.
+
+.. tip::
+
+   If you prefer to set up your development environment in GitHub Codespaces
+   or Docker, see the linked code repository in the
+   `How to Build a Laravel + MongoDB Back End Service <https://www.mongodb.com/developer/languages/php/laravel-mongodb-tutorial/>`__
+   MongoDB Developer Center tutorial.
+
+   You can learn how to set up a local Laravel development environment
+   and perform CRUD operations by taking the
+   :mdbu-course:`Getting Started with Laravel and MongoDB </getting-started-with-laravel-and-mongodb>`
+   MongoDB University Learning Byte.
+
+   If you prefer to connect to MongoDB by using the PHP Library driver without
+   Laravel, see `Connecting to MongoDB <https://www.mongodb.com/docs/php-library/current/tutorial/connecting/>`__
+   in the PHP Library documentation.
+
+{+odm-short+} extends the Laravel Eloquent and Query Builder syntax to
+store and retrieve data from MongoDB.
+
+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 the steps in this guide to create a sample Laravel web application
+that connects to a MongoDB deployment.
+
+.. tip::
+
+   You can download the complete web application project by cloning the
+   `laravel-quickstart <https://github.com/mongodb-university/laravel-quickstart>`__
+   GitHub repository.
+
+.. button:: Next: Download and Install
+   :uri: /quick-start/download-and-install/
+
+.. toctree::
+
+   /quick-start/download-and-install/
+   /quick-start/create-a-deployment/
+   /quick-start/create-a-connection-string/
+   /quick-start/configure-mongodb/
+   /quick-start/view-data/
+   /quick-start/write-data/
+   /quick-start/next-steps/
+

docs/quick-start/configure-mongodb.txt

@@ -0,0 +1,56 @@
+.. _laravel-quick-start-connect-to-mongodb:
+
+=================================
+Configure Your MongoDB Connection
+=================================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: test connection, runnable, code example
+
+.. procedure::
+   :style: connected
+
+   .. step:: Set the Connection String in the Database Configuration
+
+      Open the ``database.php`` file in the ``config`` directory and
+      set the default database connection to ``mongodb`` as shown
+      in the following line:
+
+      .. code-block:: php
+
+         'default' => env('DB_CONNECTION', 'mongodb'),
+
+      Add the following highlighted ``mongodb`` entry to the ``connections`` array
+      in the same file. Replace the ``<connection string>`` placeholder with the
+      connection string that you copied from the :ref:`laravel-quick-start-connection-string`
+      step in the following code example:
+
+      .. code-block:: php
+         :emphasize-lines: 2-6
+
+         'connections' => [
+           'mongodb' => [
+             'driver' => 'mongodb',
+             'dsn' => env('DB_URI', '<connection string>'),
+             'database' => 'sample_mflix',
+           ],
+
+         // ...
+
+      .. step:: Add the Laravel MongoDB Provider
+
+         Open the ``app.php`` in the ``config`` directory and
+         add the following entry into the ``providers`` array:
+
+         .. code-block::
+
+            MongoDB\Laravel\MongoDBServiceProvider::class,
+
+.. include:: /includes/quick-start/troubleshoot.rst
+
+.. button:: Next: View Sample MongoDB Data
+   :uri: /quick-start/view-data/

docs/quick-start/create-a-connection-string.txt

@@ -0,0 +1,63 @@
+.. _laravel-quick-start-connection-string:
+
+==========================
+Create a Connection String
+==========================
+
+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.
+
+To connect to an instance or deployment not hosted on Atlas, see the
+:manual:`Connection Strings </reference/connection-string/>` in the Server
+manual.
+
+.. 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 <laravel-quick-start-create-deployment>`,
+      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
+
+      Proceed to the :guilabel:`Connect your application` section and 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:`Password (SCRAM)` authentication mechanism.
+
+      Deselect the :guilabel:`Include full driver code example` to view
+      the connection string.
+
+   .. step:: Copy your Connection String
+
+      Click the button on the right of the connection string to copy it
+      to your clipboard.
+
+   .. step:: Update the Placeholders
+
+      Paste this connection string into a file in your preferred text editor
+      and replace the ``<username>`` and ``<password>`` 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
+contains your database username and password.
+
+.. include:: /includes/quick-start/troubleshoot.rst
+
+.. button:: Next: Configure Your MongoDB Connection
+   :uri: /quick-start/configure-mongodb/

docs/quick-start/create-a-deployment.txt

@@ -0,0 +1,37 @@
+.. _laravel-quick-start-create-deployment:
+
+===========================
+Create a MongoDB Deployment
+===========================
+
+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 </getting-started?tck=docs_driver_laravel>`
+      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.
+
+.. 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:`Share Feedback`
+   tab on the right or bottom right side of this page.
+
+.. button:: Next: Create a Connection String
+   :uri: /quick-start/create-a-connection-string/