Documentation

PersistentCollection extends AbstractLazyCollection
in package
implements Selectable

FinalYes

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
psalm-template

TKey of array-key

psalm-template

T

template-extends

AbstractLazyCollection<TKey,T>

template-implements

Selectable<TKey,T>

psalm-import-type

AssociationMapping from ClassMetadata

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

$association

The association mapping the collection belongs to.

private mixed $association

This is currently either a OneToManyMapping or a ManyToManyMapping.

Tags
psalm-var

AssociationMapping|null

$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

$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

$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
psalm-var

array<string|int, mixed>

Methods

__clone()

Cleans up internal state of cloned persistent collection.

public __clone() : mixed

The following problems have to be prevented:

  1. Added entities are added to old PC
  2. New collection is not dirty, if reused on other entity nothing changes.
  3. Snapshot leads to invalid diffs being generated.
  4. Lazy loading grabs entities from old owner object.
  5. New collection is connected to old owner and leads to duplicate keys.

__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
psalm-return

array{0: string, 1: string}

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.

contains()

{@inheritDoc}

public contains(mixed $element) : bool
Parameters
$element : mixed
Tags
template

TMaybeContained

Return values
bool

containsKey()

{@inheritDoc}

public containsKey(mixed $key) : bool
Parameters
$key : mixed
Return values
bool

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.

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
psalm-return

Traversable<TKey,T>

Return values
Traversable<int|string, mixed>

getMapping()

INTERNAL: Gets the association mapping of the collection.

public getMapping() : array<string|int, mixed>
Tags
psalm-return

AssociationMapping

Return values
array<string|int, mixed>

getOwner()

INTERNAL: Gets the collection owner.

public getOwner() : object|null
Return values
object|null

getSnapshot()

INTERNAL: Returns the last snapshot of the elements in the collection.

public getSnapshot() : array<string|int, mixed>
Tags
psalm-return

array<string|int, mixed> The last snapshot of the elements.

Return values
array<string|int, 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
template

TMaybeContained

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.

isInitialized()

Is the lazy collection already initialized?

public isInitialized() : bool
Tags
psalm-assert-if-true

Collection<TKey,T> $this->collection

Return values
bool

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
psalm-return

Collection<TKey, T>

throws
RuntimeException
Return values
Collection<string|int, mixed>|Selectable<string|int, mixed>

offsetExists()

public offsetExists(mixed $offset) : bool
Parameters
$offset : mixed
Return values
bool

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

partition()

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
psalm-param

AssociationMapping $assoc

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
psalm-return

array<TKey,T>

Return values
array<string|int, mixed>

takeSnapshot()

INTERNAL: Tells this collection to take a snapshot of its current state.

public takeSnapshot() : void

restoreNewObjectsInDirtyCollection()

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 using array_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


        
On this page

Search results