How to Use MongoDB (NoSQL) in Laravel

11 min readFeb 8, 2024

MongoDB is a popular NoSQL database that offers flexibility and scalability for web applications. Laravel, on the other hand, is a powerful PHP framework known for its elegant syntax and rich ecosystem. Combining MongoDB with Laravel can provide developers with a robust and efficient solution for building modern web applications.

MongoDB Roadmap - roadmap.sh

A step-by-step guide to learning MongoDB in 2024. We also have resources and short descriptions attached to the roadmap…

roadmap.sh

Prerequisites
Installing the Laravel MongoDB Package
Configuring the MongoDB Connection
Creating Eloquent Models for MongoDB Collections
Querying Data with Eloquent
Using Relationships in MongoDB Models
Implementing Authentication with MongoDB
Performing CRUD Operations with MongoDB
Working with Aggregations in MongoDB
Indexing and Performance Optimization
Migrating Data to MongoDB
Testing and Debugging

1. Prerequisites

Before diving into the integration of MongoDB with Laravel, there are a few prerequisites that need to be in place. Ensure that you have the following installed on your development environment:

PHP version 7.3 or above
Composer (PHP package manager)
MongoDB server
MongoDB PHP extension

You can install the MongoDB PHP extension by running the following command:

pecl install mongodb

If you encounter any issues during the installation, refer to the official PHP documentation for MongoDB installation instructions.

2. Installing the Laravel MongoDB Package

To integrate MongoDB with Laravel, we will use the jenssegers/mongodb package. This package extends the functionality of Laravel's Eloquent ORM to work seamlessly with MongoDB.

You can install the package by running the following command in your Laravel project directory:

composer require jenssegers/mongodb

Once the package is installed, Laravel will automatically discover and register the package’s service provider.

3. Configuring the MongoDB Connection

After installing the package, we need to configure the connection to our MongoDB server. Open the .env file in your Laravel project directory and update the following database-related variables:

DB_CONNECTION=mongodb
DB_HOST=127.0.0.1
DB_PORT=27017
DB_DATABASE=my_database
DB_USERNAME=
DB_PASSWORD=

Make sure to replace my_database with the name of your MongoDB database. If you have authentication enabled for your MongoDB server, provide the username and password accordingly.

Next, open the config/database.php file and add the following configuration to the connections array:

'mongodb' => [
    'driver' => 'mongodb',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', 27017),
    'database' => env('DB_DATABASE', 'my_database'),
    'username' => env('DB_USERNAME', ''),
    'password' => env('DB_PASSWORD', ''),
],

This configuration tells Laravel to use the MongoDB driver for the mongodb connection.

To test the connection, you can run the following command:

php artisan migrate

If the connection is successful, Laravel will migrate any pending database migrations to your MongoDB database.

4. Creating Eloquent Models for MongoDB Collections

In Laravel, models are used to interact with database tables. When working with MongoDB, we can create Eloquent models for corresponding collections. To get started, create a new model class in the app/Models directory. For example, let's create a Book model for a collection called books:

namespace App\Models;

use Jenssegers\Mongodb\Eloquent\Model;

class Book extends Model
{
    protected $collection = 'books';
}

By default, the MongoDB model class will use the pluralized lowercase version of the model name as the collection name. However, you can override this behavior by specifying the $collection property.

Now, you can use the Book model to perform CRUD operations on the books collection in MongoDB.

5. Querying Data with Eloquent

With Eloquent models for MongoDB collections in place, you can leverage the power of Laravel’s query builder to retrieve and manipulate data in MongoDB.

Basic Queries

To retrieve all records from a MongoDB collection, you can use the all method on the model:

$books = Book::all();

You can also use the find method to retrieve a single record by its primary key:

$book = Book::find('5f8e1c2e49ef4a001f000001');

To perform more complex queries, you can chain methods like where, orWhere, whereIn, etc. For example, to find books with a specific author:

$books = Book::where('author', 'John Doe')->get();

Advanced Queries

MongoDB offers a rich set of query operators that allow you to perform complex searches. With Laravel’s query builder, you can use these operators seamlessly. For example, to find books published after a certain date:

$books = Book::where('published_at', '>', '2021-01-01')->get();

You can also use the dot notation to query nested fields in MongoDB documents. For example, to find books with a specific tag:

$books = Book::where('tags.name', 'Adventure')->get();

Aggregations

MongoDB provides powerful aggregation capabilities to perform advanced calculations and transformations on your data. Laravel’s query builder includes methods to work with MongoDB aggregations. For example, to calculate the average rating of all books:

$averageRating = Book::avg('rating');

You can also use the groupBy method to group documents based on a specific field. For example, to group books by genre:

$booksByGenre = Book::groupBy('genre')->get();

6. Using Relationships in MongoDB Models

Just like in relational databases, you can define relationships between MongoDB models in Laravel. This allows you to establish associations and retrieve related records effortlessly.

One-to-One Relationships

To define a one-to-one relationship between two MongoDB models, you can use the hasOne and belongsTo methods. For example, let's assume we have a Author model and a Book model. Each book belongs to a single author, and an author can have multiple books:

namespace App\Models;

