Skip to content

Commit e5634ac

Browse files
author
Chris Cho
authored
Merge pull request #2721 from ccho-mongodb/DOCSP-35892-quick-start-docs
DOCSP-35892: Quick Start docs
2 parents 7c1d0ab + 6c5b1f7 commit e5634ac

12 files changed

+655
-88
lines changed

‎docs/includes/figures/atlas_connection_select_cluster.png

34.6 KB
Loading

‎docs/includes/quick-start/troubleshoot.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. note::
2+
3+
If you run into issues, ask for help in the
4+
:community-forum:`MongoDB Community Forums <>` or submit feedback by using
5+
the :guilabel:`Share Feedback` tab on the right or bottom right side of the
6+
page.
7+

‎docs/index.txt

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Laravel MongoDB
1313
:titlesonly:
1414
:maxdepth: 1
1515

16-
/install
16+
/quick-start
1717
/eloquent-models
1818
/query-builder
1919
/user-authentication
@@ -37,11 +37,12 @@ Laravel Eloquent and Query Builder syntax to work with your MongoDB data.
3737
maintained by MongoDB, Inc. and is compatible with Laravel 10.x and
3838
later.
3939

40-
Getting Started
41-
---------------
40+
Quick Start
41+
-----------
4242

43-
Learn how to install and configure your app to MongoDB by using the
44-
{+odm-short+} in the :ref:`laravel-install` section.
43+
Learn how to add {+odm-short+} to a Laravel web application, connect to
44+
MongoDB hosted on MongoDB Atlas, and begin working with data in the
45+
:ref:`laravel-quick-start` section.
4546

4647
Fundamentals
4748
------------
@@ -73,7 +74,7 @@ Reporting Issues
7374
We are lucky to have a vibrant PHP community that includes users of varying
7475
experience with MongoDB PHP Library and {+odm-short+}. To get support for
7576
general questions, search or post in the
76-
`MongoDB Community Forums <https://www.mongodb.com/community/forums/>`__.
77+
:community-forum:`MongoDB Community Forums <>`.
7778

7879
To learn more about MongoDB support options, see the
7980
`Technical Support <https://www.mongodb.org/about/support>`__ page.

‎docs/install.txt

Lines changed: 0 additions & 82 deletions
This file was deleted.

‎docs/quick-start.txt

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
.. _laravel-quick-start:
2+
3+
===========
4+
Quick Start
5+
===========
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: php framework, odm
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 1
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
This guide shows you how to add the {+odm-long+} to a new Laravel web
24+
application, connect to a MongoDB cluster hosted on MongoDB Atlas, and perform
25+
read and write operations on the data.
26+
27+
.. tip::
28+
29+
If you prefer to set up your development environment in GitHub Codespaces
30+
or Docker, see the linked code repository in the
31+
`How to Build a Laravel + MongoDB Back End Service <https://www.mongodb.com/developer/languages/php/laravel-mongodb-tutorial/>`__
32+
MongoDB Developer Center tutorial.
33+
34+
You can learn how to set up a local Laravel development environment
35+
and perform CRUD operations by viewing the
36+
:mdbu-course:`Getting Started with Laravel and MongoDB </getting-started-with-laravel-and-mongodb>`
37+
MongoDB University Learning Byte.
38+
39+
If you prefer to connect to MongoDB by using the PHP Library driver without
40+
Laravel, see `Connecting to MongoDB <https://www.mongodb.com/docs/php-library/current/tutorial/connecting/>`__
41+
in the PHP Library documentation.
42+
43+
{+odm-short+} extends the Laravel Eloquent and Query Builder syntax to
44+
store and retrieve data from MongoDB.
45+
46+
MongoDB Atlas is a fully managed cloud database service that hosts your
47+
MongoDB deployments. You can create your own free (no credit card
48+
required) MongoDB Atlas deployment by following the steps in this guide.
49+
50+
Follow the steps in this guide to create a sample Laravel web application
51+
that connects to a MongoDB deployment.
52+
53+
.. tip::
54+
55+
You can download the complete web application project by cloning the
56+
`laravel-quickstart <https://github.com/mongodb-university/laravel-quickstart>`__
57+
GitHub repository.
58+
59+
.. button:: Next: Download and Install
60+
:uri: /quick-start/download-and-install/
61+
62+
.. toctree::
63+
64+
/quick-start/download-and-install/
65+
/quick-start/create-a-deployment/
66+
/quick-start/create-a-connection-string/
67+
/quick-start/configure-mongodb/
68+
/quick-start/view-data/
69+
/quick-start/write-data/
70+
/quick-start/next-steps/
71+

