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.

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(string $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, object $document)

Schedules a document for insertion into the database.

scheduleForUpsert(ClassMetadata $class, object $document)

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

isScheduledForInsert(object $document)

Checks whether a document is scheduled for insertion.

isScheduledForUpsert(object $document)

Checks whether a document is scheduled for upsert.

scheduleForUpdate(object $document)

Schedules a document for being updated.

isScheduledForUpdate(object $document)

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

isScheduledForDirtyCheck(object $document)

No description

scheduleForDelete(object $document)

INTERNAL: Schedules a document for deletion.

isScheduledForDelete(object $document)

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

isDocumentScheduled(object $document)

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

addToIdentityMap(object $document)

INTERNAL: Registers a document in the identity map.

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

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

removeFromIdentityMap(object $document)

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

getById($id, ClassMetadata $class)

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

mixed
tryGetById($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.

isInIdentityMap(object $document)

Checks whether a document is registered in the identity map.

containsId($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.

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|null $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.

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.

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

getScheduledCollections(object $document)

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

hasScheduledCollections(object $document)

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

getOwningDocument(object $document)

Get the top-most owning document of a given document

getClassNameForAssociation(array $mapping, $data)

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

getOrCreateDocument(string $className, array $data, array $hints = [], object|null $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.

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(object $document, array $data)

No description

setOriginalDocumentProperty(string $oid, string $property, $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.

size()

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

registerManaged(object $document, $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.

getScheduledDocumentInsertions()

Gets the currently scheduled document insertions in this UnitOfWork.

getScheduledDocumentUpserts()

Gets the currently scheduled document upserts in this UnitOfWork.

getScheduledDocumentUpdates()

Gets the currently scheduled document updates in this UnitOfWork.

getScheduledDocumentDeletions()

Gets the currently scheduled document deletions in this UnitOfWork.

getScheduledCollectionDeletions()

Get the currently scheduled complete collection deletions

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

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.

Parameters

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

getParentAssociation(object $document)

Gets the parent association for a given embedded document.

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

Parameters

object $document

getDocumentPersister(string $documentName)

Get the document persister instance for the given document name

Parameters

string $documentName

getCollectionPersister()

Get the collection persister instance.

setDocumentPersister(string $documentName, DocumentPersister $persister)

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

Parameters

string $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
object $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().

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
object $document

Exceptions

InvalidArgumentException If the passed document is not MANAGED.

scheduleForInsert(ClassMetadata $class, object $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
object $document

Exceptions

InvalidArgumentException

scheduleForUpsert(ClassMetadata $class, object $document)

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

Parameters

ClassMetadata $class
object $document

Exceptions

InvalidArgumentException

isScheduledForInsert(object $document)

Checks whether a document is scheduled for insertion.

Parameters

object $document

isScheduledForUpsert(object $document)

Checks whether a document is scheduled for upsert.

Parameters

object $document

scheduleForUpdate(object $document)

Schedules a document for being updated.

Parameters

object $document

Exceptions

InvalidArgumentException

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

isScheduledForDirtyCheck(object $document)

Parameters

object $document

scheduleForDelete(object $document)

INTERNAL: Schedules a document for deletion.

Parameters

object $document

isScheduledForDelete(object $document)

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

Parameters

object $document

isDocumentScheduled(object $document)

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

Parameters

object $document

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

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

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

Exceptions

InvalidArgumentException

getById($id, ClassMetadata $class)

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

Parameters

$id
ClassMetadata $class

Exceptions

InvalidArgumentException If the class does not have an identifier.

mixed tryGetById($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

$id
ClassMetadata $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

isInIdentityMap(object $document)

Checks whether a document is registered in the identity map.

Parameters

object $document

containsId($id, string $rootClassName)

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

Parameters

$id
string $rootClassName

persist(object $document)

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

Parameters

object $document

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

merge(object $document)

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

Parameters

object $document

detach(object $document)

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

Parameters

object $document

refresh(object $document)

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

Parameters

object $document

Exceptions

InvalidArgumentException If the document is not MANAGED.

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

Acquire a lock on the given document.

Parameters

object $document
int $lockMode
int|null $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

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.

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.

isCollectionScheduledForUpdate(PersistentCollectionInterface $coll)

Checks whether a PersistentCollection is scheduled for update.

PersistentCollectionInterface[] getVisitedCollections(object $document)

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

Parameters

object $document

Return Value

PersistentCollectionInterface[]

PersistentCollectionInterface[] getScheduledCollections(object $document)

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

Parameters

object $document

Return Value

PersistentCollectionInterface[]

hasScheduledCollections(object $document)

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

Parameters

object $document

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

Exceptions

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

getClassNameForAssociation(array $mapping, $data)

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

Parameters

array $mapping
$data

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

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

Parameters

string $className
array $data
array $hints
object|null $document

loadCollection(PersistentCollectionInterface $collection)

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

Parameters

PersistentCollectionInterface $collection

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.

Parameters

object $document

Return Value

array

setOriginalDocumentData(object $document, array $data)

Parameters

object $document
array $data

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

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

Parameters

string $oid
string $property
$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.

size()

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

registerManaged(object $document, $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
$id
array $data

clearDocumentChangeSet(string $oid)

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

Parameters

string $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.

getScheduledDocumentInsertions()

Gets the currently scheduled document insertions in this UnitOfWork.

getScheduledDocumentUpserts()

Gets the currently scheduled document upserts in this UnitOfWork.

getScheduledDocumentUpdates()

Gets the currently scheduled document updates in this UnitOfWork.

getScheduledDocumentDeletions()

Gets the currently scheduled document deletions in this UnitOfWork.

getScheduledCollectionDeletions()

Get the currently scheduled complete collection deletions

getScheduledCollectionUpdates()

Gets the currently scheduled collection inserts, updates and deletes.

initializeObject(object $obj)

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

Parameters

object $obj