class UnitOfWork implements PropertyChangedListener (View source)

The UnitOfWork is responsible for tracking changes to objects during an "object-level" transaction and for writing out changes to the database in the correct order.

Constants

STATE_MANAGED

A document is in MANAGED state when its persistence is managed by a DocumentManager.

STATE_NEW

A document is new if it has just been instantiated (i.e. using the "new" operator) and is not (yet) managed by a DocumentManager.

STATE_DETACHED

A detached document is an instance with a persistent identity that is not (or no longer) associated with a DocumentManager (and a UnitOfWork).

STATE_REMOVED

A removed document instance is an instance with a persistent identity, associated with a DocumentManager, whose persistent state has been deleted (or is scheduled for deletion).

Methods

__construct(DocumentManager $dm, EventManager $evm, HydratorFactory $hydratorFactory)

Initializes a new UnitOfWork instance, bound to the given DocumentManager.

getPersistenceBuilder()

Factory for returning new PersistenceBuilder instances used for preparing data into queries for insert persistence.

setParentAssociation(object $document, array $mapping, object $parent, string $propertyPath)

Sets the parent association for a given embedded document.

array
getParentAssociation(object $document)

Gets the parent association for a given embedded document.

getDocumentPersister(string $documentName)

Get the document persister instance for the given document name

getCollectionPersister()

Get the collection persister instance.

setDocumentPersister($documentName, DocumentPersister $persister)

Set the document persister instance to use for the given document name

commit(array $options = [])

Commits the UnitOfWork, executing all operations that have been postponed up to this point. The state of all managed documents will be synchronized with the database.

array
getDocumentChangeSet(object $document)

Gets the changeset for a document.

setDocumentChangeSet(object $document, array $changeset)

INTERNAL: Sets the changeset for a document.

array
getDocumentActualData(object $document)

Get a documents actual data, flattening all the objects to arrays.

computeChangeSet(ClassMetadata $class, object $document)

Computes the changes that happened to a single document.

computeChangeSets()

Computes all the changes that have been done to documents and collections since the last commit and stores these changes in the _documentChangeSet map temporarily for access by the persisters, until the UoW commit is finished.

recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document)

INTERNAL: Computes the changeset of an individual document, independently of the computeChangeSets() routine that is used at the beginning of a UnitOfWork#commit().

scheduleForInsert(ClassMetadata $class, $document)

Schedules a document for insertion into the database.

scheduleForUpsert(ClassMetadata $class, $document)

Schedules a document for upsert into the database and adds it to the identity map

bool
isScheduledForInsert(object $document)

Checks whether a document is scheduled for insertion.

bool
isScheduledForUpsert(object $document)

Checks whether a document is scheduled for upsert.

scheduleForUpdate(object $document)

Schedules a document for being updated.

bool
isScheduledForUpdate(object $document)

Checks whether a document is registered as dirty in the unit of work.

isScheduledForDirtyCheck($document)

No description

scheduleForDelete(object $document)

INTERNAL: Schedules a document for deletion.

bool
isScheduledForDelete(object $document)

Checks whether a document is registered as removed/deleted with the unit of work.

bool
isDocumentScheduled(object $document)

Checks whether a document is scheduled for insertion, update or deletion.

bool
addToIdentityMap(object $document)

INTERNAL: Registers a document in the identity map.

int
getDocumentState(object $document, int|null $assume = null)

Gets the state of a document with regard to the current unit of work.

bool
removeFromIdentityMap(object $document)

INTERNAL: Removes a document from the identity map. This effectively detaches the document from the persistence management of Doctrine.

object
getById(mixed $id, ClassMetadata $class)

INTERNAL: Gets a document in the identity map by its identifier hash.

mixed
tryGetById(mixed $id, ClassMetadata $class)

INTERNAL: Tries to get a document by its identifier hash. If no document is found for the given hash, FALSE is returned.

scheduleForDirtyCheck(object $document)

Schedules a document for dirty-checking at commit-time.

bool
isInIdentityMap(object $document)

Checks whether a document is registered in the identity map.

bool
containsId(string $id, string $rootClassName)

INTERNAL: Checks whether an identifier exists in the identity map.

persist(object $document)

Persists a document as part of the current unit of work.

remove(object $document)

Deletes a document as part of the current unit of work.

object
merge(object $document)

Merges the state of the given detached document into this UnitOfWork.

detach(object $document)

Detaches a document from the persistence management. It's persistence will no longer be managed by Doctrine.

refresh(object $document)

Refreshes the state of the given document from the database, overwriting any local, unpersisted changes.

