Initial commit
This commit is contained in:
@@ -0,0 +1,301 @@
|
||||
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
|
||||
Reference in New Issue
Block a user