Boomgo, a micro PHP ODM for MongoDB
Boomgo still a work in progress and is initially developped for Retentio, (*1)
Boomgo is a light and simple Object Document Mapper on top of the MongoDB php native driver., (*2)
, (*3)
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, ...)., (*4)
In short, Boomgo offers a handy way to manipulate your MongoDB Documents with PHP Objects., (*5)
Features
Boomgo generate Mappers for your php object, which allow you to:, (*6)
- 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., (*7)
Installation
Composer
First, in your composer.json, add the requirement line for Boomgo., (*8)
{
"require": {
"retentio/boomgo": "dev-master"
}
}
Then get composer and run the install command., (*9)
$ wget -nc -nv http://getcomposer.org/composer.phar
$ php composer.phar install
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 :, (*10)
- A dedicated & unique namespace part for your persisted classes (default "Document").
- The "@Persistent" tag in the property docblock.
- Getter & Setter for this property.
Simple persistence
myField;
}
public function setMyField($value)
{
$this->myField = $value;
}
}
?>
Then, you can generate your mapper with the command (if you used composer):, (*11)
$ vendor/bin/boomgo generate:mappers path/to/your/document/folder
Boomgo will generate (default: aside of your documents folder) a mapper class called VendorName\Project\Mapper\MyPersistedClassMapper.
The mapper exposes 3 methods:, (*12)
->serialize($yourObject)->unserialize($yourArray)->hydrate($yourObject, $yourArray)
Then, the usage becomes really simple:, (*13)
setMyField('my value');
// Create the mapper
$mapper = new \VendorName\Project\Mapper\MyPersistedClassMapper();
// Serialize your object to a mongoable array
$mongoableArray = $mapper->serialize($object);
// Save with the native php driver
$mongo->selectDB('my_db')
->selectCollection('my_collection')
->save($mongoableArray);
// Fetch a result with the native driver
$result = $mongo->selectDB('my_db')
->selectCollection('my_collection')
->findOne(array('myField' => 'my value'));
// Unserialize the result to an object
$object = $mapper->unserialize($result);
$object->getMyField();
// You could also hydrate an existing object from a result
$object = new \VendorName\Project\Document\MyPersistedClass();
$mapper->hydrate($object, $result);
?>
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., (*14)
After mapper generation, usage is almost the same and stay explicit, Boomgo doesn't hide magic., (*15)
setId(new \MongoId());
$object->setMyField('my value');
$object->setMyArray(array('many','values'));
$object->setMyVar('anything');
$object->setEmbeddedDocument(new \VendorName\Project\Document\EmbeddedDocument());
$object->setEmbeddedCollection(array(new \VendorName\Project\Document\EmbeddedDocument()));
// Create the mapper
$mapper = new \VendorName\Project\Mapper\DocumentClassMapper();
// Serialize your object to a mongoable array
$mongoableArray = $mapper->serialize($object);
// Save with the native php driver
$mongo->selectDB('my_db')
->selectCollection('my_collection')
->save($mongoableArray);
// Fetch a result with the native driver
$result = $mongo->selectDB('my_db')
->selectCollection('my_collection')
->findOne(array('myField' => 'my value'));
// Unserialize the result to an object
$object = $mapper->unserialize($result);
?>
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., (*16)
Limitations
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., (*17)
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 !, (*18)
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, (*19)
$ php composer.phar install --dev --prefer-source
To run the complete test suite, open a shell and type :, (*20)
$ cd path/to/Boomgo
$ php vendor/bin/atoum -c .atoum.php -d tests
Want to test on a single class while contributing ? Here is an example with AnnotationParser class :, (*21)
$ php vendor/bin/atoum -c .atoum.php -f tests/Boomgo/Tests/Units/Parser/AnnotationParser.php
Framework integration
Boomgo already have integration for:, (*22)
Credits
Boomgo was built thanks to many open source projects & some awesome guys:, (*23)
Wallogit.com