lock(object $document, int $lockMode, int $lockVersion = null)

Acquire a lock on the given document.

unlock(object $document)

Releases a lock on the given document.

clear(string|null $documentName = null)

Clears the UnitOfWork.

scheduleOrphanRemoval(object $document)

INTERNAL: Schedules an embedded document for removal. The remove() operation will be invoked on that document at the beginning of the next commit of this UnitOfWork.

unscheduleOrphanRemoval(object $document)

INTERNAL: Unschedules an embedded or referenced object for removal.

scheduleCollectionDeletion(PersistentCollectionInterface $coll)

INTERNAL: Schedules a complete collection for removal when this UnitOfWork commits.

bool
isCollectionScheduledForDeletion(PersistentCollectionInterface $coll)

Checks whether a PersistentCollection is scheduled for deletion.

unscheduleCollectionDeletion(PersistentCollectionInterface $coll)

INTERNAL: Unschedules a collection from being deleted when this UnitOfWork commits.

scheduleCollectionUpdate(PersistentCollectionInterface $coll)

INTERNAL: Schedules a collection for update when this UnitOfWork commits.

unscheduleCollectionUpdate(PersistentCollectionInterface $coll)

INTERNAL: Unschedules a collection from being updated when this UnitOfWork commits.

bool
isCollectionScheduledForUpdate(PersistentCollectionInterface $coll)

Checks whether a PersistentCollection is scheduled for update.

getVisitedCollections(object $document)

INTERNAL: Gets PersistentCollections that have been visited during computing change set of $document

array
getScheduledCollections(object $document)

INTERNAL: Gets PersistentCollections that are scheduled to update and related to $document

bool
hasScheduledCollections(object $document)

Checks whether the document is related to a PersistentCollection scheduled for update or deletion.

object
getOwningDocument(object $document)

Get the top-most owning document of a given document

string
getClassNameForAssociation(array $mapping, array|null $data)

Gets the class name for an association (embed or reference) with respect to any discriminator value.

object
getOrCreateDocument(string $className, array $data, array $hints = [], object $document = null)

INTERNAL: Creates a document. Used for reconstitution of documents during hydration.

loadCollection(PersistentCollectionInterface $collection)

Initializes (loads) an uninitialized persistent collection of a document.

array
getIdentityMap()

Gets the identity map of the UnitOfWork.

array
getOriginalDocumentData(object $document)

Gets the original data of a document. The original data is the data that was present at the time the document was reconstituted from the database.

setOriginalDocumentData($document, array $data)

No description

setOriginalDocumentProperty(string $oid, string $property, mixed $value)

INTERNAL: Sets a property value of the original data array of a document.

mixed
getDocumentIdentifier(object $document)

Gets the identifier of a document.

bool
hasPendingInsertions()

Checks whether the UnitOfWork has any pending insertions.

int
size()

Calculates the size of the UnitOfWork. The size of the UnitOfWork is the number of documents in the identity map.

registerManaged(object $document, array $id, array $data)

INTERNAL: Registers a document as managed.

clearDocumentChangeSet(string $oid)

INTERNAL: Clears the property changeset of the document with the given OID.

propertyChanged(object $document, string $propertyName, mixed $oldValue, mixed $newValue)

Notifies this UnitOfWork of a property change in a document.

array
getScheduledDocumentInsertions()

Gets the currently scheduled document insertions in this UnitOfWork.

array
getScheduledDocumentUpserts()

Gets the currently scheduled document upserts in this UnitOfWork.

array
getScheduledDocumentUpdates()

Gets the currently scheduled document updates in this UnitOfWork.

array
getScheduledDocumentDeletions()

Gets the currently scheduled document deletions in this UnitOfWork.

array
getScheduledCollectionDeletions()

Get the currently scheduled complete collection deletions

array
getScheduledCollectionUpdates()

Gets the currently scheduled collection inserts, updates and deletes.

initializeObject(object $obj)

Helper method to initialize a lazy loading proxy or persistent collection.

Details

__construct(DocumentManager $dm, EventManager $evm, HydratorFactory $hydratorFactory)

Initializes a new UnitOfWork instance, bound to the given DocumentManager.

Parameters

DocumentManager $dm
EventManager $evm
HydratorFactory $hydratorFactory

PersistenceBuilder getPersistenceBuilder()

Factory for returning new PersistenceBuilder instances used for preparing data into queries for insert persistence.

Return Value

PersistenceBuilder $pb

setParentAssociation(object $document, array $mapping, object $parent, string $propertyPath)

