Get Started with Laravel MongoDB

Install the MongoDB PHP Extension

Laravel MongoDB requires the MongoDB PHP Extension to manage MongoDB connections and commands. To learn how to install the MongoDB PHP Extension, see the Install the MongoDB PHP extension step of the Get Started with the PHP Library guide.

Install Laravel

Ensure that the version of Laravel you install is compatible with the version of the Laravel Integration. To learn which versions are compatible, see the Compatibility page.

Run the following command to install Laravel:

composer global require laravel/installer

When the installation completes, the command outputs the following message:

Using version ^<version number> for laravel/installer

Create a Laravel application

Run the following command to generate a new Laravel web application called my-app:

laravel new my-app

When the installation completes, the command outputs the following message:

INFO  Application ready in [my-app]. You can
start your local development using:
➜ cd my-app
➜ php artisan serve
New to Laravel? Check out our bootcamp and documentation.
Build something amazing!

Add a Laravel application encryption key

Navigate to the application directory you created in the previous step:

cd my-app

Run the following command to add the Laravel application encryption key, which is required to encrypt cookies:

php artisan key:generate

Add Laravel MongoDB to the dependencies

Run the following command to add the Laravel MongoDB dependency to your application:

composer require mongodb/laravel-mongodb:^5.8

When the installation completes, verify that the composer.json file includes the following line in the require object:

"mongodb/laravel-mongodb": "^5.8"

After completing these steps, you have a new Laravel project with the Laravel Integration dependencies installed.

Create a free MongoDB deployment on Atlas

Complete the MongoDB Get Started guide to set up a new Atlas account and load sample data into a new free tier MongoDB deployment. Follow the instructions in the Cloud Deployment tabs to create your MongoDB Atlas deployment in the cloud.

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.

Find your MongoDB Atlas connection string.

To retrieve your connection string for the deployment that you created in the previous step, log in to your Atlas account and navigate to the Clusters page under the Database section. Click the Connect button for your new deployment.

If you do not already have a database user configured, MongoDB will prompt you to create and configure a new user.

Click the Drivers button under Connect to your application and select "PHP" from the Driver selection menu and the version that best matches the version you installed from the Version selection menu.

Ensure the View full code sample option is deselected to view only the connection string.

Copy your connection string.

Click the copy icon on the right of the connection string to copy it to your clipboard as shown in the following screenshot:

Update the password placeholder.

Paste this connection string into a file in your preferred text editor and replace the <db_password> placeholder with your database user's password. The connection string is already populated with your database user's username.

Save this file to a safe location for use in the next step.

Configure the application environment variable file

Copy the .env.example file to a file named .env in the project root directory by running the following shell command:

cp .env.example .env

Open the .env file and add or edit the following variables and values. Replace the <connection string> placeholder with your connection string from the Create a Connection String step:

DB_CONNECTION=mongodb
DB_URI="<connection string>"

For example, if your connection string is "mongodb+srv://myUser:myPass123@mongo0.example.com/", your DB_URI variable matches the following line:

DB_URI="mongodb+srv://myUser:myPass123@mongo0.example.com/"

Set the connection string in the database configuration

Open the database.php file in the config directory and set the default database connection to the DB_CONNECTION environment variable as shown in the following line:

'default' => env('DB_CONNECTION'),

Add the following highlighted mongodb entry to the connections array in the same file:

'connections' => [
  'mongodb' => [
    'driver' => 'mongodb',
    'dsn' => env('DB_URI'),
    'database' => 'sample_mflix',
  ],
],
// ...

Add the Laravel Integration provider

Open the providers.php file in the bootstrap directory and add the following entry into the array:

MongoDB\Laravel\MongoDBServiceProvider::class,

Create a model and controller

Create a model called Movie to represent data from the sample movies collection in your MongoDB database and the corresponding resource controller by running the following command:

php artisan make:model Movie -cr

When the command completes, it outputs the following message:

INFO  Model [app/Models/Movie.php] created successfully.
INFO  Controller [app/Http/Controllers/MovieController.php]
created successfully.

Edit the model to use the Laravel Integration

Open the Movie.php model in your app/Models directory and make the following edits:

