Authentication With Laravel and MongoDB

Thank you very much for joining me for this tutorial, where you’ll learn how to set up user authentication for Laravel and MongoDB. We start by setting up a local development environment, going over some changes to the files, and finally, having a complete basic authentication running with MongoDB.

#Setting up the environment

Laravel is a PHP web framework, which makes it easy to build standardised web applications. In this tutorial, we set up PHP, Laravel, and MongoDB on macOS.

We start off by installing PHP, Composer, and the Laravel Installer with the following terminal commands:

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

This bash script is going to extend your PATH environment variable with the path to all necessary commands. If you see an error like this…

ERROR  Unknown shell. Defaulting to update ~/.profile.

…you might want to do this manually. In my case, I’m using the fish shell, so it is done with this command:

fish_add_path /Users/[YOUR-USERNAME]/.config/herd-lite/bin

Just make sure all necessary commands are working by executing:

php -r "phpinfo();" | grep "Loaded Configuration File"

The output should give you the loaded configuration file for PHP. If this points to your path extension from above, you’re good to go!

Let’s go quickly through the versions I used in this tutorial:

php -v
# PHP 8.4.1 (cli) (built: Nov 21 2024 09:02:06) (NTS)
# Copyright (c) The PHP Group
# Zend Engine v4.4.1, Copyright (c) Zend Technologies
#     with Zend OPcache v8.4.1, Copyright (c), by Zend Technologies
 
composer -v
#    ______
#   / ____/___  ____ ___  ____  ____  ________  _____
#  / /   / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/
# / /___/ /_/ / / / / / / /_/ / /_/ (__  )  __/ /
# \____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
#                     /_/
# Composer version 2.8.3 2024-11-17 13:13:04
 
laravel -v
# Laravel Installer 5.14.0

All the commands above should work and give you roughly the same versions I used.

To compile Laravel’s frontend assets, you need either Node and NPM or Bun. Please follow the official instructions on how to install these:

• Node and NPM
• Bun

#Creating the Laravel application

Now that the development environment is set up, we use the Laravel Installer to create our Laravel application skeleton. Please change the directory to where you want the application to be created and execute:

laravel new mongodb-auth-app

Answer the questions like this:

Which starter kit would you like to install?
React
 
Which authentication provider do you prefer?
Laravel's built-in authentication
 
Which testing framework do you prefer?
PHPUnit
 
Would you like to run npm install and npm run build?
Yes

Now that the application skeleton is created and all frontend dependencies are installed and built, let’s change to the application directory and have a look:

cd mongodb-auth-app

The application directory structure should look like this:

app/
artisan*
bootstrap/
composer.json
composer.lock
config/
database/
node_modules/
package-lock.json
package.json
phpunit.xml
public/
README.md
resources/
routes/
storage/
tests/
vendor/
vite.config.js

Start your Laravel application with composer run dev.

Now, point your browser to http://localhost:8000/ and you’ll see your Laravel application. It should look like this:

It’s time to set up MongoDB.

#Setting up a local MongoDB database

MongoDB is a document-oriented database, developed by MongoDB Inc. It was released in February 2009 and has gained massive popularity since—not just because of its schemaless design, which makes development and software iterations fast, but its powerful MongoDB query language.

MongoDB can easily be deployed as a standalone or in a replica set with three nodes. Horizontal scaling is done by a process called sharding.

Let’s get MongoDB up and running locally.

The easiest and best maintained way to install MongoDB on macOS is homebrew, I find. Homebrew is the missing package manager for macOS. If you lack Homebrew, please install it via the official website and documentation.

Homebrew offers formulae for all major MongoDB versions, starting with version 4.4. In case you want only the latest release, use the mongodb/brew/mongodb-community formula. Otherwise, go with mongodb/brew/mongodb-community@8.0. At time of writing, mongodb/brew/mongodb-community installs MongoDB version 8.2.0.

There are formulae for the MongoDB shell, and database tools as well. These are installed automatically as dependencies to mongodb/brew/mongodb-community.

Install MongoDB now:

brew install mongodb/brew/mongodb-community

After you’ve installed MongoDB, you can either start MongoDB as a service with…

brew services start mongodb/brew/mongodb-community

…or run it in a terminal window with:

/usr/local/opt/mongodb-community/bin/mongod --config /usr/local/etc/mongod.conf

I’ve done this tutorial on my MacBook Pro with Apple Silicon, but my initial Homebrew setup is many years old. It might be that your path starts with /opt/homebrew. Please check your installation.

PRO-TIP: Change your MongoDB config file, and comment out the systemLog section:

#systemLog:
#  destination: file
#  path: /usr/local/var/log/mongodb/mongo.log
#  logAppend: true

This shows you all MongoDB logs directly in the terminal. I use iTerm2 and added a MongoDB profile with the above command. Now, if I quickly need to spin up MongoDB, I start the profile, a new terminal tab appears, and I can see everything that is going on with MongoDB.

#Connecting your Laravel application to MongoDB

Now that you’ve got a Laravel application and MongoDB running, let’s connect them. First, install the Laravel MongoDB package with the following command:

