Documentation

PersistentCollection extends AbstractLazyCollection
in package

Application

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.

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

$collection

The backed collection to use


    protected
        Collection<string|int, mixed>|null
    $collection

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

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

$typeClass

The class descriptor of the collection's entity type.


    private
        ClassMetadata|null
    $typeClass

__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

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

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

Return values

bool

containsKey()

{@inheritDoc}


    public
                    containsKey(mixed $key) : bool

Parameters

$key : mixed

Return values

bool

count()

{@inheritDoc}


    public
                    count() : int

Return values

int

current()

{@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>

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>

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>

Return values

array<string|int, mixed>

getTypeClass()


    public
                    getTypeClass() : ClassMetadata

Return values

ClassMetadata

getValues()

{@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

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

bool

isInitialized()

Is the lazy collection already initialized?


    public
                    isInitialized() : bool

Return values

bool

key()

{@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

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

bool

offsetGet()


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

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

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

UnitOfWork

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

PersistentCollection extends AbstractLazyCollection in package Application implements Selectable

Tags

Table of Contents

Interfaces

Properties

Methods

Properties

$collection

Tags

$initialized

$association

Tags

$backRefFieldName

$em

$isDirty

$owner

$snapshot

Tags

$typeClass

Methods

__clone()

__construct()

Parameters

Tags

__sleep()

Tags

Return values

add()

Parameters

Return values

clear()

contains()

Parameters

Tags

Return values

containsKey()

Parameters

Return values

count()

Return values

current()

exists()

Parameters

filter()

Parameters

Return values

first()

forAll()

Parameters

get()

Parameters

getDeleteDiff()

Return values

getInsertDiff()

Return values

getIterator()

Tags

Return values

getKeys()

getMapping()

Tags

Return values

getOwner()

Return values

getSnapshot()

Tags

Return values

getTypeClass()

Return values

getValues()

hydrateAdd()

Parameters

hydrateSet()

Parameters

indexOf()

Parameters

Tags

initialize()

isDirty()

Return values

PersistentCollection extends AbstractLazyCollection
in package

Application

implements Selectable