Doctrine MongoDB Object Document Mapper

Tags: Doctrine2, mongodb, odm

Posted 4 months ago by jwage

A question asked to me many times by many different people over the last year is, "will Doctrine ever have any support for MongoDB?". I have never really had an answer because we haven't had any official plans to support it as it was so new to the database world and php so nobody really knew much about it yet.

A few weekends ago I decided to install MongoDB and give it a try. It was pretty fun and interesting. I quickly learned that it being a document based storage system lends itself well to a object mapper so the experimental Doctrine MongoDB Object Document Mapper was born.

Introducing Doctrine MongoDB Object Document Mapper (ODM)

Much like the Doctrine 2 ORM, the ODM aims to provide transparent persistence for PHP 5.3.0+ objects. You will notice that the Doctrine 2 ORM and ODM infrastructure, style, interfaces, etc. are all very similar. Instead of an EntityManager like in the ORM you have the DocumentManager. Map your objects in the same way you do for the ORM. Here is an examle User document:

<?php

/** @Document(db="my_db", collection="users") */
class User
{
    /** @Id */
    private $id;

    /** @String */
    private $username;

    /** @String */
    private $password;

    // ...
}

Now like you would expect you can create new instances and persist them to Mongo:

<?php

$user = new User();
$user->setUsername('jwage');
$user->setPassword('testing');

$dm->persist($user);
$dm->flush();

Now if you have a look in MongoDB you will see a database named my_db and a collection named users containing a new document like the following:

array(
  '_id' => instanceof MongoId,
  'username' => 'jwage',
  'password' => 'testing'
)

When you query for and retrieve this document from the database later, Doctrine reconstructs the PHP object with the data from MongoDB:

<?php

$user = $dm->findOne('User', array('username' => 'jwage')); // instanceof User
echo $user->getUsername();

Below you can find an overview list of the features available:

  • Transparent persistence.
  • Map one or many embedded documents.
  • Map one or many referenced documents.
  • Create references between documents in different databases.
  • Map documents with Annotations, XML, YAML or plain old PHP code.
  • Documents can be stored on the MongoGridFS.
  • Collection per class(concrete) and single collection inheritance supported.
  • Map your Doctrine 2 ORM Entities to the ODM and use mixed data stores.
  • Inserts are performed using MongoCollection::batchInsert()
  • Updates are performed using $set instead of saving the entire document.

Getting Started?

We've put together a little documentation to help you get familiar with the ODM quickly.

How can I contribute?

Get your fork on! All you need to do is fork a Doctrine repository on github.com and submit your modifications to us by sending a pull request.

You can also take part in discussions on our mailing list or join #doctrine on irc.freenode.net for live support from the community.


Comments (25) [ add comment ]

Amazing Posted by Anton Onyshchenko about 4 months ago.

This is really amazing news!!! Thank you!

It would be great if stable version of this mapper will be released someday with Doctrine2.

deleted comment Posted by jwage about 4 months ago.

The original 2nd comment on this blog post was accidentally deleted, but here is the reply:

"this looks interesting, but in what cases would I need to use a non-relational database? serious question, I've been following the buzz about NoSQL/Mongo etc, but no one has actually explained why it's needed."

The decision to use a relational database or something like Mongo is a complicated decision. It depends on lots of different factors about your project (size, type, scale, load, etc.). I would suggest just reading up on Mongo and document based storage systems in general. If you google around and read a bit you will find lots of good different articles about mongodb, comparing it to mysql, etc.

DQL Posted by J Philip about 4 months ago.

Do you plan on supporting a flavor of DQL for MongoDB?

@jphilip Posted by jwage about 4 months ago.

I thought about it, but I don't think it is necessary. The API for interacting with Mongo is already so simple and just required php array key value pairs. I think DQL would just complicate things and would be an unnecessary layer.

@jphilip Posted by romanb about 4 months ago.

The main reason something like DQL probably makes no sense for MongoDB is that there is no equivalently powerful query language like SQL for mongo. The Mongo querying capabilities can be fully covered by simple php arrays, apparently, so this can map easily to how you query in PHP. This is not the case with relational databases where the main query capability is the almighty and extremely flexible SQL and DQL is the OO layer for that.

what about object query language ? Posted by Stoyan about 4 months ago.

I think something like PHPLinq would be more usefull and adequate for Doctrine MongoDB. I'd like to hear the opinion of the doctrine core devs about this.

@Stoyan Posted by jwage about 4 months ago.

We don't need any kind of major abstraction for querying. MongoDB already works this way and we just need to use regular old PHP arrays. We have the Query object which gives you everything you need.

<?php

$query = $dm->createQuery('User')
  ->where('username', 'jwage');

Default database?! Posted by Sebastian Hoitz about 4 months ago.

Hi!

I have implemented the Doctrine ODM into my current project. However, I ran into some problems:

Why do I have to specify a database in my Documents? And if I don't specify one, why does the ODM use doctrine instead?

What is the reason for this? Shouldn't you much rather be able to use a database you previously configured?

