Doctrine MongoDB Object Document Mapper

Doctrine
MongoDB Object Document Mapper (ODM)

Doctrine MongoDB ODM www.doctrine-project.org www.sensiolabs.org

What is Doctrine?


What is Doctrine?
• Open source PHP project started in 2006

• Relational database abstraction layer.
• mysql, oracle, pgsql, sqlite, etc.

• Object persistence layers for RDBMS,
MongoDB, etc.

• Other database related functionalities.
http://www.doctrine-project.org

What is MongoDB?
• Key-Value document based storage
system.

• Bridge between traditional relational
databases and key-value data stores.

http://www.mongodb.org


Terminology

RDBMS MongoDB
Database Database

Table Collection

Row Document


Using MongoDB in PHP


Connecting

$mongo = new Mongo('mongodb://localhost');


Selecting Databases

$db = $mongo->selectDB('dbname');


Selecting Collections

$db = $mongo->selectDB('dbname');
$coll = $db->selectCollection('users');


Inserting Documents
Insert a new user document and echo the newly generated id

$user = array(
'username' => 'jwage',
'password' => md5('changeme')
'active' => true
);
$coll->insert($user);

echo $user['_id'];


Updating Documents
Update username and password and save the whole document

$user = $coll->findOne(array('username' => 'jwage'));
$user['username'] = 'jonwage';
$user['password'] = md5('newpassword');
$coll->save($user);


Atomic Updates
• Faster than saving the entire document.

• Safer than updating the entire document.

• Updates are done in place and are atomic.


Atomic Updates
Update username and password where username is jwage

$coll->update(array(
'username' => 'jwage'
), array(
'$set' => array(
'username' => 'jonwage',
'password' => md5('newpassword')
)
));


Atomic Updates
Many other atomic operators exist for manipulating a documents data

• $inc - increments field by the number value
• $set - sets field to value
• $unset - deletes a given field
• $push - appends value to an array
• $pushAll - appends multiple values to an array
• $addToSet - appends multiple values to an array that don’t already exist in the
array
• $pop - removes the last element in an array
• $pull - removes all occurrences of a value from an array
• $pullAll - removes all occurrences of multiple values from an array


Removing Documents

$coll->remove(array('username' => 'jwage'));


Doctrine + MongoDB


DocumentManager
• Abstraction on top of the PHP Mongo
class

• Manages the persistent state of PHP
objects

• Implements UnitOfWork for change
tracking
http://martinfowler.com/eaaCatalog/unitOfWork.html


Document States
• A NEW document instance has no persistent identity, and is not yet
associated with a DocumentManager (i.e. those just created with the
"new" operator).

• A MANAGED document instance is an instance with a persistent
identity that is associated with an DocumentManager and whose
persistence is thus managed.

• A DETACHED document instance is an instance with a persistent
identity that is not (or no longer) associated with an
DocumentManager.

• A REMOVED document instance is an instance with a persistent
identity, associated with an DocumentManager, that will be removed
from the database upon transaction commit.


DocumentManager
Create your DocumentManager instance for managing object persistence

$config = new DoctrineODMMongoDBConfiguration();
$config->setMetadataCacheImpl(new DoctrineCommonCacheArrayCache);
$driverImpl = $config->newDefaultAnnotationDriver(array(__DIR__."/Documents"));
$config->setMetadataDriverImpl($driverImpl);

$config->setProxyDir(__DIR__ . '/Proxies');
$config->setProxyNamespace('Proxies');

$dm = DoctrineORMDocumentManager::create($mongo, $config);

Wraps around existing $mongo connection


Deﬁning Document
A document is just a regular ole’ PHP class

class User
{
private $id;
private $username;
private $password;

public function getId()
{
return $this->id;
}

public function getUsername()
{
return $this->username;
}

public function setUsername($username)
{
$this->username = $username;
}

public function getPassword()
{
return $this->password;
}

public function setPassword($password)
{
$this->password = md5($password);
}
}


Mapping the Document

/** @Document */
class User
{
/** @Id */
private $id;
/** @String */
private $username;
/** @String */
private $password;

// ...
}


Ready to Go
Doctrine now knows about this document and is able
to manage its persistent state


Inserting, Updating and
Deleting Documents


