Class \Prado\Collections\TWeakCallableCollection

TWeakCallableCollection class

TWeakCallableCollection implements a priority ordered list collection of callables. This extends TPriorityList. This holds the callables for object event handlers and global event handlers by converting all callable objects into a WeakReference. TWeakCallableCollection prevents circular references in global events that would otherwise block object destruction, and thus removal of the callable in __destruct. All data out has the callable objects converted back to the regular object reference in a callable.

Closure and IWeakRetainable are not converted into WeakReference as they may be the only instance in the application. This increments their PHP use counter resulting in them being retained.

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. Put another way, searching for callable handlers will find TEventHandlers that use the handler.

This uses PHP 8 WeakMap to track any system changes to the weak references of objects the list is using -when \Prado\Collections\getDiscardInvalid is true. By default, when the map is read only then the items are not scrubbed, but the scrubbing behavior can be enabled for read only lists. In this instance, no new items can be added but only a list of valid callables is kept.

By default, lists that are mutable (aka. not read only) will discard invalid callables automatically, but the scrubbing behavior can be disabled for mutable lists if needed.

Class hierarchy

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

\Prado\Collections\TPriorityList implements IPriorityCollection uses TPriorityCollectionTrait

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

\Prado\TComponent

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

Methods summary
`public`	`__clone() : mixed` Cloning a TWeakCallableCollection requires cloning the WeakMap
`public`	`__construct([null\|array<string\|int, mixed>\|Iterator\|TPriorityList\|TPriorityMap $data = null ][, bool\|null $readOnly = null ][, numeric-string\|int\|float\|null $defaultPriority = null ][, null\|int $precision = null ][, bool\|null $discardInvalid = null ]) : mixed` Constructor. Initializes the list with an array or an iterable object.
`public`	`__wakeup() : mixed` Waking up a TWeakCallableCollection requires creating the WeakMap. No items are saved in TWeakList so only initialization of the WeakMap is required.
`public`	`clear() : void` Removes all items in the priority list by calling removeAtIndexInPriority from the last item to the first.
`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(callable &$handler[, bool $validate = false ]) : void` Converts the $handler callable into a WeakReference version for storage
`public static`	`filterItemForOutput(callable &$handler) : void` This converts the $items array of callable with WeakReferences back into the actual callable.
`public`	`getAutoGlobalListen() : bool` TWeakCallableCollection cannot auto listen to global events or there will be catastrophic recursion.
`public`	`getCount() : int` Returns the total number of items in the list 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. All invalid WeakReference[s] are optionally removed from the list before indexing. This method is required by the interface \IteratorAggregate.
`public`	`getPriorities() : array<string\|int, mixed>` This returns a list of the priorities within this list, ordered lowest (first) to highest (last). All invalid WeakReference[s] are optionally removed from the list before getting the priorities.
`public`	`getPriorityCount([null\|(numeric) $priority = null ]) : int` Gets the number of items at a priority within the list. All invalid WeakReference[s] are optionally removed from the list before counting.
`public`	`indexOf(mixed $item[, mixed $priority = false ]) : int` All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`insertAfter(mixed $indexitem, mixed $item) : int` This inserts an item after another item within the list. It uses the same priority as the found index item and places the new item after it. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`insertAt(int $index, mixed $item) : float\|null` Inserts an item at an index. It reads the priority of the item at index within the flattened list and then inserts the item at that priority-index. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`insertAtIndexInPriority(mixed $item[, null\|false\|int $index = null ][, null\|(numeric) $priority = null ][, bool $preserveCache = false ]) : mixed` Inserts an item at the specified index within a priority. This scrubs the list and calls {@see internalInsertAtIndexInPriority}. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`insertBefore(mixed $indexitem, mixed $item) : int` This inserts an item before another item within the list. It uses the same priority as the found index item and places the new item before it. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`itemAt(int $index) : mixed` Returns the item at the index of a flattened priority list. This is needed to filter the output. {@see offsetGet} calls this method. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`itemAtIndexInPriority(int $index[, null\|(numeric) $priority = null ]) : mixed` Returns the item at an index within a priority. This is needed to filter the output. All invalid WeakReference[s] are optionally removed from the list before retrieving.
`public`	`itemsAtPriority([null\|(numeric) $priority = null ]) : array<string\|int, mixed>\|null` Gets all the items at a specific priority. This is needed to filter the output. All invalid WeakReference[s] are optionally removed from the list before retrieving.
`public`	`mergeWith(mixed $data) : void` Merges iterable data into the priority list. New data will be appended to the end of the existing data. If another TPriorityList is merged, the incoming parameter items will be appended at the priorities they are present. These items will be added to the end of the existing items with equal priorities, if there are any.
`public`	`offsetSet(int $offset, mixed $item) : void` Sets the element at the specified offset. This method is required by the interface \ArrayAccess. Setting elements in a priority list is not straight forword when appending and setting at the end boundary. When appending without an offset (a null offset), the item will be added at the default priority. The item may not be the last item in the list. When appending with an offset equal to the count of the list, the item will get be appended with the last items priority. All together, when setting the location of an item, the item stays in that location, but appending an item into a priority list doesn't mean the item is at the end of the list. All invalid WeakReference[s] are optionally removed from the list when an $offset is given.
`public`	`priorityAt(int $index[, bool $withindex = false ]) : array<string\|int, mixed>\|false\|(numeric)` Returns the priority of an item at a particular flattened index. The index after the last item does not exist but receives a priority from the last item so that priority information about any new items being appended is available. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`priorityOf(mixed $item[, bool $withindex = false ]) : array<string\|int, mixed>\|false\|(numeric)` Returns the priority of a particular item. This is needed to filter the input. All invalid WeakReference[s] are optionally removed from the list before indexing when $withindex is "true" due to the more complex processing.
`public`	`remove(mixed $item[, null\|bool\|float $priority = false ]) : int` Removes an item from the priority list. The list will search for the item. The first matching 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 index in the flattened list. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`removeAtIndexInPriority(int $index[, null\|(numeric) $priority = null ]) : mixed` Removes the item at a specific index within a priority. This is needed to filter the output. All invalid WeakReference[s] are optionally removed from the list before indexing.
`public`	`setDiscardInvalid(null\|bool\|string $value) : void` All invalid WeakReference[s] are optionally removed from the list on $value being "true".
`public`	`toArray() : array<string\|int, mixed>` All invalid WeakReference[s] are optionally removed from the list before returning.
`public`	`toArrayAbovePriority(numeric-string\|int\|float $priority[, bool $inclusive = true ]) : array<string\|int, mixed>` Combines the map elements which have a priority above the parameter value. This is needed to filter the output. All invalid WeakReference[s] are optionally removed from the list before returning.
`public`	`toArrayBelowPriority(numeric-string\|int\|float $priority[, bool $inclusive = false ]) : array<string\|int, mixed>` Combines the map elements which have a priority below the parameter value. This is needed to filter the output. All invalid WeakReference[s] are optionally removed from the list before returning.
`public`	`toPriorityArray() : array<string\|int, mixed>` All invalid WeakReference[s] are optionally removed from the list before returning.
`public`	`toPriorityArrayWeak() : array<string\|int, mixed>` All invalid WeakReference[s] are optionally removed from the list before returning.
`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.
`protected`	`collapseDiscardInvalid() : mixed` Ensures that DiscardInvalid is set.
`protected`	`filterItemsForOutput(array<string\|int, mixed> &$items) : mixed` This converts the $items array of callable with WeakReferences back into the actual callable.
`protected`	`flattenPriorities() : void` This flattens the priority list into a flat array [0,...,n-1]. This is needed to filter the output. All invalid WeakReference[s] are optionally removed from the list before flattening.
`protected`	`internalInsertAtIndexInPriority(mixed $items[, null\|false\|int $index = null ][, null\|(numeric) $priority = null ][, bool $preserveCache = false ]) : mixed` Inserts an item at the specified index within a priority. This does not scrub the list of WeakReference. This converts the item into a WeakReference if it is an object or contains an object in its callable. This does not convert Closure into WeakReference.
`protected`	`internalRemoveAtIndexInPriority(int $index[, null\|(numeric) $priority = null ]) : mixed` Removes the item at a specific index within a priority. This is needed to filter the output.
`protected`	`scrubWeakReferences() : mixed` When a change in the WeakMap is detected, scrub the list of WeakReference that have lost their object. All invalid WeakReference[s] are optionally removed from the list when getDiscardInvalid is true.
`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, getDefaultPriority, getEventHandlers, getIterator, getListeningToGlobalEvents, getPrecision, getPriorities, getPriorityCount, getReadOnly, getSubProperty, hasEvent, hasEventHandler, hasMethod, hasProperty, indexOf, insertAfter, insertAt, insertAtIndexInPriority, insertBefore, isa, itemAt, itemAtIndexInPriority, itemsAtPriority, listen, mergeWith, offsetExists, offsetGet, offsetSet, offsetUnset, priorityAt, priorityOf, raiseEvent, remove, removeAt, removeAtIndexInPriority, setDefaultPriority, setPrecision, setReadOnly, setSubProperty, toArray, toArrayAbovePriority, toArrayBelowPriority, toPriorityArray, unlisten, _getZappableSleepProps, _priorityZappableSleepProps, _weakZappableSleepProps, collapseReadOnly, ensurePriority, flattenPriorities, getCallChain, getClassFxEvents, instanceBehavior, sortPriorities, weakAdd, weakChanged, weakClone, weakCount, weakObjectCount, weakRemove, weakResetCount, weakRestart, weakStart, weakStop, filter_prado_fx, getPriorityCombineStyle

Inherited constants
`\Prado\TComponent::GLOBAL_RAISE_EVENT_LISTENER`

Classes

Interfaces

Traits

Search results

Class \Prado\Collections\TWeakCallableCollection

Class hierarchy