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

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

Methods

__construct(EntityManager $em)

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

void
commit(null|object|array $entity = null)

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.

array
getEntityChangeSet(object $entity)

Gets the changeset for an entity.

void
computeChangeSet(ClassMetadata $class, object $entity)

Computes the changes that happened to a single entity.

void
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.

void
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().

void
scheduleForInsert(object $entity)

Schedules an entity for insertion into the database.

boolean
isScheduledForInsert(object $entity)

Checks whether an entity is scheduled for insertion.

void
scheduleForUpdate(object $entity)

Schedules an entity for being updated.

void
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.

boolean
isScheduledForUpdate(object $entity)

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

boolean
isScheduledForDirtyCheck(object $entity)

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

void
scheduleForDelete(object $entity)

INTERNAL: Schedules an entity for deletion.

boolean
isScheduledForDelete(object $entity)

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

boolean
isEntityScheduled(object $entity)

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

boolean
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.

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

boolean
isInIdentityMap(object $entity)

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

boolean
containsIdHash(string $idHash, string $rootClassName)

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

void
persist(object $entity)

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

void
remove(object $entity)

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

object
merge(object $entity)

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

void
detach(object $entity)

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

void
refresh(object $entity)

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

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

Acquire a lock on the given entity.

getCommitOrderCalculator()

Gets the CommitOrderCalculator used by the UnitOfWork to order commits.

void
clear(string|null $entityName = null)

Clears the UnitOfWork.

void
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.

void
scheduleCollectionDeletion(PersistentCollection $coll)

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

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

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

void
triggerEagerLoads()

No description

void
loadCollection(PersistentCollection $collection)

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

array
getIdentityMap()

Gets the identity map of the UnitOfWork.

array
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.

void
setOriginalEntityData(object $entity, array $data)

No description

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

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

array
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 $id, string $rootClassName)

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

void
scheduleForDirtyCheck(object $entity)

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

boolean
hasPendingInsertions()

Checks whether the UnitOfWork has any pending insertions.

integer
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(array $association)

Gets a collection persister for a collection-valued association.

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

INTERNAL: Registers an entity as managed.

void
clearEntityChangeSet(string $oid)

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

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

Notifies this UnitOfWork of a property change in an entity.

array
getScheduledEntityInsertions()

Gets the currently scheduled entity insertions in this UnitOfWork.

array
getScheduledEntityUpdates()

Gets the currently scheduled entity updates in this UnitOfWork.

array
getScheduledEntityDeletions()

Gets the currently scheduled entity deletions in this UnitOfWork.

array
getScheduledCollectionDeletions()

Gets the currently scheduled complete collection deletions

array
getScheduledCollectionUpdates()

Gets the currently scheduled collection inserts, updates and deletes.

void
initializeObject(object $obj)

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

void
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?

Details

__construct(EntityManager $em)

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

Parameters

EntityManager $em

void commit(null|object|array $entity = null)

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

Parameters

null|object|array $entity

Return Value

void

Exceptions

Exception

array getEntityChangeSet(object $entity)

Gets the changeset for an entity.

Parameters

object $entity

Return Value

array

void 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.

Return Value

void

void 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.

Return Value

void

void 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.

Return Value

void

Exceptions

ORMInvalidArgumentException If the passed entity is not MANAGED.

void 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.

Return Value

void

Exceptions

ORMInvalidArgumentException
InvalidArgumentException

boolean isScheduledForInsert(object $entity)

Checks whether an entity is scheduled for insertion.

Parameters

object $entity

Return Value

boolean

void scheduleForUpdate(object $entity)

Schedules an entity for being updated.

Parameters

object $entity The entity to schedule for being updated.

Return Value

void

Exceptions

ORMInvalidArgumentException

void 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).

Return Value

void

boolean 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

Return Value

boolean

boolean isScheduledForDirtyCheck(object $entity)

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

Parameters

object $entity

Return Value

boolean

void scheduleForDelete(object $entity)

INTERNAL: Schedules an entity for deletion.

Parameters

object $entity

Return Value

void

boolean isScheduledForDelete(object $entity)

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

Parameters

object $entity

Return Value

boolean

boolean isEntityScheduled(object $entity)

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

Parameters

object $entity

Return Value

boolean

boolean 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

boolean 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.

boolean 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

boolean

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

string $idHash
string $rootClassName

Return Value

object|bool The found entity or FALSE.

boolean isInIdentityMap(object $entity)

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

Parameters

object $entity

Return Value

boolean

boolean containsIdHash(string $idHash, string $rootClassName)

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

Parameters

string $idHash
string $rootClassName

Return Value

boolean

void persist(object $entity)

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

Parameters

object $entity The entity to persist.

Return Value

void

void remove(object $entity)

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

Parameters

object $entity The entity to remove.

Return Value

void

object merge(object $entity)

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

Parameters

object $entity

Return Value

object The managed copy of the entity.

Exceptions

OptimisticLockException If the entity uses optimistic locking through a version attribute and the version check against the managed copy fails.

void detach(object $entity)

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

Parameters

object $entity The entity to detach.

Return Value

void

void 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.

Return Value

void

Exceptions

InvalidArgumentException If the entity is not MANAGED.

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

Acquire a lock on the given entity.

Parameters

object $entity
int $lockMode
int $lockVersion

Return Value

void

Exceptions

ORMInvalidArgumentException
TransactionRequiredException
OptimisticLockException

CommitOrderCalculator getCommitOrderCalculator()

Gets the CommitOrderCalculator used by the UnitOfWork to order commits.

Return Value

CommitOrderCalculator

void clear(string|null $entityName = null)

Clears the UnitOfWork.

Parameters

string|null $entityName if given, only entities of this type will get detached.

Return Value

void

void 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

Return Value

void

void scheduleCollectionDeletion(PersistentCollection $coll)

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

Parameters

PersistentCollection $coll

Return Value

void

bool isCollectionScheduledForDeletion(PersistentCollection $coll)

Parameters

PersistentCollection $coll

Return Value

bool

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

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

Parameters

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

Return Value

object The managed entity instance.

void triggerEagerLoads()

Return Value

void

void loadCollection(PersistentCollection $collection)

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

Parameters

PersistentCollection $collection The collection to initialize.

Return Value

void

array getIdentityMap()

Gets the identity map of the UnitOfWork.

Return Value

array

array 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

array

void setOriginalEntityData(object $entity, array $data)

Parameters

object $entity
array $data

Return Value

void

void 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

Return Value

void

array 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

array 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 $id, string $rootClassName)

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

Parameters

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.

void scheduleForDirtyCheck(object $entity)

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

Parameters

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

Return Value

void

boolean hasPendingInsertions()

Checks whether the UnitOfWork has any pending insertions.

Return Value

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

integer size()

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

Return Value

integer

BasicEntityPersister getEntityPersister(string $entityName)

Gets the EntityPersister for an Entity.

Parameters

string $entityName The name of the Entity.

Return Value

BasicEntityPersister

AbstractCollectionPersister getCollectionPersister(array $association)

Gets a collection persister for a collection-valued association.

Parameters

array $association

Return Value

AbstractCollectionPersister

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

INTERNAL: Registers an entity as managed.

Parameters

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

Return Value

void

void clearEntityChangeSet(string $oid)

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

Parameters

string $oid The entity's OID.

Return Value

void

void 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.

Return Value

void

array getScheduledEntityInsertions()

Gets the currently scheduled entity insertions in this UnitOfWork.

Return Value

array

array getScheduledEntityUpdates()

Gets the currently scheduled entity updates in this UnitOfWork.

Return Value

array

array getScheduledEntityDeletions()

Gets the currently scheduled entity deletions in this UnitOfWork.

Return Value

array

array getScheduledCollectionDeletions()

Gets the currently scheduled complete collection deletions

Return Value

array

array getScheduledCollectionUpdates()

Gets the currently scheduled collection inserts, updates and deletes.

Return Value

array

void initializeObject(object $obj)

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

Parameters

object $obj

Return Value

void

void 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

Return Value

void

Exceptions

ORMInvalidArgumentException

bool isReadOnly(object $object)

Is this entity read only?

Parameters

object $object

Return Value

bool

Exceptions

ORMInvalidArgumentException