mongodb/laravel-mongodb: MongoDB Eloquent Models for Laravel

What mongodb/laravel-mongodb actually replaces

Laravel ships an ORM, Eloquent, that assumes a relational database behind it. If you want to store documents in MongoDB but keep writing Eloquent code, you otherwise rewrite every model, query and relationship by hand against the MongoDB PHP driver. This package removes that rewrite. It extends the original Laravel classes, and the README states the library "uses exactly the same methods", so a model that extends the package's base class queries MongoDB through the same fluent interface you already know.

The audience is specific: PHP teams on Laravel who have chosen MongoDB for the shape of their data, not teams who inherited a MySQL schema and want to move it sideways. If your tables are normalized and your queries are joins, this package will not make that model work better. It makes a document model usable from Laravel without dropping to the raw driver.

The package was previously known as Jenssegers MongoDB, and the README notes it was renamed to mongodb/laravel-mongodb after a transfer of ownership to MongoDB, Inc. That history matters when you read older tutorials: the class names and install instructions in pre-rename articles may not match what you get from Packagist today.

How the Eloquent-to-MongoDB bridge is built

The package lives in src/ and extends Laravel's model and query builder classes rather than wrapping them. That is the architectural decision that defines everything else: because it subclasses the framework's own components, the method surface is Laravel's, and the query builder translates the fluent calls into MongoDB operations instead of SQL. The README makes the claim directly: "This library extends the original Laravel classes, so it uses exactly the same methods."

The practical consequence is that the abstraction is leaky in one direction only. Laravel-shaped code works; MongoDB-shaped concepts that have no SQL equivalent need their own methods, and the documentation site (linked from the README at mongodb.com/docs/drivers/php/laravel-mongodb/) is where those live. The README itself does not enumerate them.

The repository also carries a docker-compose.yml that starts an app container and a mongodb service. The database service uses the image mongodb/mongodb-atlas-local:8 and exposes port 27017, with a healthcheck that runs mongosh --quiet --eval 'db.runCommand("ping").ok'. The app container sets MONGODB_URI to mongodb://mongodb/ and waits for that healthcheck before starting. That tells you the maintainers test against a real server, and it gives you a working local topology to copy.

Running mongodb/laravel-mongodb against a local server

The README does not print a composer require line, but the package name is unambiguous from the repository and the Packagist badge: mongodb/laravel-mongodb. The README states compatibility with Laravel 10.x and points older Laravel versions at the 3.9 branch.

The package needs the MongoDB PHP extension, not just the Composer library. The repository's Dockerfile shows what that means in practice: it installs the extension with pecl and enables it before Composer is copied in:

RUN apt-get update && \
    apt-get install -y autoconf pkg-config libssl-dev git unzip libzip-dev zlib1g-dev && \
    pecl install mongodb && docker-php-ext-enable mongodb && \
    pecl install xdebug && docker-php-ext-enable xdebug && \
    docker-php-ext-install -j$(nproc) zip

If your own environment lacks the extension, the package will install but the connection will fail at runtime. For a first real use you need a running server, and the repository's own compose file is the shortest path to one:

services:
    mongodb:
        container_name: mongodb
        image: mongodb/mongodb-atlas-local:8
        ports:
            - "27017:27017"
        healthcheck:
            test: mongosh --quiet --eval 'db.runCommand("ping").ok'

With that service up, point Laravel at it. The compose file's app service uses this exact value, so it is the value to mirror in your configuration:

environment:
    MONGODB_URI: 'mongodb://mongodb/'

Once the connection is configured, your work is a model that extends the package's Eloquent base class instead of Laravel's. At that point the query methods you write are the ones you already use; the difference is what they execute against. The README does not walk through a model definition, so treat the linked documentation site as the source for the base class name and connection config keys rather than guessing them.

Where this package stops being the right tool

The most honest limitation is structural, not a bug. Eloquent's relationship methods imply joins and referential integrity. MongoDB does not enforce foreign keys, and the package cannot add a guarantee the server does not offer. If your application depends on the database rejecting an orphaned row, this stack will not do it for you. Validation moves into application code, and application code can be bypassed.

