302 lines
8.2 KiB
ReStructuredText
302 lines
8.2 KiB
ReStructuredText
Getting Started
|
||
===============
|
||
|
||
Doctrine is a project that aims to handle the persistence of your
|
||
domain model in a non-interfering way. Non-relational or no-sql
|
||
databases like MongoDB give you flexibility of building data store
|
||
around your object model and not vise versa. You can read more on the
|
||
initial configuration and setup in :doc:`Introduction to MongoDB Object
|
||
Document Mapper <../reference/introduction>`. This section will give you a basic
|
||
overview of what could be accomplished using Doctrine MongoDB ODM.
|
||
|
||
Example Model: Simple Blog
|
||
--------------------------
|
||
|
||
To create the simplest example, let’s assume the following in a simple blog web application:
|
||
|
||
- Blog has a user.
|
||
- Blog user can make blog posts
|
||
|
||
A first prototype
|
||
-----------------
|
||
|
||
For the above mentioned example, something as simple as this could be modeled with plain PHP classes.
|
||
First define the ``User`` document:
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
|
||
namespace Documents;
|
||
|
||
class User
|
||
{
|
||
private $name;
|
||
private $email;
|
||
private $posts = array();
|
||
|
||
// ...
|
||
}
|
||
|
||
Now define the ``BlogPost`` document:
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
|
||
namespace Documents;
|
||
|
||
class BlogPost
|
||
{
|
||
private $title;
|
||
private $body;
|
||
private $createdAt;
|
||
|
||
// ...
|
||
}
|
||
|
||
Persistent Models
|
||
-----------------
|
||
|
||
To make the above classes persistent, all we need to do is provide Doctrine with some mapping
|
||
information so that it knows how to consume the objects and persist them to the database.
|
||
|
||
You can provide your mapping information in Annotations, XML, or YAML:
|
||
|
||
.. configuration-block::
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
|
||
|
||
/** @ODM\Document */
|
||
class User
|
||
{
|
||
/** @ODM\Id */
|
||
private $id;
|
||
|
||
/** @ODM\Field(type="string") */
|
||
private $name;
|
||
|
||
/** @ODM\Field(type="string") */
|
||
private $email;
|
||
|
||
/** @ODM\ReferenceMany(targetDocument="BlogPost", cascade="all") */
|
||
private $posts = array();
|
||
|
||
// ...
|
||
}
|
||
|
||
/** @ODM\Document */
|
||
class BlogPost
|
||
{
|
||
/** @ODM\Id */
|
||
private $id;
|
||
|
||
/** @ODM\Field(type="string") */
|
||
private $title;
|
||
|
||
/** @ODM\Field(type="string") */
|
||
private $body;
|
||
|
||
/** @ODM\Field(type="date") */
|
||
private $createdAt;
|
||
|
||
// ...
|
||
}
|
||
|
||
.. code-block:: xml
|
||
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping"
|
||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping
|
||
http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd">
|
||
<document name="Documents\User">
|
||
<field fieldName="id" id="true" />
|
||
<field fieldName="name" type="string" />
|
||
<field fieldName="email" type="string" />
|
||
<reference-many fieldName="posts" targetDocument="Documents\BlogPost">
|
||
<cascade>
|
||
<all/>
|
||
</cascade>
|
||
</reference-many>
|
||
</document>
|
||
</doctrine-mongo-mapping>
|
||
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping"
|
||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping
|
||
http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd">
|
||
<document name="Documents\BlogPost">
|
||
<field fieldName="id" id="true" />
|
||
<field fieldName="title" type="string" />
|
||
<field fieldName="body" type="string" />
|
||
<field fieldName="createdAt" type="date" />
|
||
</document>
|
||
</doctrine-mongo-mapping>
|
||
|
||
.. code-block:: yaml
|
||
|
||
Documents\User:
|
||
fields:
|
||
id:
|
||
type: id
|
||
id: true
|
||
name:
|
||
type: string
|
||
email:
|
||
type: string
|
||
referenceMany:
|
||
posts:
|
||
targetDocument: Documents\BlogPost
|
||
cascade: all
|
||
|
||
Documents\BlogPost:
|
||
fields:
|
||
id:
|
||
type: id
|
||
id: true
|
||
title:
|
||
type: string
|
||
body:
|
||
type: string
|
||
createdAt:
|
||
type: date
|
||
|
||
That’s it, we have our models, and we can save and retrieve them. Now
|
||
all we need to do is to properly instantiate the ``DocumentManager``
|
||
instance. Read more about setting up the Doctrine MongoDB ODM in the
|
||
:doc:`Introduction to MongoDB Object Document Mapper <../reference/introduction>`:
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
|
||
use Doctrine\MongoDB\Connection;
|
||
use Doctrine\ODM\MongoDB\Configuration;
|
||
use Doctrine\ODM\MongoDB\DocumentManager;
|
||
use Doctrine\ODM\MongoDB\Mapping\Driver\AnnotationDriver;
|
||
|
||
AnnotationDriver::registerAnnotationClasses();
|
||
|
||
$config = new Configuration();
|
||
$config->setProxyDir('/path/to/generate/proxies');
|
||
$config->setProxyNamespace('Proxies');
|
||
$config->setHydratorDir('/path/to/generate/hydrators');
|
||
$config->setHydratorNamespace('Hydrators');
|
||
$config->setMetadataDriverImpl(AnnotationDriver::create('/path/to/document/classes'));
|
||
|
||
$dm = DocumentManager::create(new Connection(), $config);
|
||
|
||
Usage
|
||
-----
|
||
|
||
Here is how you would use your models now:
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
|
||
// ...
|
||
|
||
// create user
|
||
$user = new User();
|
||
$user->setName('Bulat S.');
|
||
$user->setEmail('email@example.com');
|
||
|
||
// tell Doctrine 2 to save $user on the next flush()
|
||
$dm->persist($user);
|
||
|
||
// create blog post
|
||
$post = new BlogPost();
|
||
$post->setTitle('My First Blog Post');
|
||
$post->setBody('MongoDB + Doctrine 2 ODM = awesomeness!');
|
||
$post->setCreatedAt(new DateTime());
|
||
|
||
$user->addPost($post);
|
||
|
||
// store everything to MongoDB
|
||
$dm->flush();
|
||
|
||
.. note::
|
||
|
||
Note that you do not need to explicitly call persist on the ``$post`` because the operation
|
||
will cascade on to the reference automatically.
|
||
|
||
Now if you did everything correctly, you should have those two objects
|
||
stored in MongoDB in correct collections and databases. You can use the
|
||
`php-mongodb-admin project, hosted on github`_ to look at your
|
||
``BlogPost`` collection, where you will see only one document:
|
||
|
||
::
|
||
|
||
Array
|
||
(
|
||
[_id] => 4bec5869fdc212081d000000
|
||
[title] => My First Blog Post
|
||
[body] => MongoDB + Doctrine 2 ODM = awesomeness!
|
||
[createdAt] => MongoDate Object
|
||
(
|
||
[sec] => 1273723200
|
||
[usec] => 0
|
||
)
|
||
)
|
||
|
||
And the ``User`` collection would consist of the following:
|
||
|
||
::
|
||
|
||
Array
|
||
(
|
||
[_id] => 4bec5869fdc212081d010000
|
||
[name] => Bulat S.
|
||
[email] => email@example.com
|
||
[posts] => Array
|
||
(
|
||
[0] => Array
|
||
(
|
||
[$ref] => blog_posts
|
||
[$id] => 4bec5869fdc212081d000000
|
||
[$db] => test_database
|
||
)
|
||
)
|
||
)
|
||
|
||
You can retrieve the user later by its identifier:
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
|
||
// ...
|
||
|
||
$userId = '....';
|
||
$user = $dm->find('User', $userId);
|
||
|
||
Or you can find the user by name even:
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
|
||
$user = $dm->getRepository('User')->findOneByName('Bulat S.');
|
||
|
||
If you want to iterate over the posts the user references it is as easy as the following:
|
||
|
||
.. code-block:: php
|
||
|
||
<?php
|
||
|
||
$posts = $dm->getPosts();
|
||
foreach ($posts as $post) {
|
||
}
|
||
|
||
You will notice that working with objects is nothing magical and you only have access to the properties,
|
||
getters and setters that you have defined yourself so the semantics are very clear. You can continue
|
||
reading about the MongoDB in the :doc:`Introduction to MongoDB Object Document Mapper <../reference/introduction>`.
|
||
|
||
.. _php-mongodb-admin project, hosted on github: http://github.com/jwage/php-mongodb-admin
|