composer require mongodb/laravel-mongodb

The laravel-mongodb package is officially maintained by MongoDB, and while MongoDB is natively supported by PHP through the MongoDB Driver, the Laravel MongoDB package provides a richer integration with Eloquent and other Laravel features.

Should you get problems with version mismatch of dependencies, add something like --ignore-platform-req=ext-mongodb to the above command.

Add your MongoDB connection string and database name to the .env file:

DB_CONNECTION=mongodb
DB_QUEUE_CONNECTION=mongodb
DB_URL=mongodb://localhost:27017
DB_DATABASE=mongodb_auth_app
CACHE_STORE=mongodb

Register the database connection in config/database.php:

'mongodb' => [
    'driver' => 'mongodb',
    'dsn' => env('DB_URL', 'mongodb://localhost:27017'),
    'database' => env('DB_DATABASE', 'laravel_app'),
],

Change [connections][database][driver] from “database” to “mongodb” in config/queue.php.

Register the cache store in config/cache.php like so:

'mongodb' => [
    'driver' => 'mongodb',
    'connection' => 'mongodb',
],

And finally, add the MongoDB Service Provider to bootstrap/providers.php:

<?php
 
return [
    App\Providers\AppServiceProvider::class,
    App\Providers\FortifyServiceProvider::class,
    MongoDB\Laravel\MongoDBServiceProvider::class,
];

Because we started with SQLite during the creation of our Laravel application earlier, all default tables were created in that database. Therefore, it is worthwhile at that point in time to create them in MongoDB, as well. Execute this command to do so:

php artisan migrate

Congratulations! Your Laravel application uses MongoDB now.

NOTE: Should you get a duplicate key error while trying to log in, use the MongoDB shell or MongoDB Compass to remove the “key_1” index on the “cache” collection. The Laravel MongoDB integration uses the “_id” field as the key field.

Same for the “id_1” index on the “sessions” collection.

#User authentication with MongoDB

Laravel comes with user authentication out of the box, but the scope of existing components varies depending on the Starter Kit you choose during the creation of the application. Do you remember? We chose the React Starter Kit. This means that we’ve got not just the necessary backend components but all frontend components, like login, signup, and “forgot password” forms, as well.

Laravel’s default database is SQLite. Therefore, all authentication functions work with that database out of the box. Let’s change that to MongoDB.

#Install the official Laravel MongoDB client library

This was done in the previous step already, by installing the mongodb/laravel-mongodb package.

#Modify the Laravel user model

Now that we run on MongoDB, we want to change the built-in user model accordingly:

Navigate to app/Models/User.php and change use Illuminate\Foundation\Auth\User as Authenticatable; to use MongoDB\Laravel\Auth\User as Authenticatable;.

That’s really all you need to do to switch Laravel user authentication to MongoDB. Please open your browser to http://localhost:8000/ and register a new user account. This user should be stored in the users collection of your local MongoDB instance.

#Create the auth controller

We started this little tutorial on Laravel React Starter Kit, which means that we’re set without creating a separate user controller. The login is handled by app/Http/Controllers/Auth/AuthenticatedSessionController.php::store(), and logout by app/Http/Controllers/Auth/AuthenticatedSessionController.php::destroy().

The public and restricted routes are handled by guest and auth route groups in routes/auth.php. Have a look to understand the concept better.

Should you ever want to implement a user controller yourself, you’ll find a barebones one in the MongoDB documentation.

#Password reminders via MongoDB

Password reminders work out of the box if you’ve made all the changes described in this tutorial and given that you use roughly the same versions as I did.

#HTTP sessions with MongoDB

Laravel gives you many options when it comes to where to store your user sessions. You can store them into the filesystem, cookies, database, redis, memcached, and many more.

#Configure MongoDB as the session driver

Same as with password reminders, when following this tutorial precisely, all HTTP sessions should be stored in MongoDB automatically. The collection is called sessions.

Laravel removes expired sessions automatically after 120 minutes through some kind of garbage collector. Nevertheless, should you want more control over HTTP sessions in MongoDB, please add the MongoDB session driver.

PRO-TIP: Use a MongoDB time-to-live (TTL) index on your sessions and let MongoDB handle the garbage collection and not PHP.

You can implement this by changing your config/session.php to:

<?php return [
    'driver' => 'mongodb',
    'connection' => 'mongodb',
    'table' => 'sessions',
    'lifetime' => null,
    'options' => [
        'time_field' => 'time'
    ]
];

Add a TTL index on time like so:

db.session.createIndex(
   { "time": 1 },
   { expireAfterSeconds: 7200 } // session expires after 120 minutes
);

#Conclusion and takeaways

The popular PHP web framework Laravel can be used with MongoDB. Thanks to the official Laravel integration for MongoDB, implementing user authentication is a breeze.

Follow this tutorial closely and your Laravel application, whether a new or existing one, will use MongoDB in no time for your user data, password reset tokens, and HTTP sessions.

Please keep in mind that relying on an ORM of any kind might affect your non-relational database performance in a negative way.