Collection

Reference for the Collection module: small static helpers for working with arrays, maps, objects and optional values, plus a key-value element data object. Each helper class groups related operations behind static methods.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

CollectionArray - static helpers for reading and transforming arrays.
CollectionArrayElement - an immutable key and value element.
CollectionMap - static helper for reading a map entry.
CollectionObject - static helper for reading a field from an object, array or JSON.
CollectionOptional - static helpers for values that may be null.

CollectionArray

Static helpers for reading and transforming arrays: length and emptiness checks, construction, splitting, first and rest, iteration and mapping, and extracting unique field values from a list of objects.

Functions

Each Empty First From IfEmpty Length Map NotEmpty Rest Split UniqueFieldValues Zero

Each

CollectionArray::Each(array $array, callable $callback): void

Call the callback once for each element, passing the value and its key.

Name	Type	Description
`$array`	`array`	The array to iterate.
`$callback`	`callable`	Receives the value and the key.

Returns void

Empty

CollectionArray::Empty(array $array): bool

Whether the array has no elements.

Name	Type	Description
`$array`	`array`	The array to check.

Returns bool True when the array is empty.

First

CollectionArray::First(array $array): mixed

The first element of the array, or null when it is empty.

Name	Type	Description
`$array`	`array`	The array to read.

Returns mixed The first element, or null.

From

CollectionArray::From(mixed $element): array

A new array containing the single given element.

Name	Type	Description
`$element`	`mixed`	The element to wrap.

Returns array A one-element array.

IfEmpty

CollectionArray::IfEmpty(array $array, callable $onEmpty, callable $onNotEmpty): mixed

Call the onEmpty callback when the array is empty, otherwise the onNotEmpty callback, and return its result.

Name	Type	Description
`$array`	`array`	The array to check.
`$onEmpty`	`callable`	Called when the array is empty.
`$onNotEmpty`	`callable`	Called when the array is not empty.

Returns mixed The result of the callback that ran.

Length

CollectionArray::Length(array $array): int

The number of elements in the array.

Name	Type	Description
`$array`	`array`	The array to measure.

Returns int The element count.

Map

CollectionArray::Map(array $array, callable $callback): array

Build a new list by calling the callback with each value and key, collecting the returned values.

Name	Type	Description
`$array`	`array`	The array to map.
`$callback`	`callable`	Receives the value and the key, and returns the mapped value.

Returns array The mapped values.

NotEmpty

CollectionArray::NotEmpty(array $array): bool

Whether the array has at least one element.

Name	Type	Description
`$array`	`array`	The array to check.

Returns bool True when the array is not empty.

Rest

CollectionArray::Rest(array $array): array

Every element after the first, as a new array.

Name	Type	Description
`$array`	`array`	The array to read.

Returns array The array without its first element.

Split

CollectionArray::Split(array $array, callable $splitCallback): array

Split the array into piles, starting a new pile at each element for which the callback returns true. The splitting elements are dropped.

Name	Type	Description
`$array`	`array`	The array to split.
`$splitCallback`	`callable`	Returns true for an element that separates piles.

Returns array A list of piles, each itself an array.

UniqueFieldValues

CollectionArray::UniqueFieldValues(array $arrayOfObjects, string $fieldName, bool $sort = true): array

The unique, non-null values of a named field across a list of objects, sorted by default.

Name	Type	Description
`$arrayOfObjects`	`array`	The objects to read from.
`$fieldName`	`string`	The field to extract.
`$sort`	`bool`	Whether to sort the results.

Returns array The unique field values.

Zero

CollectionArray::Zero(): array

A new empty array.

Returns array An empty array.

CollectionArrayElement

An immutable key and value element. Fields and constructor only.

Properties

Property	Type	Description
`$element->key`	`string`	The element key (readonly).
`$element->value`	`mixed`	The element value (readonly).

Functions

__construct

new CollectionArrayElement(string $key, mixed $value)

Create an element from a key and a value.

Name	Type	Description
`$key`	`string`	The element key.
`$value`	`mixed`	The element value.

Returns CollectionArrayElement

CollectionMap

Static helper for reading an entry from a map keyed by any value.

Functions

EntryOptional

CollectionMap::EntryOptional(array $map, mixed $key): mixed

The value stored under a key, or null when the key is not present.

Name	Type	Description
`$map`	`array`	The map to read.
`$key`	`mixed`	The key to look up.

Returns mixed The value, or null.

CollectionObject

Static helper for reading a named field from an object, an array, or an object with a ToJson method, returning null when it cannot be read.

Functions

FieldOptional

CollectionObject::FieldOptional(mixed $object, string $fieldName): mixed

The value of a field, read from a ToJson result, an object property, or an array key. Returns null when the object is null, the field is missing, or the type does not match.

Name	Type	Description
`$object`	`mixed`	The object or array to read, which may be null.
`$fieldName`	`string`	The field name to access.

Returns mixed The field value, or null.

CollectionOptional

Static helpers for values that may be null: supplying a default, running a callback only when the value is present or only when it is absent, selecting between two outcomes, and testing presence.

Functions

Default If IfNot IsNone IsSome Select

Default

CollectionOptional::Default(mixed $optional, mixed $default): mixed

The value when it is not null, otherwise the given default.

Name	Type	Description
`$optional`	`mixed`	The value that may be null.
`$default`	`mixed`	The value to use when it is null.

Returns mixed The value, or the default.

If

CollectionOptional::If(mixed $optional, Callable $callable): mixed

Call the callback with the value when it is not null and return its result, otherwise return null.

Name	Type	Description
`$optional`	`mixed`	The value that may be null.
`$callable`	`callable`	Called with the value when it is present.

Returns mixed The callback result, or null.

IfNot

CollectionOptional::IfNot(mixed $optional, Callable $callable): mixed

Call the callback and return its result when the value is null, otherwise return null.

Name	Type	Description
`$optional`	`mixed`	The value that may be null.
`$callable`	`callable`	Called when the value is absent.

Returns mixed The callback result, or null.

IsNone

CollectionOptional::IsNone(mixed $optional): bool

Whether the value is null.

Name	Type	Description
`$optional`	`mixed`	The value to test.

Returns bool True when the value is null.

IsSome

CollectionOptional::IsSome(mixed $optional): bool

Whether the value is not null.

Name	Type	Description
`$optional`	`mixed`	The value to test.

Returns bool True when the value is not null.

Select

CollectionOptional::Select(mixed $optional, mixed $someCallback, mixed $noneCallback): mixed

Choose between two outcomes by presence: when the value is not null use someCallback, otherwise use noneCallback. Each argument may be a callable (invoked, with the value passed to someCallback) or a plain value returned directly.

Name	Type	Description
`$optional`	`mixed`	The value that may be null.
`$someCallback`	`mixed`	A callable called with the value, or a value returned when present.
`$noneCallback`	`mixed`	A callable called with no arguments, or a value returned when absent.

Returns mixed The chosen result.