Inserting Documents
$user = new User();
$user->setUsername('jwage');
$user->setPassword('changeme');

$dm->persist($user);
$dm->flush(); // inserts document

$users = array(
array(
'username' => 'jwage',
'password' => 'changeme'
)
);
$coll->batchInsert($users);


Updating Documents
$user = $dm->findOne('User', array('username' => 'jwage'));

$user->setUsername('jonwage');
$user->setPassword('newpassword');

$dm->flush(); // updates document

$coll->update(
array('_id' => 'theid'),
array('$set' => array(
'username' => 'jonwage',
'password' => '5e9d11a14ad1c8dd77e98ef9b53fd1ba'
)
);


Removing Documents


$dm->remove($user);
$dm->flush(); // removes document

$coll->remove(array('_id' => 'theid'));


Query API
Fluent OO Query API


Querying MongoDB
Directly

// Get user array directly from mongo
$user = $mongo->db->users->findOne(array('username' => 'jwage'));

Returns an array of information and not a User object


Querying Through
Doctrine

// Get user class instance through Doctrine

Going through Doctrine gives you managed objects back instead of arrays


Querying Through
Doctrine Query API

// Get user class instance through Doctrine Query API
$user = $dm->createQuery('User')
->field('username')->equals('jwage')
->getSingleResult();

Query for same user using the Query API


Querying Through
Doctrine Query API

// Find posts within a range of dates
$posts = $dm->createQuery('Post')
->field('createdAt')->range($startDate, $endDate)
->execute();


Updating Documents

// Update a document
$dm->createQuery('User')
->update()
->field('username')->set('jonwage')
->field('password')->set('newpassword')
->execute();


Removing Documents

// Remove a document
// Remove a document

->remove() ->remove()
->execute();
->execute();


Embedded Documents


class User
{
/** @Id */
public $id;

/** @String */
public $name;

/** @EmbedMany(targetDocument="Address") */
public $addresses = array();
}


/** @EmbeddedDocument */
class Address
{
/** @String */
public $address;

/** @String */
public $city;

/** @String */
public $state;

/** @String */
public $zipcode;
}


$user = new User();
$user->name = 'Jonathan H. Wage';

$address = new Address();
$address->address = '6512 Mercomatic Ct';
$address->city = 'Nashville';
$address->state = 'Tennessee';
$address->zipcode = '37209';
$user->addresses[] = $address;

$dm->flush();


$users = array(
array(
'name' => 'Jonathan H. Wage',
'addresses' => array(
array(
'address' => '6512 Mercomatic Ct',
'city' => 'Nashville',
'state' => 'Tennesseee',
'zipcode' => '37209'
)
)
)
);
$coll->batchInsert($users);


Updating Embedded
Documents
Uses dot notation and atomic operators for updating


$user = $dm->findOne('User', array('name' => 'Jonathan H. Wage'));
$user->addresses[0]->zipcode = '37205';
$dm->flush();

$coll->update(
array('_id' => 'theuserid'),
array('$set' => array('addresses.0.zipcode' => '37209'))
);


Add New Address


$user = $dm->findOne('User', array('name' => 'Jonathan H. Wage'));

$address = new Address();
$address->address = '475 Buckhead Ave.';
$address->city = 'Atlanta';
$address->state = 'Georgia';
$address->zipcode = '30305';
$user->addresses[] = $address;

$dm->flush();

$coll->update(
array('$pushAll' => array(
'addresses' => array(
array(
'address' => '475 Buckhead Ave.',
'city' => 'Atlanta',
'state' => 'Georgia',
'zipcode' => '30305'
)
)
))
);


unset($user->addresses[0]->zipcode);
$dm->flush();

$coll->update(
array(
'$unset' => array(
'addresses.0.zipcode' => 1
)
)
);


References
MongoDB does not have joins or foreign keys but you
can still store references to other documents and
resolve the references in your application code.
Doctrine abstracts the handling of referneces for you
so working with them is seamless.


Organization
/** @Document */
class Organization
{
/** @Id */
private $id;

/** @String */
private $name;

/** @ReferenceMany(targetDocument="User") */
private $users = array();

public function setName($name)
{
$this->name = $name;
}

public function addUser(User $user)
{
$this->users[] = $user;
}
}


User
/** @Document */
class User
{
/** @Id */
private $id;

/** @String */
private $name;

/** @ReferenceOne(targetDocument="Organization") */
private $organization;

public function setName($name)
{
$this->name = $name;
}

public function setOrganization(Organization $organization)
{
$this->organization = $organization;
$organization->addUser($this);
}
}


$organization = new Organization();
$organization->setName('Sensio Labs');

$user = new User();
$user->setName('Jonathan H. Wage');
$user->setOrganization($organization);

$dm->persist($organization);
$dm->flush();


The Result


Array
(
[_id] => 4c86acd78ead0e8759000000
[name] => Sensio Labs
[users] => Array
(
[0] => Array
(
[$ref] => User
[$id] => 4c86acd78ead0e8759010000
[$db] => doctrine_odm_sandbox
)

)

)

Array
(
[_id] => 4c86acd78ead0e8759010000
[name] => Jonathan H. Wage
[organization] => Array
(
[$ref] => Organization
[$id] => 4c86acd78ead0e8759000000
[$db] => doctrine_odm_sandbox
)

)


Working with
References


$user = $dm->find('User', array('name' => 'Jonathan H. Wage'));

// instance of uninitialized OrganizationProxy
$organization = $user->getOrganization();

// calling getter or setter for uninitialized proxy
// queries the database and initialized the proxy document

// query invoked, organization data loaded and doc initialized
echo $organization->getName();


$organization = $dm->find('Organization', array('name' => 'Sensio Labs'));
$users = $organization->getUsers(); // uninitialized collection

// Queries database for users and initializes collection
foreach ($users as $user)
{
// ...
}


Change Tracking


UnitOfWork
• Tracks changes in objects between ﬂushes

• Maintains copy of old values to compare
new values to

• Changesets computed and persisted in
the most efﬁcient way using atomic
operators $inc, $set, $unset, $pullAll,
$pushAll, etc.


Other Features


Document Query
Language
Language for querying documents in a similar way to
SQL


BNF Grammar


QueryLanguage ::= FindQuery | InsertQuery | UpdateQuery | RemoveQuery

FindQuery ::= FindClause [WhereClause] [MapClause] [ReduceClause] [SortClause] [LimitClause]
[SkipClause]
FindClause ::= "FIND" all | SelectField {"," SelectField}
SelectField ::= DocumentFieldName
SortClause ::= SortClauseField {"," SortClauseField}
SortClauseField ::= DocumentFieldName "ASC | DESC"
LimitClause ::= "LIMIT" LimitInteger
SkipClause ::= "SKIP" SkipInteger
MapClause ::= "MAP" MapFunction
ReduceClause ::= "REDUCE" ReduceFunction

DocumentFieldName ::= DocumentFieldName | EmbeddedDocument "." {"." DocumentFieldName}
WhereClause ::= "WHERE" WhereClausePart {"AND" WhereClausePart}
WhereClausePart ::= ["all", "not"] DocumentFieldName WhereClauseExpression Value
WhereClauseExpression ::= "=" | "!=" | ">=" | "<=" | ">" | "<" | "in"
"notIn" | "all" | "size" | "exists" | "type"
Value ::= LiteralValue | JsonObject | JsonArray

UpdateQuery ::= UpdateClause [WhereClause]
UpdateClause ::= [SetExpression], [UnsetExpression], [IncrementExpression],
[PushExpression], [PushAllExpression], [PullExpression],
[PullAllExpression], [AddToSetExpression], [AddManyToSetExpression],
[PopFirstExpression], [PopLastExpression]
SetExpression ::= "SET" DocumentFieldName "=" Value {"," SetExpression}
UnsetExpression ::= "UNSET" DocumentFieldName {"," UnsetExpression}
IncrementExpression ::= "INC" DocumentFieldName "=" IncrementInteger {"," IncrementExpression}
PushExpression ::= "PUSH" DocumentFieldName Value {"," PushExpression}
PushAllExpression ::= "PUSHALL" DocumentFieldName Value {"," PushAllExpression}
PullExpression ::= "PULL" DocumentFieldName Value {"," PullExpression}
PullAllExpression ::= "PULLALL" DocumentFieldName Value {"," PullAllExpression}
AddToSetExpression ::= "ADDTOSET" DocumentFieldName Value {"," AddToSetExpression}
AddManyToSetExpression ::= "ADDMANYTOSET" DocumentFieldName Value {"," AddManyToSetExpression}
PopFirstExpression ::= "POPFIRST" DocumentFieldName {"," PopFirstExpression}
PopLastExpression ::= "POPLAST" DocumentFieldName {"," PopLastExpression}

InsertQuery ::= InsertClause InsertSetClause {"," InsertSetClause}
InsertSetClause ::= DocumentFieldName "=" Value

RemoveQuery ::= RemoveClause [WhereClause]


Creating Query

$users = $dm->query('find all FROM User');


Selecting Fields

$users = $dm->query('find username FROM User');


Paging Results

$users = $dm->query('find all FROM User limit 30 skip 30');


Selecting Slice of
Embedded Documents

$post = $dm->query('find title, comments limit 20 skip 10 FROM
BlogPost WHERE id = ?', array($id));


Other Examples
// Find all posts greater than or equal to a date
$posts = $dm->query('find all FROM BlogPost WHERE createdAt >= ?',
array($date));

// Find all posts sorted by created at desc
$posts = $dm->query('find all FROM BlogPost sort createdAt desc');

// Update user
$dm->query('update DocumentsUser set password = ? where username = ?',
array('newpassword', 'jwage'));


Lifecycle Events


“A lifecycle event is a regular event with the additional
feature of providing a mechanism to register direct
callbacks inside the corresponding document classes
that are executed when the lifecycle event occurs.”

http://www.doctrine-project.org/projects/mongodb_odm/1.0/docs/reference/events/en#lifecycle-callbacks


• preRemove - The preRemove event occurs for a given document before the
respective DocumentManager remove operation for that document is
executed.
• postRemove - The postRemove event occurs for an document after the
document has been removed. It will be invoked after the database delete
operations.
• prePersist - The prePersist event occurs for a given document before the
respective DocumentManager persist operation for that document is executed.
• postPersist - The postPersist event occurs for an document after the
document has been made persistent. It will be invoked after the database insert
operations. Generated primary key values are available in the postPersist event.
• preUpdate - The preUpdate event occurs before the database update
operations to document data.
• postUpdate - The postUpdate event occurs after the database update
operations to document data.
• postLoad - The postLoad event occurs for an document after the document
has been loaded into the current DocumentManager from the database or after
the refresh operation has been applied to it.


Event Examples


/**
* @Document
* @HasLifecycleCallbacks
*/
class BlogPost
{
/** @Id */
public $id;
/** @Date */
public $createdAt;
/** @Date */
public $updatedAt;

/** @PreUpdate */
public function prePersist()
{
$this->createdAt = new DateTime();
}

/** @PreUpdate */
public function preUpdate()
{
$this->updatedAt = new DateTime();
}
}


Migrating Data


Initial Document
/**
* @Document
*/
class User
{
/** @Id */
public $id;
/** @String */
public $name;
}


New Document
/**
* @Document
*/
class User
{
/** @Id */
public $id;
/** @String */
public $firstName;
/** @String */
public $lastName;
}


Migrate Documents
With Old Field Name
/**
* @Document
* @HasLifecycleCallbacks
*/
class User
{
/** @Id */
public $id;
/** @String */
public $firstName;
/** @String */
public $lastName;

/** @PreLoad */
public function preLoad(array &$data)
{
if (isset($data['name']))
{
$e = explode(' ', $data['name']);
unset($data['name']);
$data['firstName'] = $e[0];
$data['lastName'] = $e[1];
}
}


Questions?
Jonathan H. Wage
• http://www.twitter.com/jwage

• http://www.jwage.com

• http://www.facebook.com/jwage

You can contact Jonathan about Doctrine and Open-Source or for
training, consulting, application development, or business related
questions at jonathan.wage@sensio.com


Doctrine MongoDB Object Document Mapper

More Related Content

What's hot

Viewers also liked

Similar to Doctrine MongoDB Object Document Mapper

More from Jonathan Wage

Recently uploaded

Doctrine MongoDB Object Document Mapper