use Jenssegers\Mongodb\Eloquent\Model;

class Book extends Model
{
    public function author()
    {
        return $this->belongsTo(Author::class);
    }
}

class Author extends Model
{
    public function book()
    {
        return $this->hasOne(Book::class);
    }
}

With this relationship defined, you can easily access the author of a book or the book of an author:

$book = Book::find('5f8e1c2e49ef4a001f000001');
$author = $book->author;

$author = Author::find('5f8e1c2e49ef4a001f000002');
$book = $author->book;

One-to-Many Relationships

To define a one-to-many relationship, you can use the hasMany and belongsTo methods. For example, let's assume we have a Category model and a Book model. Each category can have multiple books, and a book belongs to a single category:

namespace App\Models;

use Jenssegers\Mongodb\Eloquent\Model;

class Book extends Model
{
    public function category()
    {
        return $this->belongsTo(Category::class);
    }
}

class Category extends Model
{
    public function books()
    {
        return $this->hasMany(Book::class);
    }
}

Now, you can easily access the books of a category or the category of a book:

$category = Category::find('5f8e1c2e49ef4a001f000003');
$books = $category->books;

$book = Book::find('5f8e1c2e49ef4a001f000001');
$category = $book->category;

Many-to-Many Relationships

To define a many-to-many relationship in MongoDB models, you can use the belongsToMany method. For example, let's assume we have a Book model and a Tag model. A book can have multiple tags, and a tag can be associated with multiple books:

namespace App\Models;

use Jenssegers\Mongodb\Eloquent\Model;

class Book extends Model
{
    public function tags()
    {
        return $this->belongsToMany(Tag::class);
    }
}

class Tag extends Model
{
    public function books()
    {
        return $this->belongsToMany(Book::class);
    }
}

With this relationship defined, you can easily access the tags of a book or the books associated with a tag:

$book = Book::find('5f8e1c2e49ef4a001f000001');
$tags = $book->tags;

$tag = Tag::find('5f8e1c2e49ef4a001f000004');
$books = $tag->books;

7. Implementing Authentication with MongoDB

Authentication is a crucial aspect of web applications. In Laravel, MongoDB can be used as the underlying database for user authentication. To implement authentication with MongoDB, follow these steps:

Step 1: Replace the Default User Model

In Laravel, the default user model is Illuminate\Foundation\Auth\User. To use MongoDB for authentication, you need to replace this model with the MongoDB-compatible model provided by the jenssegers/mongodb package.

Create a new User model in the app/Models directory, and make it extend the Jenssegers\Mongodb\Auth\User class:

namespace App\Models;

use Jenssegers\Mongodb\Auth\User as Authenticatable;

class User extends Authenticatable
{
    // Additional customizations and relationships
}

Step 2: Update the Authentication Configuration

Next, update the authentication configuration in the config/auth.php file. Change the model option under the providers.users section to point to your new User model:

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],
],

Step 3: Enable MongoDB Guard

In the same configuration file, update the guards.web section to use the MongoDB guard:

'guards' => [

    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'token',
        'provider' => 'users',
        'hash' => false,
    ],

    'mongodb' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

],

Step 4: Update the Authentication Middleware

If you have any middleware that performs authentication checks, make sure to update them to use the MongoDB guard. For example, in the app/Http/Kernel.php file, update the web middleware group:

protected $middlewareGroups = [

    'web' => [
        // Other middleware
        \Illuminate\Session\Middleware\AuthenticateSession::class,
        \App\Http\Middleware\EncryptCookies::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ],

    // Other middleware groups
];

Step 5: Migrate the Users Collection

If you haven’t already done so, run the database migration command to create the necessary tables or collections for user authentication:

php artisan migrate

This will create the users collection in your MongoDB database.

Now, you can use Laravel’s built-in authentication features with MongoDB as the underlying database.

8. Performing CRUD Operations with MongoDB

One of the key advantages of using MongoDB in Laravel is the flexibility it offers for performing CRUD (Create, Read, Update, Delete) operations. In this section, we will explore how to perform these operations on MongoDB collections using Laravel’s Eloquent ORM.

Creating Records

To create a new record in a MongoDB collection, you can use the create method on the corresponding Eloquent model. For example, let's create a new book:

$book = Book::create([
    'title' => 'The Great Gatsby',
    'author' => 'F. Scott Fitzgerald',
]);

This will save the new book record in the books collection.

Reading Records

To retrieve records from a MongoDB collection, you can use various methods provided by Eloquent. For example, to retrieve all books:

$books = Book::all();

To retrieve a specific book by its primary key:

$book = Book::find('5f8e1c2e49ef4a001f000001');

You can also use query builder methods to filter and sort the results. For example, to find books by a specific author:

$books = Book::where('author', 'John Doe')->get();

Updating Records

To update a record in a MongoDB collection, you can retrieve the model instance and modify its attributes. For example, to update the title of a book:

$book = Book::find('5f8e1c2e49ef4a001f000001');
$book->title = 'New Title';
$book->save();

Deleting Records

To delete a record from a MongoDB collection, you can call the delete method on the model instance. For example, to delete a book:

