This project is not being actively maintained. If you are interested in helping to maintain this project, take a look at the open issues on GitHub and submit pull requests.
In this chapter we will help you understand the
UnitOfWork. A Unit of Work is similar to an
object-level transaction. A new Unit of Work is implicitly started
when an DocumentManager is initially created or after
DocumentManager#flush() has been invoked. A Unit of Work is
committed (and a new one started) by invoking
A Unit of Work can be manually closed by calling
DocumentManager#close(). Any changes to objects within this
Unit of Work that have not yet been persisted are lost.
The size of a Unit of Work mainly refers to the number of managed documents at a particular point in time.
How costly a flush operation is in terms of performance mainly depends on the size. You can get the size of your Unit of Work as follows:
The size represents the number of managed documents in the Unit of Work. This size affects the performance of flush() operations due to change tracking and, of course, memory consumption, so you may want to check it from time to time during development.
Do not invoke
You can get direct access to the Unit of Work by calling
DocumentManager#getUnitOfWork(). This will return the
UnitOfWork instance the DocumentManager is currently using.
Directly manipulating a UnitOfWork is not recommended. When working directly with the UnitOfWork API, respect methods marked as INTERNAL by not using them and carefully read the API documentation.
A document can be made persistent by passing it to the
DocumentManager#persist($document) method. By applying the
persist operation on some document, that document becomes MANAGED,
which means that its persistence is from now on managed by an
DocumentManager. As a result the persistent state of such a
document will subsequently be properly synchronized with the
DocumentManager#flush() is invoked.
The _id of a document is available directly after persist when using the UUID strategy (which is default).
The semantics of the persist operation, applied on a document X, are as follows:
- If X is a new document, it becomes managed. The document X will be
entered into the database as a result of the flush operation.
- If X is a pre-existing managed document, it is ignored by the
persist operation. However, the persist operation is cascaded to documents referenced by X, if the relationships from X to these other documents are mapped with cascade=PERSIST or cascade=ALL.
- If X is a removed document, it becomes managed.
- If X is a detached document, the behavior is undefined.
Do not pass detached documents to the persist operation.
A document can be removed from persistent storage by passing it to
DocumentManager#remove($document) method. By applying the
remove operation on some document, that document becomes
REMOVED, which means that its persistent state will be deleted once
DocumentManager#flush() is invoked. The in-memory state of a
document is unaffected by the
The semantics of the remove operation, applied to a document X are as follows:
- If X is a new document, it is ignored by the remove operation.
However, the remove operation is cascaded to documents referenced by X, if the relationship from X to these other documents is mapped with cascade=REMOVE or cascade=ALL.
- If X is a managed document, the remove operation causes it to
become removed. The remove operation is cascaded to documents referenced by X, if the relationships from X to these other documents is mapped with cascade=REMOVE or cascade=ALL.
- If X is a detached document, an InvalidArgumentException will be
- If X is a removed document, it is ignored by the remove operation.
- A removed document X will be removed from the database as a result
of the flush operation.
A document is detached from an DocumentManager and thus no longer
managed by invoking the
method on it or by cascading the detach operation to it. Changes
made to the detached document, if any (including removal of the
document), will not be synchronized to the database after the
document has been detached.
Doctrine will not hold on to any references to a detached document.
The semantics of the detach operation, applied to a document X are as follows:
- If X is a managed document, the detach operation causes it to
become detached. The detach operation is cascaded to documents referenced by X, if the relationships from X to these other documents is mapped with cascade=DETACH or cascade=ALL. Documents which previously referenced X will continue to reference X.
- If X is a new or detached document, it is ignored by the detach
- If X is a removed document, the detach operation is cascaded to
documents referenced by X, if the relationships from X to these other documents is mapped with cascade=DETACH or cascade=ALL/Documents which previously referenced X will continue to reference X.
There are several situations in which a document is detached
automatically without invoking the
DocumentManager#clear()is invoked, all documents that are
currently managed by the DocumentManager instance become detached.
- When serializing a document. The document retrieved upon subsequent
unserialization will be detached (This is the case for all documents that are serialized and stored in some cache).
detach operation is usually not as frequently needed and
Merging documents refers to the merging of (usually detached)
documents into the context of an DocumentManager so that they
become managed again. To merge the state of a document into an
DocumentManager use the
method. The state of the passed document will be merged into a
managed copy of this document and this copy will subsequently be
When you want to serialize/unserialize documents you have to make all document properties protected, never private. The reason for this is, if you serialize a class that was a proxy instance before, the private variables won't be serialized and a PHP Notice is thrown.
The semantics of the merge operation, applied to a document X, are as follows:
- If X is a detached document, the state of X is copied onto a
pre-existing managed document instance X' of the same iddocument or a new managed copy X' of X is created.
- If X is a new document instance, an InvalidArgumentException will
- If X is a removed document instance, an InvalidArgumentException
will be thrown.
- If X is a managed document, it is ignored by the merge operation,
however, the merge operation is cascaded to documents referenced by relationships from X if these relationships have been mapped with the cascade element value MERGE or ALL.
- For all documents Y referenced by relationships from X having the
cascade element value MERGE or ALL, Y is merged recursively as Y'. For all such Y referenced by X, X' is set to reference Y'. (Note that if X is managed then X is the same object as X'.)
- If X is a document merged to X', with a reference to another
document Y, where cascade=MERGE or cascade=ALL is not specified, then navigation of the same association from X' yields a reference to a managed object Y' with the same persistent iddocument as Y.
merge operation is usually not as frequently needed and
remove. The most common scenario for
merge operation is to re-attach documents to an
DocumentManager that come from some cache (and are therefore
detached) and you want to modify and persist such a document.
If you load some detached documents from a cache and you
do not need to persist or delete them or otherwise make use of them
without the need for persistence services there is no need to use
References between documents and embedded documents are represented just like in regular object-oriented PHP, with references to other objects or collections of objects.
Establishing a reference to another document is straight forward. Here is an example where we add a new comment to an article:
Or you can set a single reference:
Removing an association between two documents is similarly straight-forward. There are two strategies to do so, by key and by element. Here are some examples:
Or you can remove a single reference:
When working with collections, keep in mind that a Collection is
essentially an ordered map (just like a PHP array). That is why the
remove operation accepts an index/key.
removeElement is a
separate method that has O(n) complexity, where n is the size of
Persisting, removing, detaching and merging individual documents can become pretty cumbersome, especially when a larger object graph with collections is involved. Therefore Doctrine provides a mechanism for transitive persistence through cascading of these operations. Each reference to another document or a collection of documents can be configured to automatically cascade certain operations. By default, no operations are cascaded.
The following cascade options exist:
- persist : Cascades persist operations to the associated documents.
- remove : Cascades remove operations to the associated documents.
- merge : Cascades merge operations to the associated documents.
- detach : Cascades detach operations to the associated documents.
- all : Cascades persist, remove, merge and detach operations to
The following example shows an association to a number of addresses. If persist() or remove() is invoked on any User document, it will be cascaded to all associated Address documents in the $addresses collection.
Even though automatic cascading is convenient it should be used with care. Do not blindly apply cascade=all to all associations as it will unnecessarily degrade the performance of your application.
Doctrine provides the following ways, in increasing level of power and flexibility, to query for persistent objects. You should always start with the simplest one that suits your needs.
The most basic way to query for a persistent object is by its
identifier / primary key using the
DocumentManager#find($documentName, $id) method. Here is an
The return value is either the found document instance or null if no instance could be found with the given identifier.
DocumentManager#find() is just a shortcut for the
DocumentManager#getRepository($documentName) returns a
repository object which provides many ways to retrieve documents of
the specified type. By default, the repository instance is of type
Doctrine\ODM\CouchDB\DocumentRepository. You can also use
custom repository classes.
To query for one or more documents based on several conditions that
form a logical conjunction, use the
methods on a repository as follows:
1 // All users that are 20 years old $users = $dm->getRepository('User')->findBy(array('age' => 20)); // All users that are 20 years old and have a surname of 'Miller' $users = $dm->getRepository('User')->findBy(array('age' => 20, 'surname' => 'Miller')); // A single user by its nickname $user = $dm->getRepository('User')->findOneBy(array('nickname' => 'romanb')); 2 3 4 5 6 7 8 9 10
Querying by simple conditions only works for documents with indexed fields.
An DocumentRepository also provides a mechanism for more concise
calls through its use of
__call. Thus, the following two
examples are equivalent:
Whenever you have a managed document instance at hand, you can traverse and use any associations of that document as if they were in-memory already. Doctrine will automatically load the associated objects on demand through the concept of lazy-loading.
The most powerful and flexible method to query for persistent objects is the Query object. The Query object enables you to query for persistent objects through CouchDB views or the CouchDB Lucene Bridge.
By default the DocumentManager returns a default implementation of
Doctrine\ODM\CouchDB\DocumentRepository when you call
DocumentManager#getRepository($documentClass). You can override
this behavior by specifying the class name of your own Document
Repository in the Annotation, XML or YAML metadata. In large
applications that require lots of specialized DQL queries using a
custom repository is one recommended way of grouping these queries
in a central location.
You can access your repository now by calling: