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.

{@internal This class contains highly performance-sensitive code. }}

Constants

STATE_MANAGED

An entity is in MANAGED state when its persistence is managed by an EntityManager.

STATE_NEW

An entity is new if it has just been instantiated (i.e. using the "new" operator) and is not (yet) managed by an EntityManager.

STATE_DETACHED

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

STATE_REMOVED

A removed entity instance is an instance with a persistent identity, associated with an EntityManager, whose persistent state will be deleted on commit.

HINT_DEFEREAGERLOAD

Hint used to collect all primary keys of associated entities during hydration and execute it in a dedicated query afterwards

Properties

protected bool $hasCache

Methods

__construct(EntityManagerInterface $em)

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

commit()

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

mixed[]
getEntityChangeSet(object $entity)

Gets the changeset for an entity.

computeChangeSet(ClassMetadata $class, object $entity)

Computes the changes that happened to a single entity.

computeChangeSets()

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

recomputeSingleEntityChangeSet(ClassMetadata $class, object $entity)

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

scheduleForInsert(object $entity)

Schedules an entity for insertion into the database.

bool
isScheduledForInsert(object $entity)

Checks whether an entity is scheduled for insertion.

scheduleForUpdate(object $entity)

Schedules an entity for being updated.

scheduleExtraUpdate(object $entity, array $changeset)

INTERNAL: Schedules an extra update that will be executed immediately after the regular entity updates within the currently running commit cycle.

isScheduledForUpdate(object $entity)

Checks whether an entity is registered as dirty in the unit of work.

isScheduledForDirtyCheck(object $entity)

Checks whether an entity is registered to be checked in the unit of work.

scheduleForDelete(object $entity)

INTERNAL: Schedules an entity for deletion.

bool
isScheduledForDelete(object $entity)

Checks whether an entity is registered as removed/deleted with the unit of work.

bool
isEntityScheduled(object $entity)

Checks whether an entity is scheduled for insertion, update or deletion.

bool
addToIdentityMap(object $entity)

INTERNAL: Registers an entity in the identity map.

int
getEntityState(object $entity, int|null $assume = null)

Gets the state of an entity with regard to the current unit of work.

bool
removeFromIdentityMap(object $entity)

INTERNAL: Removes an entity from the identity map. This effectively detaches the entity from the persistence management of Doctrine.

object
getByIdHash(string $idHash, string $rootClassName)

INTERNAL: Gets an entity in the identity map by its identifier hash.

object|bool
tryGetByIdHash(mixed $idHash, string $rootClassName)

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

bool
isInIdentityMap(object $entity)

Checks whether an entity is registered in the identity map of this UnitOfWork.

bool
containsIdHash(string $idHash, string $rootClassName)

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

persist(object $entity)

Persists an entity as part of the current unit of work.

remove(object $entity)

Deletes an entity as part of the current unit of work.

refresh(object $entity)

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

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

Acquire a lock on the given entity.

clear()

Clears the UnitOfWork.

scheduleOrphanRemoval(object $entity)

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

cancelOrphanRemoval(object $entity)

INTERNAL: Cancels a previously scheduled orphan removal.

scheduleCollectionDeletion(PersistentCollection $coll)

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

newInstance(ClassMetadata $class)

INTERNAL: Creates a new instance of the mapped class, without invoking the constructor.

object
createEntity(string $className, array $data, mixed[] $hints = [])

INTERNAL: Creates an entity. Used for reconstitution of persistent entities.

triggerEagerLoads()

No description

loadCollection(PersistentCollection $collection)

Initializes (loads) an uninitialized persistent collection of an entity.

object[]
getIdentityMap()

Gets the identity map of the UnitOfWork.

mixed[]
getOriginalEntityData(object $entity)

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

setOriginalEntityData(object $entity, array $data)

No description

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

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

mixed[]
getEntityIdentifier(object $entity)

Gets the identifier of an entity.

mixed
getSingleIdentifierValue(object $entity)

Processes an entity instance to extract their identifier values.

object|bool
tryGetById(mixed|mixed[] $id, string $rootClassName)

Tries to find an entity with the given identifier in the identity map of this UnitOfWork.

scheduleForSynchronization(object $entity)

Schedules an entity for dirty-checking at commit-time.

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 entities in the identity map.

getEntityPersister(string $entityName)

Gets the EntityPersister for an Entity.

getCollectionPersister(ToManyAssociationMetadata $association)

Gets a collection persister for a collection-valued association.

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

INTERNAL: Registers an entity as managed.

clearEntityChangeSet(string $oid)

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

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

Notifies this UnitOfWork of a property change in an entity.

object[]
getScheduledEntityInsertions()

Gets the currently scheduled entity insertions in this UnitOfWork.

object[]
getScheduledEntityUpdates()

Gets the currently scheduled entity updates in this UnitOfWork.

object[]
getScheduledEntityDeletions()

Gets the currently scheduled entity deletions in this UnitOfWork.

Collection[]|object[][]
getScheduledCollectionDeletions()

Gets the currently scheduled complete collection deletions

Collection[]|object[][]
getScheduledCollectionUpdates()

Gets the currently scheduled collection inserts, updates and deletes.

initializeObject(object $obj)

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

markReadOnly(object $object)

Marks an entity as read-only so that it will not be considered for updates during UnitOfWork#commit().

bool
isReadOnly(object $object)

Is this entity read only?

hydrationComplete()

This method called by hydrators, and indicates that hydrator totally completed current hydration cycle.

Details

__construct(EntityManagerInterface $em)

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

Parameters

EntityManagerInterface $em

commit()

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

The operations are executed in the following order:

1) All entity insertions 2) All entity updates 3) All collection deletions 4) All collection updates 5) All entity deletions

Exceptions

Exception

mixed[] getEntityChangeSet(object $entity)

Gets the changeset for an entity.

Parameters

object $entity

Return Value

mixed[]

computeChangeSet(ClassMetadata $class, object $entity)

Computes the changes that happened to a single entity.

Modifies/populates the following properties:

{@link originalEntityData} If the entity 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 entity data yet. All of the current entity data is stored as the original entity data.

{@link entityChangeSets} The changes detected on all properties of the entity 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 entity state.

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

{@link collectionDeletions} If a PersistentCollection has been de-referenced in a fully MANAGED entity, then this collection is marked for deletion.

Parameters

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

computeChangeSets()

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

recomputeSingleEntityChangeSet(ClassMetadata $class, object $entity)

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

The passed entity must be a managed entity. If the entity 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 entity.
object $entity The entity for which to (re)calculate the change set.

Exceptions

ORMInvalidArgumentException If the passed entity is not MANAGED.
RuntimeException

scheduleForInsert(object $entity)

Schedules an entity for insertion into the database.

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

Parameters

object $entity The entity to schedule for insertion.

Exceptions

ORMInvalidArgumentException
InvalidArgumentException

bool isScheduledForInsert(object $entity)

Checks whether an entity is scheduled for insertion.

Parameters

object $entity

Return Value

bool

scheduleForUpdate(object $entity)

Schedules an entity for being updated.

Parameters

object $entity The entity to schedule for being updated.

Exceptions

ORMInvalidArgumentException

scheduleExtraUpdate(object $entity, array $changeset)

INTERNAL: Schedules an extra update that will be executed immediately after the regular entity updates within the currently running commit cycle.

Extra updates for entities are stored as (entity, changeset) tuples.

Parameters

object $entity The entity for which to schedule an extra update.
array $changeset The changeset of the entity (what to update).

isScheduledForUpdate(object $entity)

Checks whether an entity is registered as dirty in the unit of work.

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

Parameters

object $entity

isScheduledForDirtyCheck(object $entity)

Checks whether an entity is registered to be checked in the unit of work.

Parameters

object $entity

scheduleForDelete(object $entity)

INTERNAL: Schedules an entity for deletion.

Parameters

object $entity

bool isScheduledForDelete(object $entity)

Checks whether an entity is registered as removed/deleted with the unit of work.

Parameters

object $entity

Return Value

bool

bool isEntityScheduled(object $entity)

Checks whether an entity is scheduled for insertion, update or deletion.

Parameters

object $entity

Return Value

bool

bool addToIdentityMap(object $entity)

INTERNAL: Registers an entity in the identity map.

Note that entities in a hierarchy are registered with the class name of the root entity.

Parameters

object $entity The entity to register.

Return Value

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

Exceptions

ORMInvalidArgumentException

int getEntityState(object $entity, int|null $assume = null)

Gets the state of an entity with regard to the current unit of work.

Parameters

object $entity
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 entity 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 entity state.

bool removeFromIdentityMap(object $entity)

INTERNAL: Removes an entity from the identity map. This effectively detaches the entity from the persistence management of Doctrine.

Parameters

object $entity

Return Value

bool

Exceptions

ORMInvalidArgumentException

object getByIdHash(string $idHash, string $rootClassName)

INTERNAL: Gets an entity in the identity map by its identifier hash.

Parameters

string $idHash
string $rootClassName

Return Value

object

object|bool tryGetByIdHash(mixed $idHash, string $rootClassName)

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

Parameters

mixed $idHash (must be possible to cast it to string)
string $rootClassName

Return Value

object|bool The found entity or FALSE.

bool isInIdentityMap(object $entity)

Checks whether an entity is registered in the identity map of this UnitOfWork.

Parameters

object $entity

Return Value

bool

bool containsIdHash(string $idHash, string $rootClassName)

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

Parameters

string $idHash
string $rootClassName

Return Value

bool

persist(object $entity)

Persists an entity as part of the current unit of work.

Parameters

object $entity The entity to persist.

remove(object $entity)

Deletes an entity as part of the current unit of work.

Parameters

object $entity The entity to remove.

refresh(object $entity)

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

Parameters

object $entity The entity to refresh.

Exceptions

InvalidArgumentException If the entity is not MANAGED.

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

Acquire a lock on the given entity.

Parameters

object $entity
int $lockMode
int $lockVersion

Exceptions

ORMInvalidArgumentException
TransactionRequiredException
OptimisticLockException
InvalidArgumentException

clear()

Clears the UnitOfWork.

scheduleOrphanRemoval(object $entity)

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

Parameters

object $entity

cancelOrphanRemoval(object $entity)

INTERNAL: Cancels a previously scheduled orphan removal.

Parameters

object $entity

scheduleCollectionDeletion(PersistentCollection $coll)

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

Parameters

PersistentCollection $coll

bool isCollectionScheduledForDeletion(PersistentCollection $coll)

Parameters

PersistentCollection $coll

Return Value

bool

EntityManagerAware|object newInstance(ClassMetadata $class)

INTERNAL: Creates a new instance of the mapped class, without invoking the constructor.

This is only meant to be used internally, and should not be consumed by end users.

Parameters

ClassMetadata $class

Return Value

EntityManagerAware|object

object createEntity(string $className, array $data, mixed[] $hints = [])

INTERNAL: Creates an entity. Used for reconstitution of persistent entities.

{@internal Highly performance-sensitive method. }}

Parameters

string $className The name of the entity class.
array $data The data for the entity.
mixed[] $hints Any hints to account for during reconstitution/lookup of the entity.

Return Value

object The managed entity instance.

triggerEagerLoads()

loadCollection(PersistentCollection $collection)

Initializes (loads) an uninitialized persistent collection of an entity.

Parameters

PersistentCollection $collection The collection to initialize.

object[] getIdentityMap()

Gets the identity map of the UnitOfWork.

Return Value

object[]

mixed[] getOriginalEntityData(object $entity)

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

Parameters

object $entity

Return Value

mixed[]

setOriginalEntityData(object $entity, array $data)

Parameters

object $entity
array $data

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

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

Parameters

string $oid
string $property
mixed $value

mixed[] getEntityIdentifier(object $entity)

Gets the identifier of an entity.

The returned value is always an array of identifier values. If the entity has a composite identifier then the identifier values are in the same order as the identifier field names as returned by ClassMetadata#getIdentifierFieldNames().

Parameters

object $entity

Return Value

mixed[] The identifier values.

mixed getSingleIdentifierValue(object $entity)

Processes an entity instance to extract their identifier values.

Parameters

object $entity The entity instance.

Return Value

mixed A scalar value.

Exceptions

ORMInvalidArgumentException

object|bool tryGetById(mixed|mixed[] $id, string $rootClassName)

Tries to find an entity with the given identifier in the identity map of this UnitOfWork.

Parameters

mixed|mixed[] $id The entity identifier to look for.
string $rootClassName The name of the root class of the mapped entity hierarchy.

Return Value

object|bool Returns the entity with the specified identifier if it exists in this UnitOfWork, FALSE otherwise.

scheduleForSynchronization(object $entity)

Schedules an entity for dirty-checking at commit-time.

Parameters

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

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 entities in the identity map.

Return Value

int

EntityPersister getEntityPersister(string $entityName)

Gets the EntityPersister for an Entity.

Parameters

string $entityName The name of the Entity.

Return Value

EntityPersister

CollectionPersister getCollectionPersister(ToManyAssociationMetadata $association)

Gets a collection persister for a collection-valued association.

Parameters

ToManyAssociationMetadata $association

Return Value

CollectionPersister

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

INTERNAL: Registers an entity as managed.

Parameters

object $entity The entity.
array $id Map containing identifier field names as key and its associated values.
array $data The original entity data.

clearEntityChangeSet(string $oid)

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

Parameters

string $oid The entity's OID.

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

Notifies this UnitOfWork of a property change in an entity.

Parameters

object $entity The entity 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.

object[] getScheduledEntityInsertions()

Gets the currently scheduled entity insertions in this UnitOfWork.

Return Value

object[]

object[] getScheduledEntityUpdates()

Gets the currently scheduled entity updates in this UnitOfWork.

Return Value

object[]

object[] getScheduledEntityDeletions()

Gets the currently scheduled entity deletions in this UnitOfWork.

Return Value

object[]

Collection[]|object[][] getScheduledCollectionDeletions()

Gets the currently scheduled complete collection deletions

Return Value

Collection[]|object[][]

Collection[]|object[][] getScheduledCollectionUpdates()

Gets the currently scheduled collection inserts, updates and deletes.

Return Value

Collection[]|object[][]

initializeObject(object $obj)

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

Parameters

object $obj

markReadOnly(object $object)

Marks an entity as read-only so that it will not be considered for updates during UnitOfWork#commit().

This operation cannot be undone as some parts of the UnitOfWork now keep gathering information on this object that might be necessary to perform a correct update.

Parameters

object $object

Exceptions

ORMInvalidArgumentException

bool isReadOnly(object $object)

Is this entity read only?

Parameters

object $object

Return Value

bool

Exceptions

ORMInvalidArgumentException

hydrationComplete()

This method called by hydrators, and indicates that hydrator totally completed current hydration cycle.

Unit of work able to fire deferred events, related to loading events here.