There is a second boundary around migrations. The related searches show people looking for Laravel MongoDB migrations, which suggests an expectation the package does not obviously meet in the same way a SQL migration does. A SQL migration changes a schema the database enforces. A document store has no such schema to alter, so migration tooling here is a different kind of thing, and the README does not describe it at all.

Version compatibility is a real constraint you should read before anything else. The README names Laravel 10.x, and sends older versions to the 3.9 branch. If you are on a newer Laravel than the README covers, that is not documented here, and you should confirm support before planning around it.

Finally, the README does not document rollback, and it does not document what happens to an in-flight query when the server is unreachable. Those are the questions to answer from the linked documentation, not from this page.

The alternative: raw driver versus this Eloquent layer

The genuine alternative is the MongoDB PHP driver used directly, without Laravel's ORM in between. The difference in approach is the whole point of the package. The driver gives you a MongoDB-native API: you build queries as arrays and receive results as arrays or BSON documents, and nothing pretends the store is relational. There is no model class, no attribute casting, no relationship method that quietly issues a second query.

Choosing the driver means more code for CRUD and no Eloquent conveniences, but it also means no translation layer to reason about when a query behaves unexpectedly. When a MongoDB feature has no SQL analogue, the driver exposes it plainly; through an Eloquent subclass you depend on the package having a method for it.

The trade-off is legibility. A team fluent in Laravel reads Eloquent code faster than driver code, and the package's value is that fluency carrying over. A team fluent in MongoDB will find the driver more direct. Neither is wrong; they optimize for different existing skills.

Licence, releases and the cost of upgrading

The package is MIT licensed, which permits commercial use and modification. That is the licence identifier in the repository; the README does not add terms beyond it. Nothing here is legal advice, and if your organisation has licence review, MIT is the fact to bring to it.

Release cadence is visible and recent: 5.11.0 on 2026-09-10, 5.10.0 on 2026-09-02, and 5.9.1 on 2026-07-28. The last push to the repository was on 2026-09-10, and the repository is not archived, so the 5.x branch is where current work happens.

Upgrade cost is the part the README does not price for you. It documents a release-integrity process: releases are created automatically and the tag is signed with the PHP team's GPG key, which you import and then check in a local clone. The README adds a blunt note that Composer does not support verifying signatures as part of its installation process. So if signature verification matters to you, it is a manual step you own, not something a package install does for you.

gpg --import php-driver.asc

git show --show-signature 4.4.0

There is no documented support window, no stated deprecation policy for the 5.x line, and no migration guide for moving between minor versions in the README. Budget for reading the linked documentation at each upgrade rather than assuming compatibility.

What to check before you commit to it

Confirm three things in order. First, your Laravel version against the README's stated compatibility of 10.x, since that is the only version the README names. Second, that the mongodb PHP extension is present in every environment you deploy to, because the Dockerfile's pecl install mongodb step is a build-time requirement, not a Composer one. Third, whether the features you need are documented at the linked documentation site, because the README is short and defers to it.

If you want a local environment that matches what the maintainers test against, the repository's docker-compose.yml is the reference: mongodb/mongodb-atlas-local:8 on port 27017, MONGODB_URI set to mongodb://mongodb/, and a mongosh ping healthcheck gating the app container. Copying that topology removes a class of connection problems before you write a single model.

Editorial conclusion

Adopt mongodb/laravel-mongodb when your data is document-shaped and you want Eloquent's API over it, and when you are on Laravel 10.x, the version the README names as compatible. Do not adopt it if you need joins, foreign-key enforcement or a schema the database itself validates; those are SQL guarantees this package does not provide. Before committing, verify the Laravel version you run against the README's compatibility note, confirm the mongodb PHP extension is installed, and check the tag signature with git show --show-signature, since Composer does not verify signatures during installation.

Frequently asked questions

Official sources

1. License: MIT
2. mongodb/laravel-mongodb on GitHub
3. Project website
4. README
5. Releases