Sets the parent association for a given embedded document.

Parameters

object $document
array $mapping
object $parent
string $propertyPath

array getParentAssociation(object $document)

Gets the parent association for a given embedded document.

list($mapping, $parent, $propertyPath) = $this->getParentAssociation($embeddedDocument);

Parameters

object $document

Return Value

array $association

DocumentPersister getDocumentPersister(string $documentName)

Get the document persister instance for the given document name

Parameters

string $documentName

Return Value

DocumentPersister

CollectionPersister getCollectionPersister()

Get the collection persister instance.

Return Value

CollectionPersister

setDocumentPersister($documentName, DocumentPersister $persister)

Set the document persister instance to use for the given document name

Parameters

$documentName
DocumentPersister $persister

commit(array $options = [])

Commits the UnitOfWork, executing all operations that have been postponed up to this point. The state of all managed documents will be synchronized with the database.

The operations are executed in the following order:

1) All document insertions 2) All document updates 3) All document deletions

Parameters

array $options Array of options to be used with batchInsert(), update() and remove()

array getDocumentChangeSet(object $document)

Gets the changeset for a document.

Parameters

object $document

Return Value

array array('property' => array(0 => mixed|null, 1 => mixed|null))

setDocumentChangeSet(object $document, array $changeset)

INTERNAL: Sets the changeset for a document.

Parameters

object $document
array $changeset

array getDocumentActualData(object $document)

Get a documents actual data, flattening all the objects to arrays.

Parameters

object $document

Return Value

array

computeChangeSet(ClassMetadata $class, object $document)

Computes the changes that happened to a single document.

Modifies/populates the following properties:

{@link originalDocumentData} If the document is NEW or MANAGED but not yet fully persisted (only has an id) then it was not fetched from the database and therefore we have no original document data yet. All of the current document data is stored as the original document data.

{@link documentChangeSets} The changes detected on all properties of the document are stored there. A change is a tuple array where the first entry is the old value and the second entry is the new value of the property. Changesets are used by persisters to INSERT/UPDATE the persistent document state.

{@link documentUpdates} If the document is already fully MANAGED (has been fetched from the database before) and any changes to its properties are detected, then a reference to the document is stored there to mark it for an update.

Parameters

ClassMetadata $class The class descriptor of the document.
object $document The document for which to compute the changes.

computeChangeSets()

Computes all the changes that have been done to documents and collections since the last commit and stores these changes in the _documentChangeSet map temporarily for access by the persisters, until the UoW commit is finished.

recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document)

INTERNAL: Computes the changeset of an individual document, independently of the computeChangeSets() routine that is used at the beginning of a UnitOfWork#commit().

The passed document must be a managed document. If the document already has a change set because this method is invoked during a commit cycle then the change sets are added. whereby changes detected in this method prevail.

Parameters

ClassMetadata $class The class descriptor of the document.
object $document The document for which to (re)calculate the change set.

Exceptions

InvalidArgumentException If the passed document is not MANAGED.

scheduleForInsert(ClassMetadata $class, $document)

Schedules a document for insertion into the database.

If the document already has an identifier, it will be added to the identity map.

Parameters

ClassMetadata $class
$document

Exceptions

InvalidArgumentException

scheduleForUpsert(ClassMetadata $class, $document)

Schedules a document for upsert into the database and adds it to the identity map

Parameters

ClassMetadata $class
$document

Exceptions

InvalidArgumentException

bool isScheduledForInsert(object $document)

Checks whether a document is scheduled for insertion.

Parameters

object $document

Return Value

bool

bool isScheduledForUpsert(object $document)

Checks whether a document is scheduled for upsert.

Parameters

object $document

Return Value

bool

scheduleForUpdate(object $document)

Schedules a document for being updated.

Parameters

object $document The document to schedule for being updated.

Exceptions

InvalidArgumentException

bool isScheduledForUpdate(object $document)

Checks whether a document is registered as dirty in the unit of work.

Note: Is not very useful currently as dirty documents are only registered at commit time.

Parameters

object $document

Return Value

bool

isScheduledForDirtyCheck($document)

Parameters

$document

scheduleForDelete(object $document)

INTERNAL: Schedules a document for deletion.

Parameters

object $document

bool isScheduledForDelete(object $document)

Checks whether a document is registered as removed/deleted with the unit of work.

Parameters

object $document

Return Value

bool

bool isDocumentScheduled(object $document)

Checks whether a document is scheduled for insertion, update or deletion.

Parameters

object $document

Return Value

bool

