Class \Prado\Collections\TWeakList

TWeakList class

TWeakList implements an integer-indexed collection class with objects kept as WeakReference. Closure are treated as function PHP types rather than as objects.

Objects in the TWeakList are encoded into WeakReference when saved, and the objects restored on retrieval. When an object becomes unset in the application/system and its WeakReference invalidated, it can be removed from the TWeakList or have a null in place of the object, depending on the mode. The mode can be set during \Prado\Collections__construct. The default mode of the TWeakList is to maintain a list of only valid objects -where the count and item locations can change when an item is invalidated-. The other mode is to retain the place of invalidated objects and replace the object with null -maintaining the count and item locations-.

List items do not need to be objects. TWeakList is similar to TList except list items that are objects (except Closure and IWeakRetainable) are stored as WeakReference. List items that are arrays are recursively traversed for replacement of objects with WeakReference before storing. In this way, TWeakList will not retain objects (incrementing their use/reference counter) that it contains. Only primary list items are tracked with the WeakMap, and objects in arrays has no effect on the whole. If an object in an array is invalidated, it well be replaced by "null". Arrays in the TWeakList are kept regardless of the use/reference count of contained objects.

When searching by a TEventHandler object, it will only find itself and will not match on its TEventHandler::getHandler. However, if searching for a callable handler, it will first match direct callable handlers in the list, and then search for matching TEventHandlers' Handler regardless of the data.

TWeakCollectionTrait implements a PHP 8 WeakMap used to track any changes in WeakReference objects in the TWeakList and optionally scrubs the list of invalid objects on any changes to the WeakMap.

Note that any objects or objects in arrays will be lost if they are not otherwise retained in other parts of the application. The only exception is a PHP Closure. Closures are stored without WeakReference so anonymous functions can be stored without risk of deletion if it is the only reference. Closures act similarly to a PHP data type rather than an object.

Class hierarchy

\Prado\Collections\TWeakList implements IWeakCollection, ICollectionFilter uses TWeakCollectionTrait

\Prado\Collections\TList implements IteratorAggregate, ArrayAccess, Countable

\Prado\TComponent

Author: Brad Anderson <belisoful@icloud.com>
Since: 4.3.0

