Collection Documentation

CollectionTrait

Provides the shared implementation for {@see CollectionInterface} / {@see ExCollectionInterface}. The consuming class must declare the three properties below.

Table of Contents

Properties

$class  : string|null
$discrim  : string|null
$items  : array<string|int, mixed>

Methods

__debugInfo()  : array<string|int, mixed>
Returns an item that will be displayed for debugging.
__serialize()  : array<string|int, mixed>
Returns the string representation of the collection.
__unserialize()  : void
Unserializes the collection.
all()  : bool
Checks if all items match the callback.
any()  : bool
Checks if any item matches the callback.
clear()  : void
Clears the collection.
collect()  : ExCollectionInterface
Converts the items into a new collection.
count()  : int
Counts the amount of objects in the collection.
diff()  : ExCollectionInterface
Gets the difference between the items.
fill()  : self
Fills an array of items into the collection.
filter()  : ExCollectionInterface
Runs a filter callback over the collection and returns a new Collection based on the response of the callback.
find()  : mixed
Runs a filter callback over the collection and returns the first item where the callback returns `true` when given the item.
find_key()  : mixed
Finds the key of the first item that matches the callback.
first()  : mixed
Returns the first element of the collection.
get()  : mixed
Gets an item from the collection.
getIterator()  : Traversable
Returns an iterator for the collection.
has()  : bool
Checks if the array has multiple offsets.
intersect()  : ExCollectionInterface
Gets the intersection of the items.
isset()  : bool
If the collection has an offset.
jsonSerialize()  : array<string|int, mixed>
Serializes the object to a value that can be serialized natively by json_encode().
keys()  : array<string|int, int>|array<string|int, string>
Get the keys of the items.
last()  : mixed
Returns the last element of the collection.
map()  : ExCollectionInterface
Runs a callback over the collection and creates a new Collection.
merge()  : self
Merges another collection into this collection.
offsetExists()  : bool
If the collection has an offset.
offsetGet()  : mixed
Gets an item from the collection.
offsetSet()  : void
Sets an item into the collection.
offsetUnset()  : void
Unsets an index from the collection.
pull()  : mixed
Pulls an item from the collection.
push()  : self
Pushes items to the collection.
pushItem()  : self
Pushes a single item to the collection.
reduce()  : mixed
Reduces the collection to a single value using a callback function.
search()  : string|int|false
Searches for a given value within the collection and returns the corresponding key if successful.
serialize()  : string
Returns the string representation of the collection.
set()  : mixed
Sets a value in the collection.
shift()  : mixed
Shifts an item from the collection.
slice()  : ExCollectionInterface
Slices the collection.
sort()  : ExCollectionInterface
Sort through each item with a callback, a `SORT_*` flag, or `null` for a default ascending value sort.
splice()  : self
Splices the collection, removing a portion of the items and replacing them with the given replacement.
toArray()  : array<string|int, mixed>
Converts the collection to an array.
unique()  : ExCollectionInterface
Returns unique items.
unserialize()  : void
Unserializes the collection.
values()  : array<string|int, mixed>
Get the values of the items.
walk()  : ExCollectionInterface
Applies the given callback function to each item in the collection.

Properties

$class

public string|null $class

Class every item must be an instance of, or null.

$discrim

public string|null $discrim

The key used to index items (null = plain list).

$items

public array<string|int, mixed> $items

The items contained in the collection.

Methods

__debugInfo()

Returns an item that will be displayed for debugging.

public __debugInfo() : array<string|int, mixed>
Return values
array<string|int, mixed>

__serialize()

Returns the string representation of the collection.

public __serialize() : array<string|int, mixed>
Return values
array<string|int, mixed>

all()

Checks if all items match the callback.

public all(callable $callback) : bool
Parameters
$callback : callable
Return values
bool

any()

Checks if any item matches the callback.

public any(callable $callback) : bool
Parameters
$callback : callable
Return values
bool

count()

Counts the amount of objects in the collection.

public count() : int
Return values
int

diff()

Gets the difference between the items.

public diff(CollectionInterface|array<string|int, mixed> $items[, callable|null $callback = null ]) : ExCollectionInterface

If a callback is provided and is callable, it uses array_udiff_assoc to compute the difference. Otherwise, it uses array_diff (which compares elements as strings — pass a callback for collections of objects).

Parameters
$items : CollectionInterface|array<string|int, mixed>
$callback : callable|null = null
Return values
ExCollectionInterface

filter()

Runs a filter callback over the collection and returns a new Collection based on the response of the callback.