‎docs/quick-start/configure-mongodb.txt

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.. _laravel-quick-start-connect-to-mongodb:
2+
3+
=================================
4+
Configure Your MongoDB Connection
5+
=================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: test connection, runnable, code example
13+
14+
.. procedure::
15+
:style: connected
16+
17+
.. step:: Set the connection string in the database configuration
18+
19+
Open the ``database.php`` file in the ``config`` directory and
20+
set the default database connection to ``mongodb`` as shown
21+
in the following line:
22+
23+
.. code-block:: php
24+
25+
'default' => env('DB_CONNECTION', 'mongodb'),
26+
27+
Add the following highlighted ``mongodb`` entry to the ``connections`` array
28+
in the same file. Replace the ``<connection string>`` placeholder with the
29+
connection string that you copied from the :ref:`laravel-quick-start-connection-string`
30+
step in the following code example:
31+
32+
.. code-block:: php
33+
:emphasize-lines: 2-6
34+
35+
'connections' => [
36+
'mongodb' => [
37+
'driver' => 'mongodb',
38+
'dsn' => env('DB_URI', '<connection string>'),
39+
'database' => 'sample_mflix',
40+
],
41+
42+
// ...
43+
44+
.. step:: Add the Laravel MongoDB provider
45+
46+
Open the ``app.php`` file in the ``config`` directory and
47+
add the following entry into the ``providers`` array:
48+
49+
.. code-block::
50+
51+
MongoDB\Laravel\MongoDBServiceProvider::class,
52+
53+
After completing these steps, your Laravel web application is ready to
54+
connect to MongoDB.
55+
56+
.. include:: /includes/quick-start/troubleshoot.rst
57+
58+
.. button:: Next: View Sample MongoDB Data
59+
:uri: /quick-start/view-data/

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. _laravel-quick-start-connection-string:
2+
3+
==========================
4+
Create a Connection String
5+
==========================
6+
7+
You can connect to your MongoDB deployment by providing a
8+
**connection URI**, also called a *connection string*, which
9+
instructs the driver on how to connect to a MongoDB deployment
10+
and how to behave while connected.
11+
12+
The connection string includes the hostname or IP address and
13+
port of your deployment, the authentication mechanism, user credentials
14+
when applicable, and connection options.
15+
16+
To connect to an instance or deployment not hosted on Atlas, see
17+
:manual:`Connection Strings </reference/connection-string/>` in the Server
18+
manual.
19+
20+
.. procedure::
21+
:style: connected
22+
23+
.. step:: Find your MongoDB Atlas connection string
24+
25+
To retrieve your connection string for the deployment that
26+
you created in the :ref:`previous step <laravel-quick-start-create-deployment>`,
27+
log in to your Atlas account. Then, navigate to the
28+
:guilabel:`Database` section and click the :guilabel:`Connect` button
29+
for your new deployment.
30+
31+
.. figure:: /includes/figures/atlas_connection_select_cluster.png
32+
:alt: The connect button in the clusters section of the Atlas UI
33+
34+
Proceed to the :guilabel:`Connect your application` section. Select
35+
"PHP" from the :guilabel:`Driver` selection menu and the version
36+
that best matches the version you installed from the :guilabel:`Version`
37+
selection menu.
38+
39+
Select the :guilabel:`Password (SCRAM)` authentication mechanism.
40+
41+
Deselect the :guilabel:`Include full driver code example` option to view
42+
the connection string.
43+
44+
.. step:: Copy your connection string
45+
46+
Click the button on the right of the connection string to copy it
47+
to your clipboard.
48+
49+
.. step:: Update the placeholders
50+
51+
Paste this connection string into a file in your preferred text editor
52+
and replace the ``<username>`` and ``<password>`` placeholders with
53+
your database user's username and password.
54+
55+
Save this file to a safe location for use in the next step.
56+
57+
After completing these steps, you have a connection string that
58+
contains your database username and password.
59+
60+
.. include:: /includes/quick-start/troubleshoot.rst
61+
62+
.. button:: Next: Configure Your MongoDB Connection
63+
:uri: /quick-start/configure-mongodb/

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.. _laravel-quick-start-create-deployment:
2+
3+
===========================
4+
Create a MongoDB Deployment
5+
===========================
6+
7+
You can create a free tier MongoDB deployment on MongoDB Atlas
8+
to store and manage your data. MongoDB Atlas hosts and manages
9+
your MongoDB database in the cloud.
10+
11+
.. procedure::
12+
:style: connected
13+
14+
.. step:: Create a free MongoDB deployment on Atlas
15+
16+
Complete the :atlas:`Get Started with Atlas </getting-started?tck=docs_driver_laravel>`
17+
guide to set up a new Atlas account and load sample data into a new free
18+
tier MongoDB deployment.
19+
20+
.. step:: Save your credentials
21+
22+
After you create your database user, save that user's
23+
username and password to a safe location for use in an upcoming step.
24+
25+
After completing these steps, you have a new free tier MongoDB deployment on
26+
Atlas, database user credentials, and sample data loaded into your database.
27+
28+
.. include:: /includes/quick-start/troubleshoot.rst
29+
30+
.. button:: Next: Create a Connection String
31+
:uri: /quick-start/create-a-connection-string/

0 commit comments

Comments
 (0)