Methods summary
`public`	`__clone() : mixed` Cloning a TWeakList requires cloning the WeakMap
`public`	`__construct([null\|array<string\|int, mixed>\|Iterator $data = null ][, bool\|null $readOnly = null ][, bool\|null $discardInvalid = null ]) : mixed` Constructor. Initializes the weak list with an array or an iterable object.
`public`	`__wakeup() : mixed` Waking up a TWeakList requires creating the WeakMap. No items are saved in TWeakList so only initialization of the WeakMap is required.
`public`	`add(mixed $item) : int` Appends an item at the end of the list. All invalid WeakReference[s] are optionally removed from the list before adding for proper indexing.
`public`	`clear() : void` Removes all items in the list and resets the Weak Cache.
`public`	`contains(mixed $item) : bool`
`public`	`copyFrom(mixed $data) : void` Copies iterable data into the list. Note, existing data in the list will be cleared first.
`public static`	`filterItemForInput(mixed &$item) : void` Converts the $item object and objects in an array into their WeakReference version for storage. Closure[s] are not converted into WeakReference and so act like a basic PHP type. Closures are added to the the WeakMap cache but has no weak effect because the TWeakList maintains references to Closure[s] preventing their invalidation.
`public static`	`filterItemForOutput(mixed &$item) : void` Converts the $item callable that has WeakReference rather than the actual object back into a regular callable.
`public`	`getCount() : int` All invalid WeakReference[s] are optionally removed from the list before counting.
`public`	`getDiscardInvalid() : bool`
`public`	`getIterator() : Iterator` Returns an iterator for traversing the items in the list. This method is required by the interface \IteratorAggregate. All invalid WeakReference[s] are optionally removed from the iterated list.
`public`	`indexOf(mixed $item) : int` All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`insertAfter(mixed $baseitem, mixed $item) : int` Finds the base item. If found, the item is inserted after it. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`insertAt(int $index, mixed $item) : mixed` Inserts an item at the specified position. Original item at the position and the next items will be moved one step towards the end. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`insertBefore(mixed $baseitem, mixed $item) : int` Finds the base item. If found, the item is inserted before it. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`itemAt(int $index) : mixed` Returns the item at the specified offset. This method is exactly the same as offsetGet. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`mergeWith(mixed $data) : void` Merges iterable data into the map. New data will be appended to the end of the existing data.
`public`	`offsetExists(int $offset) : bool` Returns whether there is an item at the specified offset. This method is required by the interface \ArrayAccess. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`offsetSet(int $offset, mixed $item) : void` Sets the item at the specified offset. This method is required by the interface \ArrayAccess. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`remove(mixed $item) : int` Removes an item from the list. The list will first search for the item. The first item found will be removed from the list. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`removeAt(int $index) : mixed` Removes an item at the specified position. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`setDiscardInvalid(bool $value) : void`
`public`	`toArray() : array<string\|int, mixed>` All invalid WeakReference[s] are optionally removed from the list.
`protected`	`_getZappableSleepProps(array<string\|int, mixed> &$exprops) : mixed` Returns an array with the names of all variables of this object that should NOT be serialized because their value is the default one or useless to be cached for the next page loads. Reimplement in derived classes to add new variables, but remember to also to call the parent implementation first. Due to being weak, the TWeakList is not serialized. The count is artificially made zero so the parent has no values to save.
`protected`	`collapseDiscardInvalid() : mixed` Ensures that DiscardInvalid is set.
`protected`	`scrubWeakReferences() : void` When a change in the WeakMap is detected, scrub the list of invalid WeakReference.
`protected`	`weakCustomAdd(object $object) : mixed` This is a custom function for adding objects to the weak map. Specifically, if the object being added is a TEventHandler, we use the {@see \Prado\TEventHandler::getHandlerObject} object instead of the TEventHandler itself.
`protected`	`weakCustomRemove(object $object) : mixed` This is a custom function for removing objects to the weak map. Specifically, if the object being removed is a TEventHandler, we use the {@see \Prado\TEventHandler::getHandlerObject} object instead of the TEventHandler itself.

Inherited methods
__call, __callStatic, __clone, __construct, __destruct, __get, __isset, __set, __sleep, __unset, __wakeup, add, addParsedObject, asa, attachBehavior, attachBehaviors, attachClassBehavior, attachEventHandler, callBehaviorsMethod, canGetProperty, canSetProperty, clear, clearBehaviors, contains, copyFrom, count, createdOnTemplate, detachBehavior, detachBehaviors, detachClassBehavior, detachEventHandler, disableBehavior, disableBehaviors, enableBehavior, enableBehaviors, evaluateExpression, evaluateStatements, fxAttachClassBehavior, fxDetachClassBehavior, getAutoGlobalListen, getBehaviors, getBehaviorsEnabled, getClassHierarchy, getCount, getEventHandlers, getIterator, getListeningToGlobalEvents, getReadOnly, getSubProperty, hasEvent, hasEventHandler, hasMethod, hasProperty, indexOf, insertAfter, insertAt, insertBefore, isa, itemAt, listen, mergeWith, offsetExists, offsetGet, offsetSet, offsetUnset, raiseEvent, remove, removeAt, setReadOnly, setSubProperty, toArray, unlisten, _getZappableSleepProps, _weakZappableSleepProps, collapseReadOnly, getCallChain, getClassFxEvents, instanceBehavior, weakAdd, weakChanged, weakClone, weakCount, weakObjectCount, weakRemove, weakResetCount, weakRestart, weakStart, weakStop, filter_prado_fx

Inherited constants
`\Prado\TComponent::GLOBAL_RAISE_EVENT_LISTENER`

Classes

Interfaces

Traits

Search results

Class \Prado\Collections\TWeakList

Class hierarchy