PHP Class Doctrine\ORM\UnitOfWork

Since: 2.0
Author: Benjamin Eberlei ([email protected])
Author: Guilherme Blanco ([email protected])
Author: Jonathan Wage ([email protected])
Author: Roman Borschel ([email protected])
Inheritance: implements Doctrine\Common\PropertyChangedListener
Show file Open project: pmjones/php-framework-benchmarks Class Usage Examples

Public Methods

Method Description
__construct ( EntityManager $em ) Initializes a new UnitOfWork instance, bound to the given EntityManager.
addToIdentityMap ( object $entity ) : boolean INTERNAL: Registers an entity in the identity map.
clear ( ) Clears the UnitOfWork.
clearEntityChangeSet ( string $oid ) INTERNAL: Clears the property changeset of the entity with the given OID.
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.
computeChangeSet ( Doctrine\ORM\Mapping\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.
containsIdHash ( string $idHash, string $rootClassName ) : boolean INTERNAL: Checks whether an identifier hash exists in the identity map.
createEntity ( string $className, array $data, array &$hints = [] ) : object INTERNAL: Creates an entity. Used for reconstitution of persistent entities.
detach ( object $entity ) Detaches an entity from the persistence management. It's persistence will no longer be managed by Doctrine.
getByIdHash ( string $idHash, string $rootClassName ) : object INTERNAL: Gets an entity in the identity map by its identifier hash.
getCollectionPersister ( array $association ) : AbstractCollectionPersister Gets a collection persister for a collection-valued association.
getCommitOrderCalculator ( ) : Doctrine\ORM\Internal\CommitOrderCalculator Gets the CommitOrderCalculator used by the UnitOfWork to order commits.
getEntityChangeSet ( $entity ) : array Gets the changeset for an entity.
getEntityIdentifier ( object $entity ) : array Gets the identifier of an entity.
getEntityPersister ( string $entityName ) : Doctrine\ORM\Persister\AbstractEntityPersister Gets the EntityPersister for an Entity.
getEntityState ( object $entity, integer $assume = null ) : integer Gets the state of an entity with regard to the current unit of work.
getIdentityMap ( ) : array Gets the identity map of the UnitOfWork.
getOriginalEntityData ( object $entity ) : array 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.
getScheduledCollectionDeletions ( ) : array Get the currently scheduled complete collection deletions
getScheduledCollectionUpdates ( ) : array Gets the currently scheduled collection inserts, updates and deletes.
getScheduledEntityDeletions ( ) : array Gets the currently scheduled entity deletions in this UnitOfWork.
getScheduledEntityInsertions ( ) : array Gets the currently scheduled entity insertions in this UnitOfWork.
getScheduledEntityUpdates ( ) : array Gets the currently scheduled entity updates in this UnitOfWork.
hasPendingInsertions ( ) : boolean Checks whether the UnitOfWork has any pending insertions.
isCollectionScheduledForDeletion ( Doctrine\ORM\PersistentCollection $coll )
isEntityScheduled ( $entity ) : boolean Checks whether an entity is scheduled for insertion, update or deletion.
isInIdentityMap ( object $entity ) : boolean Checks whether an entity is registered in the identity map of this UnitOfWork.
isScheduledForDelete ( object $entity ) : boolean Checks whether an entity is registered as removed/deleted with the unit of work.
isScheduledForDirtyCheck ( $entity )
isScheduledForInsert ( object $entity ) : boolean Checks whether an entity is scheduled for insertion.
isScheduledForUpdate ( object $entity ) : boolean Checks whether an entity is registered as dirty in the unit of work.
loadCollection ( Doctrine\ORM\PersistentCollection $collection ) Initializes (loads) an uninitialized persistent collection of an entity.
lock ( object $entity, integer $lockMode, integer $lockVersion = null ) Acquire a lock on the given entity.
merge ( object $entity ) : object Merges the state of the given detached entity into this UnitOfWork.
persist ( object $entity ) Persists an entity as part of the current unit of work.
propertyChanged ( object $entity, string $propertyName, mixed $oldValue, mixed $newValue ) Notifies this UnitOfWork of a property change in an entity.
recomputeSingleEntityChangeSet ( Doctrine\ORM\Mapping\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().
refresh ( object $entity ) Refreshes the state of the given entity from the database, overwriting any local, unpersisted changes.
registerManaged ( object $entity, array $id, array $data ) INTERNAL: Registers an entity as managed.
remove ( object $entity ) Deletes an entity as part of the current unit of work.
removeFromIdentityMap ( object $entity ) : boolean INTERNAL: Removes an entity from the identity map. This effectively detaches the entity from the persistence management of Doctrine.
scheduleCollectionDeletion ( Doctrine\ORM\PersistentCollection $coll ) INTERNAL: Schedules a complete collection for removal when this UnitOfWork commits.
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.
scheduleForDelete ( object $entity ) INTERNAL: Schedules an entity for deletion.
scheduleForDirtyCheck ( object $entity ) Schedules an entity for dirty-checking at commit-time.
scheduleForInsert ( object $entity ) Schedules an entity for insertion into the database.
scheduleForUpdate ( object $entity ) Schedules an entity for being updated.
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.
setOriginalEntityData ( $entity, array $data )
setOriginalEntityProperty ( string $oid, string $property, mixed $value ) INTERNAL: Sets a property value of the original data array of an entity.
size ( ) : integer Calculates the size of the UnitOfWork. The size of the UnitOfWork is the number of entities in the identity map.
tryGetById ( mixed $id, string $rootClassName ) : mixed Tries to find an entity with the given identifier in the identity map of this UnitOfWork.
tryGetByIdHash ( string $idHash, string $rootClassName ) : mixed INTERNAL: Tries to get an entity by its identifier hash. If no entity is found for the given hash, FALSE is returned.

Private Methods

Method Description
cascadeDetach ( object $entity, array &$visited ) Cascades a detach operation to associated entities.
cascadeMerge ( object $entity, object $managedCopy, array &$visited ) Cascades a merge operation to associated entities.
cascadePersist ( object $entity, array &$visited ) Cascades the save operation to associated entities.
cascadeRefresh ( object $entity, array &$visited ) Cascades a refresh operation to associated entities.
cascadeRemove ( object $entity, array &$visited ) Cascades the delete operation to associated entities.
computeAssociationChanges ( AssociationMapping $assoc, mixed $value ) Computes the changes of an association.
doDetach ( object $entity, array &$visited ) Executes a detach operation on the given entity.
doMerge ( object $entity, array &$visited, $prevManagedCopy = null, $assoc = null ) : object Executes a merge operation on an entity.
doPersist ( object $entity, array &$visited ) Persists an entity as part of the current unit of work.
doRefresh ( object $entity, array &$visited ) Executes a refresh operation on an entity.
doRemove ( object $entity, array &$visited ) Deletes an entity as part of the current unit of work.
executeDeletions ( Doctrine\ORM\Mapping\ClassMetadata $class ) Executes all entity deletions for entities of the specified type.
executeExtraUpdates ( ) Executes any extra updates that have been scheduled.
executeInserts ( Doctrine\ORM\Mapping\ClassMetadata $class ) Executes all entity insertions for entities of the specified type.
executeUpdates ( Doctrine\ORM\Mapping\ClassMetadata $class ) Executes all entity updates for entities of the specified type.
getCommitOrder ( array $entityChangeSet = null ) : array Gets the commit order.
objToStr ( $obj )
persistNew ( $class, $entity )

Method Details

__construct() public method

Initializes a new UnitOfWork instance, bound to the given EntityManager.
public __construct ( EntityManager $em )
$em EntityManager

addToIdentityMap() public method

Note that entities in a hierarchy are registered with the class name of the root entity.
public addToIdentityMap ( object $entity ) : boolean
$entity object The entity to register.
return boolean TRUE if the registration was successful, FALSE if the identity of the entity in question is already managed.

clear() public method

Clears the UnitOfWork.
public clear ( )

clearEntityChangeSet() public method

INTERNAL: Clears the property changeset of the entity with the given OID.
public clearEntityChangeSet ( string $oid )
$oid string The entity's OID.

commit() public method

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
public commit ( )

computeChangeSet() public method

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.
public computeChangeSet ( Doctrine\ORM\Mapping\ClassMetadata $class, object $entity )
$class Doctrine\ORM\Mapping\ClassMetadata The class descriptor of the entity.
$entity object The entity for which to compute the changes.

computeChangeSets() public method

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.
public computeChangeSets ( )

containsIdHash() public method

INTERNAL: Checks whether an identifier hash exists in the identity map.
public containsIdHash ( string $idHash, string $rootClassName ) : boolean
$idHash string
$rootClassName string
return boolean

createEntity() public method

INTERNAL: Creates an entity. Used for reconstitution of persistent entities.
public createEntity ( string $className, array $data, array &$hints = [] ) : object
$className string The name of the entity class.
$data array The data for the entity.
$hints array Any hints to account for during reconstitution/lookup of the entity.
return object The managed entity instance.

detach() public method

Detaches an entity from the persistence management. It's persistence will no longer be managed by Doctrine.
public detach ( object $entity )
$entity object The entity to detach.

getByIdHash() public method

INTERNAL: Gets an entity in the identity map by its identifier hash.
public getByIdHash ( string $idHash, string $rootClassName ) : object
$idHash string
$rootClassName string
return object

getCollectionPersister() public method

Gets a collection persister for a collection-valued association.
public getCollectionPersister ( array $association ) : AbstractCollectionPersister
$association array
return AbstractCollectionPersister

getCommitOrderCalculator() public method

Gets the CommitOrderCalculator used by the UnitOfWork to order commits.
public getCommitOrderCalculator ( ) : Doctrine\ORM\Internal\CommitOrderCalculator
return Doctrine\ORM\Internal\CommitOrderCalculator

getEntityChangeSet() public method

Gets the changeset for an entity.
public getEntityChangeSet ( $entity ) : array
return array

getEntityIdentifier() public method

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().
public getEntityIdentifier ( object $entity ) : array
$entity object
return array The identifier values.

getEntityPersister() public method

Gets the EntityPersister for an Entity.
public getEntityPersister ( string $entityName ) : Doctrine\ORM\Persister\AbstractEntityPersister
$entityName string The name of the Entity.
return Doctrine\ORM\Persister\AbstractEntityPersister

getEntityState() public method

Gets the state of an entity with regard to the current unit of work.
public getEntityState ( object $entity, integer $assume = null ) : integer
$entity object
$assume integer 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 integer The entity state.

getIdentityMap() public method

Gets the identity map of the UnitOfWork.
public getIdentityMap ( ) : array
return array

getOriginalEntityData() public method

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.
public getOriginalEntityData ( object $entity ) : array
$entity object
return array

getScheduledCollectionDeletions() public method

Get the currently scheduled complete collection deletions
public getScheduledCollectionDeletions ( ) : array
return array

getScheduledCollectionUpdates() public method

Gets the currently scheduled collection inserts, updates and deletes.
public getScheduledCollectionUpdates ( ) : array
return array

getScheduledEntityDeletions() public method

Gets the currently scheduled entity deletions in this UnitOfWork.
public getScheduledEntityDeletions ( ) : array
return array

getScheduledEntityInsertions() public method

Gets the currently scheduled entity insertions in this UnitOfWork.
public getScheduledEntityInsertions ( ) : array
return array

getScheduledEntityUpdates() public method

Gets the currently scheduled entity updates in this UnitOfWork.
public getScheduledEntityUpdates ( ) : array
return array

hasPendingInsertions() public method

Checks whether the UnitOfWork has any pending insertions.
public hasPendingInsertions ( ) : boolean
return boolean TRUE if this UnitOfWork has pending insertions, FALSE otherwise.

isCollectionScheduledForDeletion() public method

public isCollectionScheduledForDeletion ( Doctrine\ORM\PersistentCollection $coll )
$coll Doctrine\ORM\PersistentCollection

isEntityScheduled() public method

Checks whether an entity is scheduled for insertion, update or deletion.
public isEntityScheduled ( $entity ) : boolean
$entity
return boolean

isInIdentityMap() public method

Checks whether an entity is registered in the identity map of this UnitOfWork.
public isInIdentityMap ( object $entity ) : boolean
$entity object
return boolean

isScheduledForDelete() public method

Checks whether an entity is registered as removed/deleted with the unit of work.
public isScheduledForDelete ( object $entity ) : boolean
$entity object
return boolean

isScheduledForDirtyCheck() public method

public isScheduledForDirtyCheck ( $entity )

isScheduledForInsert() public method

Checks whether an entity is scheduled for insertion.
public isScheduledForInsert ( object $entity ) : boolean
$entity object
return boolean

isScheduledForUpdate() public method

Note: Is not very useful currently as dirty entities are only registered at commit time.
public isScheduledForUpdate ( object $entity ) : boolean
$entity object
return boolean

loadCollection() public method

Initializes (loads) an uninitialized persistent collection of an entity.
public loadCollection ( Doctrine\ORM\PersistentCollection $collection )
$collection Doctrine\ORM\PersistentCollection The collection to initialize.

lock() public method

Acquire a lock on the given entity.
public lock ( object $entity, integer $lockMode, integer $lockVersion = null )
$entity object
$lockMode integer
$lockVersion integer

merge() public method

Merges the state of the given detached entity into this UnitOfWork.
public merge ( object $entity ) : object
$entity object
return object The managed copy of the entity.

persist() public method

Persists an entity as part of the current unit of work.
public persist ( object $entity )
$entity object The entity to persist.

propertyChanged() public method

Notifies this UnitOfWork of a property change in an entity.
public propertyChanged ( object $entity, string $propertyName, mixed $oldValue, mixed $newValue )
$entity object The entity that owns the property.
$propertyName string The name of the property that changed.
$oldValue mixed The old value of the property.
$newValue mixed The new value of the property.

recomputeSingleEntityChangeSet() public method

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.
public recomputeSingleEntityChangeSet ( Doctrine\ORM\Mapping\ClassMetadata $class, object $entity )
$class Doctrine\ORM\Mapping\ClassMetadata The class descriptor of the entity.
$entity object The entity for which to (re)calculate the change set.

refresh() public method

Refreshes the state of the given entity from the database, overwriting any local, unpersisted changes.
public refresh ( object $entity )
$entity object The entity to refresh.

registerManaged() public method

INTERNAL: Registers an entity as managed.
public registerManaged ( object $entity, array $id, array $data )
$entity object The entity.
$id array The identifier values.
$data array The original entity data.

remove() public method

Deletes an entity as part of the current unit of work.
public remove ( object $entity )
$entity object The entity to remove.

removeFromIdentityMap() public method

INTERNAL: Removes an entity from the identity map. This effectively detaches the entity from the persistence management of Doctrine.
public removeFromIdentityMap ( object $entity ) : boolean
$entity object
return boolean

scheduleCollectionDeletion() public method

INTERNAL: Schedules a complete collection for removal when this UnitOfWork commits.
public scheduleCollectionDeletion ( Doctrine\ORM\PersistentCollection $coll )
$coll Doctrine\ORM\PersistentCollection

scheduleExtraUpdate() public method

Extra updates for entities are stored as (entity, changeset) tuples.
public scheduleExtraUpdate ( object $entity, array $changeset )
$entity object The entity for which to schedule an extra update.
$changeset array The changeset of the entity (what to update).

scheduleForDelete() public method

INTERNAL: Schedules an entity for deletion.
public scheduleForDelete ( object $entity )
$entity object

scheduleForDirtyCheck() public method

Schedules an entity for dirty-checking at commit-time.
public scheduleForDirtyCheck ( object $entity )
$entity object The entity to schedule for dirty-checking.

scheduleForInsert() public method

If the entity already has an identifier, it will be added to the identity map.
public scheduleForInsert ( object $entity )
$entity object The entity to schedule for insertion.

scheduleForUpdate() public method

Schedules an entity for being updated.
public scheduleForUpdate ( object $entity )
$entity object The entity to schedule for being updated.

scheduleOrphanRemoval() public method

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.
public scheduleOrphanRemoval ( object $entity )
$entity object

setOriginalEntityData() public method

public setOriginalEntityData ( $entity, array $data )
$data array

setOriginalEntityProperty() public method

INTERNAL: Sets a property value of the original data array of an entity.
public setOriginalEntityProperty ( string $oid, string $property, mixed $value )
$oid string
$property string
$value mixed

size() public method

Calculates the size of the UnitOfWork. The size of the UnitOfWork is the number of entities in the identity map.
public size ( ) : integer
return integer

tryGetById() public method

Tries to find an entity with the given identifier in the identity map of this UnitOfWork.
public tryGetById ( mixed $id, string $rootClassName ) : mixed
$id mixed The entity identifier to look for.
$rootClassName string The name of the root class of the mapped entity hierarchy.
return mixed Returns the entity with the specified identifier if it exists in this UnitOfWork, FALSE otherwise.

tryGetByIdHash() public method

INTERNAL: Tries to get an entity by its identifier hash. If no entity is found for the given hash, FALSE is returned.
public tryGetByIdHash ( string $idHash, string $rootClassName ) : mixed
$idHash string
$rootClassName string
return mixed The found entity or FALSE.