$book = Book::find('5f8e1c2e49ef4a001f000001');
$book->delete();

You can also use the destroy method to delete multiple records by their primary keys:

Book::destroy(['5f8e1c2e49ef4a001f000001', '5f8e1c2e49ef4a001f000002']);

9. Working with Aggregations in MongoDB

MongoDB provides powerful aggregation capabilities that allow you to perform complex data analysis and transformations. Laravel’s query builder includes methods to work with MongoDB aggregations seamlessly.

Basic Aggregations

To perform basic aggregations in MongoDB using Laravel’s query builder, you can use methods like count, sum, avg, min, and max. For example, to calculate the total number of books:

$totalBooks = Book::count();

To calculate the average rating of all books:

$averageRating = Book::avg('rating');

Grouping Documents

MongoDB’s aggregation framework allows you to group documents based on specific fields. Laravel’s query builder provides the groupBy method for this purpose. For example, to group books by genre:

$booksByGenre = Book::groupBy('genre')->get();

You can also use the sum method in conjunction with groupBy to calculate totals for each group. For example, to calculate the total sales for each category:

$totalSalesByCategory = Book::groupBy('category')->sum('sales');

Advanced Aggregations

MongoDB’s aggregation framework supports a wide range of operators and stages for performing advanced aggregations. Laravel’s query builder allows you to leverage these capabilities. For example, you can use the $match stage to filter documents before performing aggregations:

$highRatedBooks = Book::raw(function ($collection) {

    return $collection->aggregate([

        ['$match' => ['rating' => ['$gte' => 4.5]]],
        ['$group' => ['_id' => '$genre', 'count' => ['$sum' => 1]]],

    ]);

});

This example retrieves high-rated books by genre and counts the number of books in each genre.

10. Indexing and Performance Optimization

To ensure optimal performance when working with MongoDB in Laravel, it’s important to properly index your collections. Indexes help speed up query execution by allowing MongoDB to quickly locate and retrieve the requested data. Here are some tips for indexing and performance optimization:

Identify Query Patterns

Analyze the query patterns in your application to identify the most frequently executed queries. Focus on optimizing these queries by creating appropriate indexes.

Create Indexes

Use the createIndex method provided by Laravel's query builder to create indexes on your collections. For example, to create an index on the title field of the books collection:

Book::createIndex(['title' => 'text']);

This will create a text index that allows for efficient full-text search on the title field.

Monitor Query Performance

Regularly monitor the performance of your queries using MongoDB’s built-in profiling feature. This will help identify slow queries that may require optimization. You can enable profiling by setting the profile option in your MongoDB configuration.

Use Explain

Use the explain method provided by Laravel's query builder to get insights into the query execution plan. This can help identify inefficient queries and suggest improvements. For example:

$books = Book::where('author', 'John Doe')->explain();

11. Migrating Data to MongoDB

If you’re migrating an existing application from a relational database to MongoDB, you may need to transfer your data to the new database. Laravel provides a convenient way to perform data migrations using the php artisan migrate command.

To migrate data to MongoDB, you can create a new migration file and use Laravel’s database query builder to retrieve data from the source database and insert it into MongoDB collections. Here’s an example migration file:

use App\Models\Book;
use Illuminate\Support\Facades\DB;
use Illuminate\Database\Migrations\Migration;

class TransferDataToMongoDB extends Migration
{
    public function up()
    {
        $books = DB::table('books')->get();
        foreach ($books as $book) {
            Book::create((array) $book);
        }
    }
    public function down()
    {
        Book::truncate();
    }
}

In this example, we retrieve records from the books table in the source database and insert them into the books collection in MongoDB.

12. Testing and Debugging

Testing and debugging are essential parts of the development process. Laravel provides a comprehensive testing framework that allows you to write tests for your MongoDB-based applications.

You can use Laravel’s built-in testing features, such as PHPUnit and Laravel Dusk, to write unit tests and browser tests for your MongoDB models and controllers. These tests will help ensure that your application functions correctly and that your data interactions with MongoDB are working as expected.

For debugging purposes, you can use Laravel’s logging and debugging tools. Laravel allows you to log messages to various channels and provides convenient debugging methods like dd and dump. You can also use MongoDB's native logging capabilities to track queries and investigate performance issues.

The Power of Composition vs Inheritance

In the world of object-oriented programming (OOP), developers have long debated the advantages and disadvantages of two…

medium.com

Conclusion

Integrating MongoDB with Laravel opens up new possibilities for building powerful and scalable web applications. In this comprehensive guide, we have covered everything you need to know to get started with MongoDB in Laravel. From installation and configuration to querying, relationships, authentication, and optimization, you now have the knowledge and tools to leverage the full potential of MongoDB in your Laravel projects.

Next Step:: MongoDB indexing types:

1. Single field

2. Compound index

3. Multikey index

4. Text index

5. Hashed index

6. Geospatial index

MongoDB indexing tutorial with examples

Even if you haven't worked with MongoDB, you probably know that this database is used to work with big data which gives…

farshadth.medium.com

What is Sharding in MongoDB?

Nowadays we struggle with high volume and complexity of data, so it’s pretty important to develop a scalable project…