PersistentCollection
extends AbstractLazyCollection
in package
implements
Selectable
A PersistentCollection represents a collection of elements that have persistent state.
Collections of entities represent only the associations (links) to those entities. That means, if the collection is part of a many-many mapping and you remove entities from the collection, only the links in the relation table are removed (on flush). Similarly, if you remove entities from a collection that is part of a one-many mapping this will only result in the nulling out of the foreign keys on flush.
Tags
Table of Contents
Interfaces
- Selectable
- Interface for collections that allow efficient filtering with an expression API.
Properties
- $collection : Collection<string|int, mixed>|null
- The backed collection to use
- $initialized : bool
- $association : mixed
- The association mapping the collection belongs to.
- $backRefFieldName : string|null
- The name of the field on the target entities that points to the owner of the collection. This is only set if the association is bi-directional.
- $em : EntityManagerInterface|null
- The EntityManager that manages the persistence of the collection.
- $isDirty : bool
- Whether the collection is dirty and needs to be synchronized with the database when the UnitOfWork that manages its persistent state commits.
- $owner : object|null
- The entity that owns this collection.
- $snapshot : mixed
- A snapshot of the collection at the moment it was fetched from the database.
- $typeClass : ClassMetadata|null
- The class descriptor of the collection's entity type.
Methods
- __clone() : mixed
- Cleans up internal state of cloned persistent collection.
- __construct() : mixed
- Creates a new persistent collection.
- __sleep() : array<string|int, string>
- Called by PHP when this collection is serialized. Ensures that only the elements are properly serialized.
- add() : true
- Adds an element at the end of the collection.
- clear() : void
- Clears the collection, removing all elements.
- contains() : bool
- {@inheritDoc}
- containsKey() : bool
- {@inheritDoc}
- count() : int
- {@inheritDoc}
- current() : mixed
- {@inheritDoc}
- exists() : mixed
- {@inheritDoc}
- filter() : Collection<string|int, mixed>
- Returns all the elements of this collection that satisfy the predicate p.
- first() : mixed
- {@inheritDoc}
- forAll() : mixed
- {@inheritDoc}
- get() : mixed
- {@inheritDoc}
- getDeleteDiff() : array<string|int, mixed>
- INTERNAL: getDeleteDiff
- getInsertDiff() : array<string|int, mixed>
- INTERNAL: getInsertDiff
- getIterator() : Traversable<int|string, mixed>
- {@inheritDoc}
- getKeys() : mixed
- {@inheritDoc}
- getMapping() : array<string|int, mixed>
- INTERNAL: Gets the association mapping of the collection.
- getOwner() : object|null
- INTERNAL: Gets the collection owner.
- getSnapshot() : array<string|int, mixed>
- INTERNAL: Returns the last snapshot of the elements in the collection.
- getTypeClass() : ClassMetadata
- getValues() : mixed
- {@inheritDoc}
- hydrateAdd() : void
- INTERNAL: Adds an element to a collection during hydration. This will automatically complete bidirectional associations in the case of a one-to-many association.
- hydrateSet() : void
- INTERNAL: Sets a keyed element in the collection during hydration.
- indexOf() : mixed
- {@inheritDoc}
- initialize() : void
- Initializes the collection by loading its contents from the database if the collection is not yet initialized.
- isDirty() : bool
- Gets a boolean flag indicating whether this collection is dirty which means its state needs to be synchronized with the database.
- isEmpty() : bool
- {@inheritDoc}
- isInitialized() : bool
- Is the lazy collection already initialized?
- key() : mixed
- {@inheritDoc}
- last() : mixed
- {@inheritDoc}
- map() : mixed
- {@inheritDoc}
- matching() : Collection<string|int, mixed>|Selectable<string|int, mixed>
- Selects all elements from a selectable that match the expression and return a new collection containing these elements.
- next() : mixed
- {@inheritDoc}
- offsetExists() : bool
- offsetGet() : mixed
- offsetSet() : void
- offsetUnset() : object|null
- partition() : array<string|int, Collection<string|int, mixed>>
- Partitions this collection in two collections according to a predicate.
- remove() : mixed
- Removes the element at the specified index from the collection.
- removeElement() : bool
- Removes the specified element from the collection, if it is found.
- set() : void
- Sets an element in the collection at the specified key/index.
- setDirty() : void
- Sets a boolean flag, indicating whether this collection is dirty.
- setInitialized() : void
- Sets the initialized flag of the collection, forcing it into that state.
- setOwner() : void
- INTERNAL: Sets the collection's owning entity together with the AssociationMapping that describes the association between the owner and the elements of the collection.
- slice() : array<string|int, mixed>
- Extracts a slice of $length elements starting at position $offset from the Collection.
- takeSnapshot() : void
- INTERNAL: Tells this collection to take a snapshot of its current state.
- toArray() : mixed
- {@inheritDoc}
- unwrap() : Collection<TKey, T>|Selectable<TKey, T>
- Retrieves the wrapped Collection instance.
- doInitialize() : void
- Do the initialization logic
- changed() : void
- Marks this collection as changed/dirty.
- getUnitOfWork() : UnitOfWork
- restoreNewObjectsInDirtyCollection() : void
Properties
$collection
The backed collection to use
protected
Collection<string|int, mixed>|null
$collection
Tags
$initialized
protected
bool
$initialized
= false
$association
The association mapping the collection belongs to.
private
mixed
$association
This is currently either a OneToManyMapping or a ManyToManyMapping.
Tags
$backRefFieldName
The name of the field on the target entities that points to the owner of the collection. This is only set if the association is bi-directional.
private
string|null
$backRefFieldName
$em
The EntityManager that manages the persistence of the collection.
private
EntityManagerInterface|null
$em
$isDirty
Whether the collection is dirty and needs to be synchronized with the database when the UnitOfWork that manages its persistent state commits.
private
bool
$isDirty
= false
$owner
The entity that owns this collection.
private
object|null
$owner
$snapshot
A snapshot of the collection at the moment it was fetched from the database.
private
mixed
$snapshot
= []
This is used to create a diff of the collection at commit time.
Tags
$typeClass
The class descriptor of the collection's entity type.
private
ClassMetadata|null
$typeClass
Methods
__clone()
Cleans up internal state of cloned persistent collection.
public
__clone() : mixed
The following problems have to be prevented:
- Added entities are added to old PC
- New collection is not dirty, if reused on other entity nothing changes.
- Snapshot leads to invalid diffs being generated.
- Lazy loading grabs entities from old owner object.
- New collection is connected to old owner and leads to duplicate keys.
__construct()
Creates a new persistent collection.
public
__construct(EntityManagerInterface $em, ClassMetadata $class, Collection $collection) : mixed
Parameters
- $em : EntityManagerInterface
-
The EntityManager the collection will be associated with.
- $class : ClassMetadata
-
The class descriptor of the entity type of this collection.
- $collection : Collection
Tags
__sleep()
Called by PHP when this collection is serialized. Ensures that only the elements are properly serialized.
public
__sleep() : array<string|int, string>
Internal note: Tried to implement Serializable first but that did not work well with circular references. This solution seems simpler and works well.
Tags
Return values
array<string|int, string>add()
Adds an element at the end of the collection.
public
add(mixed $value) : true
Parameters
- $value : mixed
Return values
true —Always TRUE.
clear()
Clears the collection, removing all elements.
public
clear() : void
contains()
{@inheritDoc}
public
contains(mixed $element) : bool
Parameters
- $element : mixed
Tags
Return values
boolcontainsKey()
{@inheritDoc}
public
containsKey(mixed $key) : bool
Parameters
- $key : mixed
Return values
boolcount()
{@inheritDoc}
public
count() : int
Return values
intcurrent()
{@inheritDoc}
public
current() : mixed
exists()
{@inheritDoc}
public
exists(Closure $p) : mixed
Parameters
- $p : Closure
filter()
Returns all the elements of this collection that satisfy the predicate p.
public
filter(Closure $p) : Collection<string|int, mixed>
Parameters
- $p : Closure
-
The predicate used for filtering.
Return values
Collection<string|int, mixed> —A collection with the results of the filter operation.
first()
{@inheritDoc}
public
first() : mixed
forAll()
{@inheritDoc}
public
forAll(Closure $p) : mixed
Parameters
- $p : Closure
get()
{@inheritDoc}
public
get(mixed $key) : mixed
Parameters
- $key : mixed
getDeleteDiff()
INTERNAL: getDeleteDiff
public
getDeleteDiff() : array<string|int, mixed>
Return values
array<string|int, mixed>getInsertDiff()
INTERNAL: getInsertDiff
public
getInsertDiff() : array<string|int, mixed>
Return values
array<string|int, mixed>getIterator()
{@inheritDoc}
public
getIterator() : Traversable<int|string, mixed>
Tags
Return values
Traversable<int|string, mixed>getKeys()
{@inheritDoc}
public
getKeys() : mixed
getMapping()
INTERNAL: Gets the association mapping of the collection.
public
getMapping() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>getOwner()
INTERNAL: Gets the collection owner.
public
getOwner() : object|null
Return values
object|nullgetSnapshot()
INTERNAL: Returns the last snapshot of the elements in the collection.
public
getSnapshot() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>getTypeClass()
public
getTypeClass() : ClassMetadata
Return values
ClassMetadatagetValues()
{@inheritDoc}
public
getValues() : mixed
hydrateAdd()
INTERNAL: Adds an element to a collection during hydration. This will automatically complete bidirectional associations in the case of a one-to-many association.
public
hydrateAdd(mixed $element) : void
Parameters
- $element : mixed
-
The element to add.
hydrateSet()
INTERNAL: Sets a keyed element in the collection during hydration.
public
hydrateSet(mixed $key, mixed $element) : void
Parameters
- $key : mixed
-
The key to set.
- $element : mixed
-
The element to set.
indexOf()
{@inheritDoc}
public
indexOf(mixed $element) : mixed
Parameters
- $element : mixed
Tags
initialize()
Initializes the collection by loading its contents from the database if the collection is not yet initialized.
public
initialize() : void
isDirty()
Gets a boolean flag indicating whether this collection is dirty which means its state needs to be synchronized with the database.
public
isDirty() : bool
Return values
bool —TRUE if the collection is dirty, FALSE otherwise.
isEmpty()
{@inheritDoc}
public
isEmpty() : bool
Return values
boolisInitialized()
Is the lazy collection already initialized?
public
isInitialized() : bool
Tags
Return values
boolkey()
{@inheritDoc}
public
key() : mixed
last()
{@inheritDoc}
public
last() : mixed
map()
{@inheritDoc}
public
map(Closure $func) : mixed
Parameters
- $func : Closure
matching()
Selects all elements from a selectable that match the expression and return a new collection containing these elements.
public
matching(Criteria $criteria) : Collection<string|int, mixed>|Selectable<string|int, mixed>
Parameters
- $criteria : Criteria
Tags
Return values
Collection<string|int, mixed>|Selectable<string|int, mixed>next()
{@inheritDoc}
public
next() : mixed
offsetExists()
public
offsetExists(mixed $offset) : bool
Parameters
- $offset : mixed
Return values
booloffsetGet()
public
offsetGet(mixed $offset) : mixed
Parameters
- $offset : mixed
offsetSet()
public
offsetSet(mixed $offset, mixed $value) : void
Parameters
- $offset : mixed
- $value : mixed
offsetUnset()
public
offsetUnset(mixed $offset) : object|null
Parameters
- $offset : mixed
Return values
object|nullpartition()
Partitions this collection in two collections according to a predicate.
public
partition(Closure $p) : array<string|int, Collection<string|int, mixed>>
Parameters
- $p : Closure
-
The predicate on which to partition.
Return values
array<string|int, Collection<string|int, mixed>> —An array with two elements. The first element contains the collection of elements where the predicate returned TRUE, the second element contains the collection of elements where the predicate returned FALSE.
remove()
Removes the element at the specified index from the collection.
public
remove(mixed $key) : mixed
Parameters
- $key : mixed
-
The key/index of the element to remove.
Return values
mixed —The removed element or NULL, if the collection did not contain the element.
removeElement()
Removes the specified element from the collection, if it is found.
public
removeElement(mixed $element) : bool
Parameters
- $element : mixed
-
The element to remove.
Return values
bool —TRUE if this collection contained the specified element, FALSE otherwise.
set()
Sets an element in the collection at the specified key/index.
public
set(mixed $key, mixed $value) : void
Parameters
- $key : mixed
-
The key/index of the element to set.
- $value : mixed
-
The element to set.
setDirty()
Sets a boolean flag, indicating whether this collection is dirty.
public
setDirty(bool $dirty) : void
Parameters
- $dirty : bool
-
Whether the collection should be marked dirty or not.
setInitialized()
Sets the initialized flag of the collection, forcing it into that state.
public
setInitialized(bool $bool) : void
Parameters
- $bool : bool
setOwner()
INTERNAL: Sets the collection's owning entity together with the AssociationMapping that describes the association between the owner and the elements of the collection.
public
setOwner(object $entity, array<string|int, mixed> $assoc) : void
Parameters
- $entity : object
- $assoc : array<string|int, mixed>
Tags
slice()
Extracts a slice of $length elements starting at position $offset from the Collection.
public
slice(int $offset[, int|null $length = null ]) : array<string|int, mixed>
If $length is null it returns all elements from $offset to the end of the Collection. Keys have to be preserved by this method. Calling this method will only return the selected slice and NOT change the elements contained in the collection slice is called on.
Parameters
- $offset : int
- $length : int|null = null
Tags
Return values
array<string|int, mixed>takeSnapshot()
INTERNAL: Tells this collection to take a snapshot of its current state.
public
takeSnapshot() : void
toArray()
{@inheritDoc}
public
toArray() : mixed
unwrap()
Retrieves the wrapped Collection instance.
public
unwrap() : Collection<TKey, T>|Selectable<TKey, T>
Return values
Collection<TKey, T>|Selectable<TKey, T>doInitialize()
Do the initialization logic
protected
doInitialize() : void
changed()
Marks this collection as changed/dirty.
private
changed() : void
getUnitOfWork()
private
getUnitOfWork() : UnitOfWork
Return values
UnitOfWorkrestoreNewObjectsInDirtyCollection()
private
restoreNewObjectsInDirtyCollection(array<string|int, object> $newObjects) : void
Parameters
- $newObjects : array<string|int, object>
-
Note: the only reason why this entire looping/complexity is performed via
spl_object_id
is because we want to prevent usingarray_udiff()
, which is likely to cause very high overhead (complexity of O(n^2)).array_diff_key()
performs the operation in core, which is faster than using a callback for comparisons