• Replace the Illuminate\Database\Eloquent\Model import with MongoDB\Laravel\Eloquent\Model

• Specify "mongodb" in the $connection field

The edited Movie.php file contains the following code:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Movie extends Model
{
    protected $connection = 'mongodb';
}

Add a controller function

Open the MovieController.php file in your app/Http/Controllers directory. Replace the show() function with the following code to retrieve results that match a database query and render it in the view:

public function show()
{
    return view('browse_movies', [
        'movies' => Movie::where('runtime', '<', 60)
            ->where('imdb.rating', '>', 8.5)
            ->orderBy('imdb.rating', 'desc')
            ->take(10)
            ->get()
    ]);
}

Add a web route

Open the web.php file in the routes directory. Add an import for the MovieController and a route called browse_movies as shown in the following code:

<?php
// ...
use App\Http\Controllers\MovieController;
Route::get('/browse_movies/', [MovieController::class, 'show']);

Generate a view

Run the following command from the application root directory to create a view that displays movie data:

php artisan make:view browse_movies

After you run the command, it outputs the following message:

INFO  View [resources/views/browse_movies.blade.php] created
successfully.

Open the browse_movies.blade.php view file in the resources/views directory. Replace the contents with the following code and save the changes:

<!DOCTYPE html>
<html>
<head>
   <title>Browse Movies</title>
</head>
<body>
<h2>Movies</h2>
@forelse ($movies as $movie)
  <p>
    Title: {{ $movie->title }}<br>
    Year: {{ $movie->year }}<br>
    Runtime: {{ $movie->runtime }}<br>
    IMDB Rating: {{ $movie->imdb['rating'] }}<br>
    IMDB Votes: {{ $movie->imdb['votes'] }}<br>
    Plot: {{ $movie->plot }}<br>
  </p>
@empty
    <p>No results</p>
@endforelse
</body>
</html>

Optionally, view your results as JSON documents

Rather than generating a view and editing the browse_movies.blade.php file, you can use the toJson() method to display your results in JSON format.

Replace the show() function with the following code to retrieve results and return them as JSON documents:

public function show()
{
    $results = Movie::where('runtime', '<', 60)
        ->where('imdb.rating', '>', 8.5)
        ->orderBy('imdb.rating', 'desc')
        ->take(10)
        ->get();
    return $results->toJson();
}

Start your Laravel application

Run the following command from the application root directory to start your PHP built-in web server:

php artisan serve

After the server starts, it outputs the following message:

INFO  Server running on [http://127.0.0.1:8000].
Press Ctrl+C to stop the server

View the movie data

Open the URL http://127.0.0.1:8000/browse_movies in your web browser. The page shows a list of movies and details about each of them.

Implement the function to insert data

Replace the store() method in the MovieController.php file, located in the app/Http/Controllers directory with the following code:

public function store(Request $request)
{
    $data = $request->all();
    $movie = new Movie();
    $movie->fill($data);
    $movie->save();
}

Add an API route that calls the controller function

Generate an API route file by running the following command:

php artisan install:api

Import the controller and add an API route that calls the store() method in the routes/api.php file:

use App\Http\Controllers\MovieController;
// ...
Route::resource('movies', MovieController::class)->only([
    'store'
]);

Update the model fields

Update the Movie model in the app/Models directory to specify the fields that the fill() method populates as shown in the following code:

class Movie extends Model
{
     protected $connection = 'mongodb';
     protected $fillable = ['title', 'year', 'runtime',
         'imdb', 'plot'];
}

Post a request to the API

Create a file called movie.json and insert the following data:

{
  "title": "The Laravel MongoDB Quick Start",
  "year": 2024,
  "runtime": 15,
  "imdb": {
    "rating": 9.5,
    "votes": 1
  },
  "plot": "This movie entry was created by running through
      the Laravel MongoDB Quick Start tutorial."
}

Send the JSON payload to the endpoint as a POST request by running the following command in your shell:

curl -H "Content-Type: application/json" \
  --data @movie.json \
  http://localhost:8000/api/movies

View the data

Open http://127.0.0.1:8000/browse_movies in your web browser to view the movie information that you submitted. The inserted movie appears at the top of the results.