bool addToIdentityMap(object $document)

INTERNAL: Registers a document in the identity map.

Note that documents in a hierarchy are registered with the class name of the root document. Identifiers are serialized before being used as array keys to allow differentiation of equal, but not identical, values.

Parameters

object $document The document to register.

Return Value

bool TRUE if the registration was successful, FALSE if the identity of the document in question is already managed.

int getDocumentState(object $document, int|null $assume = null)

Gets the state of a document with regard to the current unit of work.

Parameters

object $document
int|null $assume The state to assume if the state is not yet known (not MANAGED or REMOVED). This parameter can be set to improve performance of document state detection by potentially avoiding a database lookup if the distinction between NEW and DETACHED is either known or does not matter for the caller of the method.

Return Value

int The document state.

bool removeFromIdentityMap(object $document)

INTERNAL: Removes a document from the identity map. This effectively detaches the document from the persistence management of Doctrine.

Parameters

object $document

Return Value

bool

Exceptions

InvalidArgumentException

object getById(mixed $id, ClassMetadata $class)

INTERNAL: Gets a document in the identity map by its identifier hash.

Parameters

mixed $id Document identifier
ClassMetadata $class Document class

Return Value

object

Exceptions

InvalidArgumentException If the class does not have an identifier.

mixed tryGetById(mixed $id, ClassMetadata $class)

INTERNAL: Tries to get a document by its identifier hash. If no document is found for the given hash, FALSE is returned.

Parameters

mixed $id Document identifier
ClassMetadata $class Document class

Return Value

mixed The found document or FALSE.

Exceptions

InvalidArgumentException If the class does not have an identifier.

scheduleForDirtyCheck(object $document)

Schedules a document for dirty-checking at commit-time.

Parameters

object $document The document to schedule for dirty-checking.

bool isInIdentityMap(object $document)

Checks whether a document is registered in the identity map.

Parameters

object $document

Return Value

bool

bool containsId(string $id, string $rootClassName)

INTERNAL: Checks whether an identifier exists in the identity map.

Parameters

string $id
string $rootClassName

Return Value

bool

persist(object $document)

Persists a document as part of the current unit of work.

Parameters

object $document The document to persist.

Exceptions

MongoDBException If trying to persist MappedSuperclass.
InvalidArgumentException If there is something wrong with document's identifier.

remove(object $document)

Deletes a document as part of the current unit of work.

Parameters

object $document The document to remove.

object merge(object $document)

Merges the state of the given detached document into this UnitOfWork.

Parameters

object $document

Return Value

object The managed copy of the document.

detach(object $document)

Detaches a document from the persistence management. It's persistence will no longer be managed by Doctrine.

Parameters

object $document The document to detach.

refresh(object $document)

Refreshes the state of the given document from the database, overwriting any local, unpersisted changes.

Parameters

object $document The document to refresh.

Exceptions

InvalidArgumentException If the document is not MANAGED.

lock(object $document, int $lockMode, int $lockVersion = null)

Acquire a lock on the given document.

Parameters

object $document
int $lockMode
int $lockVersion

Exceptions

LockException
InvalidArgumentException

unlock(object $document)

Releases a lock on the given document.

Parameters

object $document

Exceptions

InvalidArgumentException

clear(string|null $documentName = null)

Clears the UnitOfWork.

Parameters

string|null $documentName if given, only documents of this type will get detached.

scheduleOrphanRemoval(object $document)

INTERNAL: Schedules an embedded document for removal. The remove() operation will be invoked on that document at the beginning of the next commit of this UnitOfWork.

Parameters

object $document

unscheduleOrphanRemoval(object $document)

INTERNAL: Unschedules an embedded or referenced object for removal.

Parameters

object $document

scheduleCollectionDeletion(PersistentCollectionInterface $coll)

INTERNAL: Schedules a complete collection for removal when this UnitOfWork commits.

bool isCollectionScheduledForDeletion(PersistentCollectionInterface $coll)

Checks whether a PersistentCollection is scheduled for deletion.

Parameters

PersistentCollectionInterface $coll

Return Value

bool

unscheduleCollectionDeletion(PersistentCollectionInterface $coll)

INTERNAL: Unschedules a collection from being deleted when this UnitOfWork commits.

scheduleCollectionUpdate(PersistentCollectionInterface $coll)

INTERNAL: Schedules a collection for update when this UnitOfWork commits.

unscheduleCollectionUpdate(PersistentCollectionInterface $coll)

INTERNAL: Unschedules a collection from being updated when this UnitOfWork commits.