The PHP MongoDB extension supports this:

mongodb://user:pass@host/database

So why do you overwrite this? I have to use a customizable database for my project, since I want to install several instances of this project on my server (think of it as SaaS). They can not all share the same database??

Greetings from Germany, Sebastian

@Sebastian Posted by jwage about 4 months ago.

We can fix this. Expect a commit soon. When you specify a dsn like that and specify a database, is it possible to get the name of the default database or how do I select that default database specified in the dsn?

@jwage Posted by Sebastian Hoitz about 4 months ago.

Hum... I did not find a way to get the database name from the DSN with the Mongo object.

It seems like you have to create the connection and authenticate using the DSN (users are per database, so you have to specify the database, as it is only used for authentication), and then select the database using selectDB and provide the database name again.

That means you have to parse the DSN to get the database name, I think.

@Sebastian Posted by jwage about 4 months ago.

Check the latest code in git. I added a way to configure the default DB to use and removed the default of "doctrine" and you must always either specify a default database or specify one on the document.

@jwage Posted by Sebastian Hoitz about 4 months ago.

Wow, thank you very much. I will test that addition tomorrow. Thanks! :)

Symfony plugin Posted by J Philip about 4 months ago.

Hi Jon,

Thank you, this should simplify development as there is no more need to keep the application's schema synchronised with one in the DB. However the application will be fully responsible to enforce constraints, validation, integrity... Have you thought of having a Symfony plugin with validator classes and form, filter and module generator?

@JPhilip Posted by jwage about 4 months ago.

Symfony is working on a generic object validation component that Doctrine ORM, ODM and Symfony forms will use.

Any plans for other NoSQL support? Posted by harold about 4 months ago.

This is awesome.

Have you guys got any plans to support any other NoSQL products like Cassandra?

@harold Posted by jwage about 4 months ago.

Hi, the only one we've discussed to implement next is possibly CouchDB. The thing is, it all depends on whether or not PHP has native support for it. I don't think we have a driver for CouchDB or Cassandra yet.

CouchDB Posted by romanb about 4 months ago.

Well, CouchDB is just HTTP/REST, so no special driver needed. I've no idea about Cassandra but it looks very interesting.

@jwage cassandra driver Posted by harold about 3 months ago.

Cassandra uses Thrift to manage messaging between clients and servers. Unless I'm mistaken there is a PHP module for Thrift.

I'm using Scribe, another FB project that uses Thrift. When I compiled the Scribe source, it built the PHP module. I just had a quick search for it, and I don't think I ever actually installed the PHP module. But Thrift still handles communication -- perhaps not quite as efficiently as if I'd installed the PHP module.

Cassandra/Thrift Posted by @jperras about 3 months ago.

The Thrift PHP extension exports two methods that the generated Thrift interface will utilize if present. The extension is only meant to speed up the serialization process, and is thus not required for development/testing, but is recommended for any kind of production-level setup.

SVN Posted by mg about 3 months ago.

Hello,

Would it be possible to put ODM on svn.doctrine-project.org? I'm having trouble to hook svn:externals from github (authentication issues).

Thank you

@mg Posted by jwage about 3 months ago.

What are the issues? We will be eliminating SVN completely so that is not an option. We should figure out what your problems are with github so you can use it.

Thanks, Jon

Another inheritance type? Posted by Sebastian Hoitz about 3 months ago.

Hello Jon,

I'm currently running into some trouble.

I have a document which is set up like this:

post: - id - date - messages: [ 0: - type: a - subject: Foo - message: Bar 1: - type: b - subject: Foo - attachment: c ]

This is just a small example to clarify what I mean.

I have one model for the post. This embeds many messages, which itself discriminates using the field "type".

However, I can not get this to work, and I think this is caused by the inheritance type.

I set it to SINGLE_COLLECTION. So I have two models, message_a and message_b both extending my message model.

But for some reason, Doctrine does not give me the message_a or message_b classes, but just message classes, even when I configured the discrimination part for my message model.

Is this an error on my side, a bug or a feature not implemented yet?

Thanks, Sebastian

@Sebastian Posted by @jwage about 3 months ago.

Can we take the discussion somewhere other than comments? You can use the mailing or ping me in IRC.

http://www.doctrine-project.org/community

Thanks, Jon

read-only SVN Posted by mg about 3 months ago.

Hi Jwage,

Issue is that github does not support subdirectories when using svn checkout/externals and I it is not possible link to lib/ODM directly. Only way I to use it now is to download whole project .zip and copy the folder manually into project (+ again upload all to svn)

After github: "You cannot checkout parts of a repo (such as subdirectories) or branches other than the default branch on GitHub (yet)."

Isn't it possible to mirror ODM like you do with svn.doctrine-project.org ?

Thanks, Marcin

@mg Posted by jwage about 3 months ago.

Hi,

svn.doctrine-project.org is being phased out so we will not add anything new to it. We have fully moved over to github for all of our source control.

  • Jon

Create Comment