An Object-Document Mapper (ODM) for Doctrine ORM leveraging new JSON types of modern RDBMS.
Did you ever dreamed of a tool creating powerful data models mixing traditional efficient relational mappings with modern schema-less and NoSQL-like ones?
With Doctrine JSON ODM, it's now possible to create and query such hybrid data models with ease. Thanks to modern JSON types of RDBMS, querying schema-less documents is easy, powerful and fast as hell (similar in performance to a MongoDB database)! You can even define indexes for those documents.
Doctrine JSON ODM allows to store PHP objects as JSON documents in modern dynamic columns of RDBMS. It works with JSON and JSONB columns of PostgreSQL (>= 9.4) and, soon, will support the JSON column of MySQL (>= 5.7.8).
For more information about concepts behind Doctrine JSON ODM, take a look at the presentation given by Benjamin Eberlei at Symfony Catalunya 2016.
The library comes with a bundle for the Symfony framework.
// ...
use Doctrine\Bundle\DoctrineBundle\DoctrineBundle;
use Dunglas\DoctrineJsonOdm\Bundle\DunglasDoctrineJsonOdmBundle;
use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
use Symfony\Component\HttpKernel\Kernel;
class AppKernel extends Kernel
{
public function registerBundles()
{
return [
new FrameworkBundle(),
new DoctrineBundle(),
new DunglasDoctrineJsonOdmBundle(),
// ...
];
}
// ...
}Doctrine JSON ODM can also be used standalone, without any framework, but the documentation hasn't been redacted yet (PRs welcome!).
Doctrine JSON ODM provides a json_document column type for properties of Doctrine entities.
The content of properties mapped with this type is serialized in JSON using the Symfony Serializer then, it is stored in a dynamic JSON column in the database.
When the object will be hydrated, the JSON content of this column is transformed back to its original values, thanks again to the Symfony Serializer. All PHP objects and structures will be preserved (if you use Symfony >= 3.1, see the FAQ).
You can store any type of (serializable) PHP data structures in properties mapped using the json_document type.
Example:
namespace AppBundle\Entity;
use Doctrine\ORM\Mapping as ORM;
/**
* This is a typical Doctrine ORM entity.
*
* @ORM\Entity
*/
class Foo
{
/**
* @ORM\Column(type="integer")
* @ORM\Id
* @ORM\GeneratedValue(strategy="AUTO")
*/
public $id;
/**
* @ORM\Column(type="string")
*/
public $name;
/**
* Can contain anything (array, objects, nested objects...).
*
* @ORM\Column(type="json_document", options={"jsonb": true})
*/
public $misc;
// Works with private and protected methods with getters and setters too.
}namespace AppBundle\Entity;
/**
* This is NOT an entity! It's a POPO (Plain Old PHP Object). It can contain anything.
*/
class Bar
{
public $title;
public $weight;
}namespace AppBundle\Entity;
/**
* This is NOT an entity. It's another POPO and it can contain anything.
*/
class Baz
{
public $name;
public $size;
}Store a graph of random object in the JSON type of the database:
// $entityManager = $this->get('doctrine')->getManagerForClass(\AppBundle/EntityFoo::class);
$bar = new Bar();
$bar->title = 'Bar';
$bar->weight = 12;
$baz = new Baz();
$baz->name = 'Baz';
$baz->size = 7;
$foo = new Foo();
$foo->name = 'Foo';
$foo->misc = [$bar, $baz]
$entityManager->persist($foo);
$entityManager->flush();Retrieve the object graph back:
$foo = $entityManager->find(Foo::class, $foo->getId());
var_dump($foo->misc); // Same as what we set earlierYou can execute complex queries using native queries. Checkout the PostgreSQL documentation to learn how to query the stored JSON document.
MySQL support is coming (see the FAQ).
What DBMS are supported?
Currently only PostgreSQL is supported. MySQL (>= 5.7.8) will be supported when the Pull Request doctrine/dbal#2266 will be merged.
How to use the JSONB type of PostgreSQL?
First, be sure to use Postgres >= 9.4, Doctrine ORM >= 2.6 (dev) and DBAL >= 2.6 (dev). Then, you need to set an option of in the column mapping:
// ...
/**
* @ORM\Column(type="json_document", options={"jsonb": true})
*/
public $foo;
// ...Does the ODM support nested objects and object graphs?
Yes.
Run the following commands in your shell to set mandatory environment variables:
export SYMFONY__POSTGRESQL_HOST=127.0.0.1
export SYMFONY__POSTGRESQL_USER=dunglas
export SYMFONY__POSTGRESQL_PASSWORD=
export SYMFONY__POSTGRESQL_DBNAME=my_test_db
The database must exist. Be careful, its content may be deleted.
Run the test suite using PHPUnit:
phpunit
This bundle is brought to you by Kévin Dunglas and awesome contributors. Sponsored by Les-Tilleuls.coop.