PHPackages                             chefsplate/laravel-doctrine-odm - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. chefsplate/laravel-doctrine-odm

ActiveLibrary[Database & ORM](/categories/database)

chefsplate/laravel-doctrine-odm
===============================

A smart, lightweight Laravel wrapper around Doctrine's mongodb-odm Document Mapper

1.0.0(9y ago)9544[1 issues](https://github.com/chefsplate/laravel-doctrine-odm/issues)[3 PRs](https://github.com/chefsplate/laravel-doctrine-odm/pulls)MITPHPPHP >=5.4.0

Since Feb 22Pushed 4y ago3 watchersCompare

[ Source](https://github.com/chefsplate/laravel-doctrine-odm)[ Packagist](https://packagist.org/packages/chefsplate/laravel-doctrine-odm)[ Docs](https://github.com/chefsplate/laravel-doctrine-odm)[ RSS](/packages/chefsplate-laravel-doctrine-odm/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (1)Dependencies (5)Versions (7)Used By (0)

Laravel Doctrine 2 ODM for MongoDB \[WIP\]
==========================================

[](#laravel-doctrine-2-odm-for-mongodb-wip)

A smart, lightweight Laravel wrapper around the [Doctrine ODM](https://github.com/doctrine/mongodb-odm) document mapper. Convenient features like soft deletions, automatic create and modification times, and consistent and flexible response formats (useful when developing APIs) are built in.

This ODM wrapper is compatible with jensseger's [laravel-mongodb](https://github.com/jenssegers/laravel-mongodb) library, should you want to leverage both Eloquent and Doctrine at the same time.

Note: a "minimum-stability" of "dev" is currently required for this package.

Please check out the [chefsplate/laravel-doctrine-odm-example](https://github.com/chefsplate/laravel-doctrine-odm-example) repo for a fully-working example of how this package can be used to create a Doctrine-based API on top of Mongo.

Table of contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Using the Eloquent-like wrapper methods](#eloquent-like-wrapper-methods)
- [IDE helper for generating phpDocumentation](#ide-helper-for-generating-phpdocumentation)
- [Response Formats](#response-formats)
- [References](#references)

Requirements
------------

[](#requirements)

- PHP 5.4+
- Laravel 5.3+ (for Laravel 5.1 - 5.2, please use the 5.1 branch)
- PHP mongo extension (ext-mongo) must be installed:
    - On a Mac, the easiest way to install this extension is through `brew`: `brew install php56` followed by `brew install php56-mongo`

Installation
------------

[](#installation)

Require the latest version of this package with Composer:

```
composer require chefsplate/laravel-doctrine-odm:"0.1.x"

```

Add the Service Provider to the providers array in `config/app.php`:

```
ChefsPlate\ODM\Providers\DocumentMapperServiceProvider::class,

```

Add the facade to your class aliases array in `config/app.php`:

```
'DocumentMapper' => ChefsPlate\ODM\Facades\DocumentMapper::class,

```

Ensure you have connection details for the **mongodb** driver setup in `config/database.php`. See `vendor/chefsplate/laravel-odm/config/database.php` for a more complete example.

```
'mongodb' => [
    'driver'        => 'mongodb',
    'dsn'           => 'mongodb://localhost:27017',
    'database'      => 'mydb', // Default DB to perform queries against (not authenticate against)
    'retryConnect'  => 2, // Number of connection retry attempts before failing (doctrine feature)
    'retryQuery'    => 1, // Number of query retry attempts before failing (doctrine feature)
    'options'       => [

    ],
    'driverOptions' => [

    ]
]

```

The format for the DSN is: `mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db`

Copy the default doctrine and ide-odm-helper config files to your app's config `cp vendor/chefsplate/laravel-odm/config/doctrine.php config/doctrine.php``cp vendor/chefsplate/laravel-odm/config/ide-odm-helper.php config/ide-odm-helper.php`Modify to suit your environment

Eloquent-like Wrapper Methods
-----------------------------

[](#eloquent-like-wrapper-methods)

`first` and `where`
-------------------

[](#first-and-where)

`first` is an Eloquent-like way of constructing queries. It uses the arrow (associative array) notation of specifying parameters:

```
$user = User::first([
    'username' => 'davidchchang'
]);

```

The `first` wrapper will automatically construct the query and fetch the first result returned, so if you want to retrieve more than one document or if you want to use specific query builder methods, you'll need to use `where` method instead.

```
$users_named_david_chang = User::where([
    'first_name' => 'David',
    'last_name' => 'Chang'
])->getQuery()->execute();

foreach ($users_named_david_chang as $user) {
    // do something with $user here
}

```

There is an additional caveat with using these wrapper methods; the `first` and `where` wrapper methods only work with non-entities such as strings, booleans, numbers, and regexes. If you want to use any (non-equals) [conditional operators](http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/query-builder-api.html#conditional-operators), you'll need to chain them before executing the query (note: `first` does not support chaining since it executes the query immediately).

```
$recent_user_tasks = Task::where([
    'status' => 'Active'
])->field('created_at')->gte(new \MongoDate($date->getTimestamp()))
  ->field('user')->references($user)
  ->getQuery()->execute();

```

### Projections

[](#projections)

Both `first` and `where` allow you to define an array of projections you would like returned. For example, if you only care about the username and email address fields being set on the returned models, you can specify this in the second parameter:

```
$users_named_david = User::where([
    'first_name' => new \MongoRegex('/^David/i')
], ['username', 'email']);

```

`find`
------

[](#find)

`find` will return the entity that corresponds to a specific ID.

```
$user = User::find("davidchchang");

```

IDE helper for generating phpDocumentation
------------------------------------------

[](#ide-helper-for-generating-phpdocumentation)

If you're familiar with [@barryvdh's IDE helper](https://github.com/barryvdh/laravel-ide-helper) for generating phpDocumentation (useful for auto-complete), we have built on top of his command generator.

To get started, add the Service Provider to the providers array in config/app.php:

```
ChefsPlate\ODM\Providers\IdeOdmHelperServiceProvider::class,

```

Usage
-----

[](#usage)

The default usage will analyze all models under `App\Entities` and write all annotations to a `_ide_helper_models.php` file.

```
php artisan ide-helper:doctrine-models

```

You can alternatively choose to write annotations directly to the PHP DocBlock class annotations within the PHP files themselves.

If the annotations contain duplicates, you can use the `--reset` option to replace existing DocBlock annotations:

```
php artisan ide-helper:doctrine-models --reset

```

Or specifically, to reset a single entity:

```
php artisan ide-helper:doctrine-models App\Entities\ModelName --reset

```

For complete usage on generating helper annotations, use `--help`:

```
php artisan ide-helper:doctrine-models --help

```

Response Formats
----------------

[](#response-formats)

If you are using our [Laravel API Response Formatter](https://github.com/chefsplate/laravel-api-response-formatter) (highly recommended with this package), you can leverage the built-in response format support, which allows you to customize which fields you want returned to the front-end from your APIs.

There are two simple steps you'll need to follow to make use of response formats in your code.

Step One: Define your response formats
--------------------------------------

[](#step-one-define-your-response-formats)

First, we define which fields in the model we want to have returned. For example, let's assume your user has the following fields: `id`, `username`, `first_name`, `last_name`, `email` and `password`. Upon returning a user object to the front-end, we don't ever want to return the `password` field. This can be done by creating a `default` response format within the `User.php` model:

```
protected static $response_formats = [
    'default' => ['password'],
]

```

The response format is a blacklist array of fields you ***don't*** want in the response. By default, all fields are returned.

So if you don't need the first name, last name or password, you would specify:

```
protected static $response_formats = [
    'default' => ['first_name', 'last_name', 'password'],
]

```

Note that this gets pretty cumbersome if there are more fields you don't want then the fields that you do want. As an alternative, you can specify to exclude all fields using the `*` symbol, and include only the ones you want using the special `|except:` syntax. This makes the response format behave more like a whitelist.

As an example:

```
'default'   => ['*|except:first_name,email'],

```

Which means, exclude everything except `first_name` and `email`.

### Multiple response formats for a model

[](#multiple-response-formats-for-a-model)

You can add as many named formats as you want here:

For example, if we wanted to add a new response format for formatting emails that only contains the user's first name and email address, we could do something like:

```
protected static $response_formats = [
    'default' => ['password'],
    'email'   => ['*|except:first_name,email'],
]

```

### Nested response formats

[](#nested-response-formats)

If your model references other models, you can form complex response formats that restrict what is returned by the referenced models. For example, if a `Project` model contains a reference to the `User` model, you can specify which user fields you want returned (again, all fields for each model are returned by default).

Within `Project.php`:

```
protected static $response_formats = [
    'listing_view' => ['created_at', 'updated_at', 'user.*|except:id,username'],
]

```

This example combines both exclusion and inclusion type filters. This corresponds to saying: don't return me the `created_at` and `updated_at` properties, and also don't return any of the `user` fields except `user.id` and `user.username`.

This allows for some very powerful nested response formats while maintaining simplicity in syntax.

Step Two: Inform your controller endpoints of which response formats to use
---------------------------------------------------------------------------

[](#step-two-inform-your-controller-endpoints-of-which-response-formats-to-use)

Now that the formats have been defined in the models, you can specify which models you would like to use when returning the payload back to the front-end.

Within your controller:

```
return (new ResponseObject($projects))
    ->setResponseFormatsForModels(
        [
            Project::class   => 'listing_view',
            User::class      => 'email',
        ]
    );

```

To demonstrate the power of response formats, consider the following:

Here `$projects` is an array of `Project`s, which contain references to `User`s and an embedded list of `Comment`s, and the `Comment` model references the `User` model. Since the response format for `Comment` is not defined here, `default`is assumed. If the `default` response format is not defined within `Comment.php`, then all fields will be returned.

However, since we specified the response format to use for `User`s, our API response formatter will format the `User`entity referenced within `Comment` using the `email` response format automatically. The `listing_view` on `Project` (as we described above) already indicates how it would like to format its `User`s references, so it is not formatted using the `email`response format.

ODM Helpers \[coming soon\]
---------------------------

[](#odm-helpers-coming-soon)

OdmHelper
---------

[](#odmhelper)

`convertCarbonToMongoDate` will convert a Carbon date to a Mongo date:

```
OdmHelper::convertCarbonToMongoDate(Carbon::parse('2016-11-17'))

```

References
----------

[](#references)

For more info see:

- [Using the PHP Library (PHPLIB)](http://php.net/manual/en/mongodb.tutorial.library.php)
- [Doctrine MongoDB ODM’s documentation](http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/)
- [chefsplate/laravel-doctrine-odm-example](https://github.com/chefsplate/laravel-doctrine-odm-example) for a fully-working example
- [PHP Annotations plug-in for PhpStorm](https://plugins.jetbrains.com/plugin/7320), compatible with Doctrine

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity16

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 91.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

3

Last Release

3353d ago

Major Versions

1.0.0 → 5.3.x-dev2017-03-08

### Community

Maintainers

![](https://www.gravatar.com/avatar/526f280d0f55551fca724c42675e9f336eebd47f83118863e7092abfc692ca02?d=identicon)[davidchchang](/maintainers/davidchchang)

---

Top Contributors

[![davidchchang](https://avatars.githubusercontent.com/u/451089?v=4)](https://github.com/davidchchang "davidchchang (55 commits)")[![thomasstevens89](https://avatars.githubusercontent.com/u/5810213?v=4)](https://github.com/thomasstevens89 "thomasstevens89 (3 commits)")[![mikaelmattsson](https://avatars.githubusercontent.com/u/2428696?v=4)](https://github.com/mikaelmattsson "mikaelmattsson (2 commits)")

---

Tags

laraveldoctrinemapperodmmongodbdocumentmongo

### Embed Badge

![Health badge](/badges/chefsplate-laravel-doctrine-odm/health.svg)

```
[![Health](https://phpackages.com/badges/chefsplate-laravel-doctrine-odm/health.svg)](https://phpackages.com/packages/chefsplate-laravel-doctrine-odm)
```

###  Alternatives

[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k7.2M71](/packages/mongodb-laravel-mongodb)[mmucklo/queue-bundle

Symfony2/3/4/5 Queue Bundle (for background jobs) supporting Mongo (Doctrine ODM), Mysql (and any Doctrine ORM), RabbitMQ, Beanstalkd, Redis, and ... {write your own}

120839.8k](/packages/mmucklo-queue-bundle)[leroy-merlin-br/mongolid

Easy, powerful and ultrafast ODM for PHP and MongoDB.

11234.3k4](/packages/leroy-merlin-br-mongolid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)