Download the PHP package retentio/boomgo without Composer

Boomgo, a micro PHP ODM for MongoDB

Boomgo still a work in progress and is initially developped for Retentio

Boomgo is a light and simple Object Document Mapper on top of the MongoDB php native driver.

Philosophy

Boomgo ODM focuses on the mapping process between PHP objects and MongoDB Documents, It doesn't abstract any feature provided by the native php driver. This way, Boomgo allows you to keep the full control about your MongoDB interactions (querying, map reduce, ...).

In short, Boomgo offers a handy way to manipulate your MongoDB Documents with PHP Objects.

Features

Boomgo generate Mappers for your php object, which allow you to:

• Hydrate PHP Object from a MongoDB results set.
• Serialize PHP Object to mongo-storable array.
• Handle hydration process of embedded document / collection.

Requirements

Boomgo was built with a lot of love (including best practices & standards). It will only work for PHP 5.3+ projects which use a structure matching PSR-0. Furthermore, composer usage is strongly encouraged.

Installation

Composer

First, in your composer.json, add the requirement line for Boomgo.

Then get composer and run the install command.

Usage

At the moment, Boomgo supports only annotation definition. Yet it uses only a single tag: by default "@Persistent" (you can change it). To persist some attributes of your model, Boomgo needs 3 things :

1. A dedicated & unique namespace part for your persisted classes (default "Document").
2. The "@Persistent" tag in the property docblock.
3. Getter & Setter for this property.

Simple persistence

Then, you can generate your mapper with the command (if you used composer):

Boomgo will generate (default: aside of your documents folder) a mapper class called VendorName\Project\Mapper\MyPersistedClassMapper. The mapper exposes 3 methods:

• ->serialize($yourObject)
• ->unserialize($yourArray)
• ->hydrate($yourObject, $yourArray)

Then, the usage becomes really simple:

Advanced persistence

Boomgo handles native PHP Mongo types (MongoId, etc.), embedded documents and nested collections. Since, Boomgo love simple & efficient things, annotation are not used for that. Instead it rely on... docblock with the famous under-used @var tag.

After mapper generation, usage is almost the same and stay explicit, Boomgo doesn't hide magic.

To see the full list of supported type/pseudo type in the @var tag you can look at Boomgo\Builder\Definition Note that Boomgo won't cast or validate anything, it's only used in the mapping process for normalization & nested documents/collections.

Limitations

• It doesn't & won't manage object relation for a simple reason: MongoDB is a NON-RELATIONAL storage.
• It doesn't & won't provide identity map etc.
• It doesn't & won't make coffee.

If you're looking for full-featured php ODM, you should look at Mandango which use active record/class generator implementation, and also Doctrine MongoDB ODM data-mapping implementation.

Known issues

• Only MongoId native type is supported, yet it's really easy to add and test other native type.
• Boomgo doesn't fit totally the PSR-0 (actually do not handle underscored class name)
• Boomgo formatters need improvement/refacto

Roadmap

• Provide a manager.
• Add functional tests.
• More parsers (yml, xml and json).
• ActiveRecord implementation.
• Provide more alternatives for mappers generation (like flat file structures).
• Document classes generation (getters & setters, JsonSerializable interface from php 5.4).
• Json document preview.
• Dynamic mapping using live discrimination.

Feel free to contribute !

How to run unit tests

Boomgo is unit tested with atoum, the dependency is not shipped by default, with composer you have to run the command

To run the complete test suite, open a shell and type :

Want to test on a single class while contributing ? Here is an example with AnnotationParser class :

Framework integration

Boomgo already have integration for:

• Symfony2 with PlemiBoomgoBundle

Credits

Boomgo was built thanks to many open source projects & some awesome guys:

• Atoum: the KISS framework for unit test.
• Composer: the awesome dependency manager.
• Symfony: the components lib is a time-saver.
• Twig Generator: the cool tool for code generation with twig.
• Doctrine, Mandango: ORM/ODM inspiration.
• @willdurand, helped me with a lot of tips.
• @jpetitcolas, regex master.
• @Palleas, ninja supporter forever.