bool isCollectionScheduledForUpdate(PersistentCollectionInterface $coll)

Checks whether a PersistentCollection is scheduled for update.

Parameters

PersistentCollectionInterface $coll

Return Value

bool

PersistentCollectionInterface[] getVisitedCollections(object $document)

INTERNAL: Gets PersistentCollections that have been visited during computing change set of $document

Parameters

object $document

Return Value

PersistentCollectionInterface[]

array getScheduledCollections(object $document)

INTERNAL: Gets PersistentCollections that are scheduled to update and related to $document

Parameters

object $document

Return Value

array

bool hasScheduledCollections(object $document)

Checks whether the document is related to a PersistentCollection scheduled for update or deletion.

Parameters

object $document

Return Value

bool

object getOwningDocument(object $document)

Get the top-most owning document of a given document

If a top-level document is provided, that same document will be returned. For an embedded document, we will walk through parent associations until we find a top-level document.

Parameters

object $document

Return Value

object

Exceptions

UnexpectedValueException When a top-level document could not be found.

string getClassNameForAssociation(array $mapping, array|null $data)

Gets the class name for an association (embed or reference) with respect to any discriminator value.

Parameters

array $mapping Field mapping for the association
array|null $data Data for the embedded document or reference

Return Value

string Class name.

object getOrCreateDocument(string $className, array $data, array $hints = [], object $document = null)

INTERNAL: Creates a document. Used for reconstitution of documents during hydration.

Parameters

string $className The name of the document class.
array $data The data for the document.
array $hints Any hints to account for during reconstitution/lookup of the document.
object $document The document to be hydrated into in case of creation

Return Value

object The document instance.

loadCollection(PersistentCollectionInterface $collection)

Initializes (loads) an uninitialized persistent collection of a document.

Parameters

PersistentCollectionInterface $collection The collection to initialize.

array getIdentityMap()

Gets the identity map of the UnitOfWork.

Return Value

array

array getOriginalDocumentData(object $document)

Gets the original data of a document. The original data is the data that was present at the time the document was reconstituted from the database.

Parameters

object $document

Return Value

array

setOriginalDocumentData($document, array $data)

Parameters

$document
array $data

setOriginalDocumentProperty(string $oid, string $property, mixed $value)

INTERNAL: Sets a property value of the original data array of a document.

Parameters

string $oid
string $property
mixed $value

mixed getDocumentIdentifier(object $document)

Gets the identifier of a document.

Parameters

object $document

Return Value

mixed The identifier value

bool hasPendingInsertions()

Checks whether the UnitOfWork has any pending insertions.

Return Value

bool TRUE if this UnitOfWork has pending insertions, FALSE otherwise.

int size()

Calculates the size of the UnitOfWork. The size of the UnitOfWork is the number of documents in the identity map.

Return Value

int

registerManaged(object $document, array $id, array $data)

INTERNAL: Registers a document as managed.

TODO: This method assumes that $id is a valid PHP identifier for the document class. If the class expects its database identifier to be an ObjectId, and an incompatible $id is registered (e.g. an integer), the document identifiers map will become inconsistent with the identity map. In the future, we may want to round-trip $id through a PHP and database conversion and throw an exception if it's inconsistent.

Parameters

object $document The document.
array $id The identifier values.
array $data The original document data.

clearDocumentChangeSet(string $oid)

INTERNAL: Clears the property changeset of the document with the given OID.

Parameters

string $oid The document's OID.

propertyChanged(object $document, string $propertyName, mixed $oldValue, mixed $newValue)

Notifies this UnitOfWork of a property change in a document.

Parameters

object $document The document that owns the property.
string $propertyName The name of the property that changed.
mixed $oldValue The old value of the property.
mixed $newValue The new value of the property.

array getScheduledDocumentInsertions()

Gets the currently scheduled document insertions in this UnitOfWork.

Return Value

array

array getScheduledDocumentUpserts()

Gets the currently scheduled document upserts in this UnitOfWork.

Return Value

array

array getScheduledDocumentUpdates()

Gets the currently scheduled document updates in this UnitOfWork.

Return Value

array

array getScheduledDocumentDeletions()

Gets the currently scheduled document deletions in this UnitOfWork.

Return Value

array

array getScheduledCollectionDeletions()

Get the currently scheduled complete collection deletions

Return Value

array

array getScheduledCollectionUpdates()

Gets the currently scheduled collection inserts, updates and deletes.

Return Value

array

initializeObject(object $obj)

Helper method to initialize a lazy loading proxy or persistent collection.

Parameters

object $obj