public filter(callable $callback) : ExCollectionInterface
Parameters
$callback : callable
Tags
todo

This method will be typed to return a CollectionInterface in v11

Return values
ExCollectionInterface

find()

Runs a filter callback over the collection and returns the first item where the callback returns `true` when given the item.

public find(callable $callback) : mixed
Parameters
$callback : callable
Return values
mixed —

null if no items returns true when called in the $callback.

find_key()

Finds the key of the first item that matches the callback.

public find_key(callable $callback) : mixed
Parameters
$callback : callable

first()

Returns the first element of the collection.

public first() : mixed

get()

Gets an item from the collection.

public get(string $discrim, mixed $key) : mixed
Parameters
$discrim : string
$key : mixed

getIterator()

Returns an iterator for the collection.

public getIterator() : Traversable
Return values
Traversable

has()

Checks if the array has multiple offsets.

public has(string|int ...$keys) : bool
Parameters
$keys : string|int
Return values
bool

intersect()

Gets the intersection of the items.

public intersect(CollectionInterface|array<string|int, mixed> $items[, callable|null $callback = null ]) : ExCollectionInterface

If a callback is provided and is callable, it uses array_uintersect_assoc to compute the intersection. Otherwise, it uses array_intersect (which compares elements as strings — pass a callback for collections of objects).

Parameters
$items : CollectionInterface|array<string|int, mixed>
$callback : callable|null = null
Return values
ExCollectionInterface

isset()

If the collection has an offset.

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

jsonSerialize()

Serializes the object to a value that can be serialized natively by json_encode().

public jsonSerialize([bool $assoc = true ]) : array<string|int, mixed>
Parameters
$assoc : bool = true

Whether to map keys to values.

Return values
array<string|int, mixed>

keys()

Get the keys of the items.

public keys() : array<string|int, int>|array<string|int, string>
Tags
since
10.2.0
Return values
array<string|int, int>|array<string|int, string>

last()

Returns the last element of the collection.

public last() : mixed

offsetExists()

If the collection has an offset.

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

offsetGet()

Gets an item from the collection.

public offsetGet(mixed $offset) : mixed
Parameters
$offset : mixed
Attributes
#[ReturnTypeWillChange]

offsetSet()

Sets an item into the collection.

public offsetSet(mixed $offset, mixed $value) : void
Parameters
$offset : mixed
$value : mixed

offsetUnset()

Unsets an index from the collection.

public offsetUnset(mixed $offset) : void
Parameters
$offset : mixed

pull()

Pulls an item from the collection.

public pull(mixed $key[, mixed $default = null ]) : mixed
Parameters
$key : mixed
$default : mixed = null

push()

Pushes items to the collection.

public push(mixed ...$items) : self
Parameters
$items : mixed
Return values
self

pushItem()

Pushes a single item to the collection.

public pushItem(mixed $item) : self
Parameters
$item : mixed
Return values
self

reduce()

Reduces the collection to a single value using a callback function.

public reduce(callable $callback[, mixed $initial = null ]) : mixed
Parameters
$callback : callable

fn ($carry, $item) => $carry

$initial : mixed = null
Return values
mixed —

The final value of $carry.

search()

Searches for a given value within the collection and returns the corresponding key if successful.

public search(mixed $needle[, bool $strict = false ]) : string|int|false
Parameters
$needle : mixed
$strict : bool = false

[optional]

Return values
string|int|false

serialize()

Returns the string representation of the collection.

public serialize([int $flags = 0 ][, int|null $depth = 512 ]) : string
Parameters
$flags : int = 0
$depth : int|null = 512
Return values
string

set()

Sets a value in the collection.

public set(mixed $offset, mixed $value) : mixed
Parameters
$offset : mixed
$value : mixed

splice()

Splices the collection, removing a portion of the items and replacing them with the given replacement.

public splice(int $offset, int|null $length[, mixed $replacement = [] ]) : self
Parameters
$offset : int
$length : int|null
$replacement : mixed = []
Return values
self

toArray()

Converts the collection to an array.

public toArray([bool $assoc = true ]) : array<string|int, mixed>

Use jsonSerialize

Parameters
$assoc : bool = true

Whether to map keys to values.

Return values
array<string|int, mixed>

unserialize()

Unserializes the collection.

public unserialize(string $serialized) : void
Parameters
$serialized : string

A string produced by serialize().

values()

Get the values of the items.

public values() : array<string|int, mixed>
Return values
array<string|int, mixed>
On this page

Search results