Usage Reference

Usage Reference#

This page is usage-first. Use it to pick the right feature quickly, then go deeper in the dedicated guide pages.

If you need exact method signatures, see the Exact API Signatures section at the end of this page.

How To Use This Page#

Start from the feature that matches your task.
Open the linked guide for full examples and behavior notes.
Use the signature appendix only when you need exact parameter and return types.

Feature Entry Points#

Array helpers (list/map/nested array operations):: Array Helpers
Dot-notation read/write for nested data:: Dot Notation
Object-style data pipeline and fluent transformations:: Collections
Configuration storage with optional get/set hooks:: Configuration
Single facade entrypoint for modules and factories:: Facade
DTO and hook traits plus helper functions:: Traits and Helpers

Common Workflows#

Nested data access (read/write with fallback):

<?php
use function Infocyph\ArrayKit\array_get;
use function Infocyph\ArrayKit\array_set;

$user = ['profile' => ['name' => 'Alice']];
$name = array_get($user, 'profile.name', 'Guest');
array_set($user, 'profile.email', '[email protected]');

Collection transformation pipeline:

<?php
use function Infocyph\ArrayKit\collect;

$result = collect([1, 2, 3, 4])
    ->filter(fn ($v) => $v % 2 === 0)
    ->map(fn ($v) => $v * 10)
    ->all(); // [1 => 20, 3 => 40]

Behavior Highlights#

ArrayMulti::flatten($array, 0) keeps top-level values unchanged.
ArraySingle::avg(), sum(), isPositive(), and isNegative() ignore non-numeric values.
ArraySingle::paginate() throws when page < 1 or perPage < 1.
ArrayMulti::sortBy() / sum() / maxBy() / minBy() callbacks support ($row, $key).
Namespaced helper functions are autoloaded by default; global helpers are optional.

Runtime configuration with hooks:

<?php
$config = new \Infocyph\ArrayKit\Config\Config();
$config->onSet('app.name', fn ($v) => trim((string) $v));
$config->setWithHooks('app.name', '  ArrayKit  ');
echo $config->getWithHooks('app.name'); // ArrayKit

Static array utilities for data shaping:

<?php
use Infocyph\ArrayKit\Array\ArrayMulti;

$rows = [
    ['team' => 'A', 'score' => 10],
    ['team' => 'B', 'score' => 30],
];

$sorted = ArrayMulti::sortBy($rows, 'score', true);
$scores = ArrayMulti::pluck($rows, 'score');

Exact API Signatures#

This appendix maps the current public API surface in src/ one-to-one.

Helper Functions#

// Namespaced helpers (autoloaded by default)
function Infocyph\ArrayKit\compare(mixed $retrieved, mixed $value, ?string $operator = null): bool
function Infocyph\ArrayKit\array_get(array $array, int|string|array|null $key = null, mixed $default = null): mixed
function Infocyph\ArrayKit\array_set(array &$array, string|array|null $key, mixed $value = null, bool $overwrite = true): bool
function Infocyph\ArrayKit\collect(mixed $data = []): Collection
function Infocyph\ArrayKit\chain(mixed $data): Pipeline

// Optional globals (manual include of src/functions.php)
function compare(mixed $retrieved, mixed $value, ?string $operator = null): bool
function array_get(array $array, int|string|array|null $key = null, mixed $default = null): mixed
function array_set(array &$array, string|array|null $key, mixed $value = null, bool $overwrite = true): bool
function collect(mixed $data = []): Collection
function chain(mixed $data): Pipeline

ArrayKit Facade#

public static function single(): ModuleProxy
public static function multi(): ModuleProxy
public static function helper(): ModuleProxy
public static function dot(): ModuleProxy
public static function config(array $items = []): Config
public static function lazyConfig(string $directory, string $extension = 'php', array $items = []): LazyFileConfig
public static function collection(mixed $data = []): Collection
public static function hookedCollection(mixed $data = []): HookedCollection
public static function lazyCollection(mixed $data = []): LazyCollection
public static function pipeline(mixed $data): Pipeline

Facade ModuleProxy#

public function __call(string $method, array $arguments): mixed

BaseArrayHelper#

public static function isMultiDimensional(mixed $array): bool
public static function wrap(mixed $value): array
public static function unWrap(mixed $value): mixed
public static function haveAny(array $array, callable $callback): bool
public static function isAll(array $array, callable $callback): bool
public static function findKey(array $array, callable $callback): int|string|null
public static function accessible(mixed $value): bool
public static function has(array $array, int|string|array $keys): bool
public static function hasAny(array $array, int|string|array $keys): bool
public static function range(int $start, int $end, int $step = 1): array
public static function times(int $number, ?callable $callback = null): array
public static function any(array $array, callable $callback): bool
public static function all(array $array, callable $callback): bool
public static function tap(array $array, callable $callback): array
public static function forget(array &$array, int|string|array $keys): void
public static function random(array $array, ?int $number = null, bool $preserveKeys = false): mixed
public static function doReject(array $array, mixed $callback): array

ArraySharedOps (Internal)#

public static function each(array $array, callable $callback): array
public static function every(array $array, callable $callback): bool
public static function partition(array $array, callable $callback): array
public static function skip(array $array, int $count): array
public static function skipUntil(array $array, callable $callback): array
public static function skipWhile(array $array, callable $callback): array
public static function normalizeArrayKey(mixed $value): int|string
public static function asString(mixed $value): string

ArraySingle#

public static function exists(array $array, int|string $key): bool
public static function only(array $array, array|string $keys): array
public static function separate(array $array): array
public static function isList(array $array): bool
public static function isAssoc(array $array): bool
public static function prepend(array $array, mixed $value, mixed $key = null): array
public static function isPositive(array $array): bool
public static function isNegative(array $array): bool
public static function shuffle(array $array, ?int $seed = null): array
public static function isInt(array $array): bool
public static function nonEmpty(array $array): array
public static function avg(array $array): float|int
public static function isUnique(array $array): bool
public static function positive(array $array): array
public static function negative(array $array): array
public static function nth(array $array, int $step, int $offset = 0): array
public static function duplicates(array $array): array
public static function paginate(array $array, int $page, int $perPage): array
public static function combine(array $keys, array $values): array
public static function where(array $array, ?callable $callback = null): array
public static function search(array $array, mixed $needle): int|string|null
public static function chunk(array $array, int $size, bool $preserveKeys = false): array
public static function map(array $array, callable $callback): array
public static function mapWithKeys(array $array, callable $callback): array
public static function each(array $array, callable $callback): array
public static function reduce(array $array, callable $callback, mixed $initial = null): mixed
public static function some(array $array, callable $callback): bool
public static function every(array $array, callable $callback): bool
public static function contains(array $array, mixed $valueOrCallback, bool $strict = false): bool
public static function containsAll(array $array, array $needles, bool $strict = false): bool
public static function containsAny(array $array, array $needles, bool $strict = false): bool
public static function countBy(array $array, ?callable $by = null): array
public static function sum(array $array, ?callable $callback = null): float|int
public static function unique(array $array, bool $strict = false): array
public static function values(array $array): array
public static function reject(array $array, mixed $callback = true): array
public static function intersect(array $array, array $values, bool $strict = false): array
public static function diff(array $array, array $values, bool $strict = false): array
public static function symmetricDiff(array $left, array $right, bool $strict = false): array
public static function same(array $left, array $right, bool $strict = false): bool
public static function slice(array $array, int $offset, ?int $length = null): array
public static function skip(array $array, int $count): array
public static function skipWhile(array $array, callable $callback): array
public static function skipUntil(array $array, callable $callback): array
public static function partition(array $array, callable $callback): array
public static function mode(array $array): array
public static function median(array $array): float|int
public static function min(array $array): float|int|null
public static function max(array $array): float|int|null
public static function minBy(array $array, callable $callback): mixed
public static function maxBy(array $array, callable $callback): mixed
public static function except(array $array, array|string $keys): array
public static function rekey(array $array, array|callable $mapper): array

ArrayMulti#

public static function only(array $array, array|string $keys): array
public static function collapse(array $array): array
public static function depth(array $array): int
public static function depthGuarded(array $array, int $maxDepth = 256, int $maxNodes = 100000, bool $throwOnTooDeep = false): int
public static function flatten(array $array, float|int $depth = \INF): array
public static function flattenGuarded(array $array, float|int $depth = \INF, int $maxDepth = 256, int $maxNodes = 100000, bool $throwOnTooDeep = false): array
public static function flattenByKey(array $array): array
public static function values(array $array): array
public static function rekey(array $array, array|callable $mapper): array
public static function sortRecursive(array $array, int $options = \SORT_REGULAR, bool $descending = false): array
public static function first(array $array, ?callable $callback = null, mixed $default = null): mixed
public static function firstWhere(array $array, string $key, mixed $operator = null, mixed $value = null, mixed $default = null): mixed
public static function firstWhereIn(array $array, string $key, array $values, bool $strict = false, mixed $default = null): mixed
public static function last(array $array, ?callable $callback = null, mixed $default = null): mixed
public static function between(array $array, string $key, float|int $from, float|int $to): array
public static function whereBetween(array $array, string $key, float|int $from, float|int $to): array
public static function whereLike(array $array, string $key, string $pattern, bool $caseSensitive = false): array
public static function whereStartsWith(array $array, string $key, string $prefix, bool $caseSensitive = true): array
public static function whereEndsWith(array $array, string $key, string $suffix, bool $caseSensitive = true): array
public static function whereContains(array $array, string $key, string $needle, bool $caseSensitive = true): array
public static function whereCallback(array $array, ?callable $callback = null, mixed $default = null): mixed
public static function where(array $array, string $key, mixed $operator = null, mixed $value = null): array
public static function chunk(array $array, int $size, bool $preserveKeys = false): array
public static function map(array $array, callable $callback): array
public static function each(array $array, callable $callback): array
public static function reduce(array $array, callable $callback, mixed $initial = null): mixed
public static function some(array $array, callable $callback): bool
public static function every(array $array, callable $callback): bool
public static function contains(array $array, mixed $valueOrCallback, bool $strict = false): bool
public static function unique(array $array, bool $strict = false): array
public static function uniqueBy(array $array, string|callable $keyOrCallback, bool $strict = false): array
public static function duplicatesBy(array $array, string|callable $keyOrCallback, bool $strict = false): array
public static function reject(array $array, mixed $callback = true): array
public static function partition(array $array, callable $callback): array
public static function skip(array $array, int $count): array
public static function skipWhile(array $array, callable $callback): array
public static function skipUntil(array $array, callable $callback): array
public static function sum(array $array, string|callable|null $keyOrCallback = null): float|int
public static function min(array $array, string|callable $keyOrCallback): float|int|null
public static function max(array $array, string|callable $keyOrCallback): float|int|null
public static function minBy(array $array, string|callable $keyOrCallback): mixed
public static function maxBy(array $array, string|callable $keyOrCallback): mixed
public static function countBy(array $array, string|callable $groupBy): array
public static function whereIn(array $array, string $key, array $values, bool $strict = false): array
public static function whereNotIn(array $array, string $key, array $values, bool $strict = false): array
public static function whereNull(array $array, string $key): array
public static function whereNotNull(array $array, string $key): array
public static function groupBy(array $array, string|callable $groupBy, bool $preserveKeys = false): array
public static function keyBy(array $array, string|callable $keyBy): array
public static function indexBy(array $array, string|callable $indexBy): array
public static function mapWithKeys(array $array, callable $callback): array
public static function sortBy(array $array, string|callable $by, bool $desc = false, int $options = \SORT_REGULAR): array
public static function sortByDesc(array $array, string|callable $by, int $options = \SORT_REGULAR): array
public static function sortByMany(array $array, array $criteria): array
public static function sortRecursiveGuarded(array $array, int $options = \SORT_REGULAR, bool $descending = false, int $maxDepth = 256, int $maxNodes = 100000, bool $throwOnTooDeep = false): array
public static function transpose(array $matrix): array
public static function pluck(array $array, string $column, ?string $indexBy = null): array
public static function mergeRecursiveDistinct(array $base, array $overrides): array
public static function replaceRecursive(array $base, array $replacements): array
public static function overlay(array $base, array $overlay): array

ArrayShape#

public static function require(array $row, array $shape): array

DotNotation#

public static function flatten(array $array, string $prepend = ''): array
public static function expand(array $array): array
public static function has(array $array, array|string $keys): bool
public static function hasAny(array $array, array|string $keys): bool
public static function hasWildcard(string $path): bool
public static function paths(array $array): array
public static function matches(array $array, string $path): bool
public static function get(array $array, array|int|string|null $keys = null, mixed $default = null): mixed
public static function getSafe(array $array, array|int|string|null $keys = null, mixed $default = null, int $maxDepth = 256, int $maxNodes = 100000, bool $throwOnTooDeep = false): mixed
public static function set(array &$array, array|string|null $keys = null, mixed $value = null, bool $overwrite = true): bool
public static function fill(array &$array, array|string $keys, mixed $value = null): void
public static function forget(array &$target, array|string|int|null $keys): void
public static function rename(array &$array, string $from, string $to, bool $overwrite = true): bool
public static function move(array &$array, string $from, string $to, bool $overwrite = true): bool
public static function string(array $array, string $key, mixed $default = null): string
public static function integer(array $array, string $key, mixed $default = null): int
public static function float(array $array, string $key, mixed $default = null): float
public static function boolean(array $array, string $key, mixed $default = null): bool
public static function arrayValue(array $array, string $key, mixed $default = null): array
public static function pluck(array $array, array|string $keys, mixed $default = null): array
public static function all(array $array): array
public static function tap(array $array, callable $callback): array
public static function offsetExists(array $array, string $key): bool
public static function offsetGet(array $array, string $key): mixed
public static function offsetSet(array &$array, string $key, mixed $value): void
public static function offsetUnset(array &$array, string $key): void

Collection#

Collection uses BaseCollectionTrait. Public API:

public function __construct(array $data = [])
public static function from(mixed $data): static
public static function make(mixed $data): static
public function __call(string $method, array $arguments): mixed
public function __invoke(): array
public function process(): Pipeline
public function immutableProcess(): Pipeline
public function pipeImmutable(): Pipeline
public function get(string|array $keys): mixed
public function has(string|array $keys): bool
public function hasAny(string|array $keys): bool
public function set(array|string|null $keys = null, mixed $value = null): bool
public function __get(string $key): mixed
public function __set(string $key, mixed $value): void
public function __isset(string $key): bool
public function __unset(string $key): void
public function getArrayableItems(mixed $items): array
public function all(): array
public function items(): array
public function toJson(int $options = 0): string
public function isEmpty(): bool
public function __toString(): string
public function toArray(): array
public function keys(): array
public function __debugInfo(): array
public function clear(): void
public function copy(): static
public function immutable(): static
public function merge(mixed $items): static
public function offsetExists(mixed $offset): bool
public function offsetGet(mixed $offset): mixed
public function offsetSet(mixed $offset, mixed $value): void
public function offsetUnset(mixed $offset): void
public function getIterator(): Traversable
public function current(): mixed
public function key(): string|int|null
public function next(): void
public function valid(): bool
public function rewind(): void
public function count(): int
public function jsonSerialize(): array

HookedCollection#

HookedCollection extends Collection and adds hook behavior (from HookTrait):

public function offsetGet(mixed $offset): mixed
public function offsetSet(mixed $offset, mixed $value): void
public function onGet(string $offset, callable $callback): static
public function onSet(string $offset, callable $callback): static

Pipeline#

public function __construct(protected array &$working, private readonly Collection $collection)
public function only(array|string $keys): Collection
public function values(): Collection
public function rekey(array|callable $mapper): Collection
public function nth(int $step, int $offset = 0): Collection
public function duplicates(): Collection
public function slice(int $offset, ?int $length = null): Collection
public function paginate(int $page, int $perPage): Collection
public function combine(array $values): Collection
public function map(callable $callback): Collection
public function mapWithKeys(callable $callback): Collection
public function filter(callable $callback): Collection
public function chunk(int $size, bool $preserveKeys = false): Collection
public function unique(bool $strict = false): Collection
public function reject(mixed $callback = true): Collection
public function intersect(array $values, bool $strict = false): Collection
public function diff(array $values, bool $strict = false): Collection
public function symmetricDiff(array $values, bool $strict = false): Collection
public function same(array $values, bool $strict = false): bool
public function skip(int $count): Collection
public function skipWhile(callable $callback): Collection
public function skipUntil(callable $callback): Collection
public function partition(callable $callback): Collection
public function flatten(float|int $depth = \INF): Collection
public function flattenByKey(): Collection
public function sortRecursive(int $options = SORT_REGULAR, bool $descending = false): Collection
public function collapse(): Collection
public function groupBy(string|callable $groupBy, bool $preserveKeys = false): Collection
public function keyBy(string|callable $keyBy): Collection
public function indexBy(string|callable $indexBy): Collection
public function between(string $key, float|int $from, float|int $to): Collection
public function whereBetween(string $key, float|int $from, float|int $to): Collection
public function whereLike(string $key, string $pattern, bool $caseSensitive = false): Collection
public function whereStartsWith(string $key, string $prefix, bool $caseSensitive = true): Collection
public function whereEndsWith(string $key, string $suffix, bool $caseSensitive = true): Collection
public function whereContains(string $key, string $needle, bool $caseSensitive = true): Collection
public function firstWhere(string $key, mixed $operator = null, mixed $value = null, mixed $default = null): mixed
public function firstWhereIn(string $key, array $values, bool $strict = false, mixed $default = null): mixed
public function whereCallback(?callable $callback = null, mixed $default = null): Collection
public function where(string $key, mixed $operator = null, mixed $value = null): Collection
public function whereIn(string $key, array $values, bool $strict = false): Collection
public function whereNotIn(string $key, array $values, bool $strict = false): Collection
public function whereNull(string $key): Collection
public function whereNotNull(string $key): Collection
public function sortBy(string|callable $by, bool $desc = false, int $options = SORT_REGULAR): Collection
public function sortByMany(array $criteria): Collection
public function isMultiDimensional(): bool
public function wrap(): Collection
public function unWrap(): Collection
public function shuffle(?int $seed = null): Collection
public function sum(?callable $callback = null): float|int
public function min(string|callable|null $keyOrCallback = null): float|int|null
public function max(string|callable|null $keyOrCallback = null): float|int|null
public function first(?callable $callback = null, mixed $default = null): mixed
public function last(?callable $callback = null, mixed $default = null): mixed
public function reduce(callable $callback, mixed $initial = null): mixed
public function any(callable $callback): bool
public function countBy(callable|string|null $groupBy = null): array
public function except(array|string $keys): Collection
public function median(): float|int
public function mode(): array
public function minBy(string|callable $keyOrCallback): mixed
public function maxBy(string|callable $keyOrCallback): mixed
public function pluck(string $column, ?string $indexBy = null): Collection
public function transpose(): Collection
public function uniqueBy(string|callable $keyOrCallback, bool $strict = false): Collection
public function duplicatesBy(string|callable $keyOrCallback, bool $strict = false): Collection
public function mergeRecursiveDistinct(array $overlay): Collection
public function replaceRecursive(array $replacements): Collection
public function overlay(array $overlay): Collection
public function tap(callable $callback): Collection
public function pipe(callable $callback): Collection
public function when(bool $condition, callable $callback, ?callable $default = null): Collection
public function unless(bool $condition, callable $callback, ?callable $default = null): Collection

Config#

Config uses BaseConfigTrait. Public API:

public function loadFile(string $path): bool
public function loadArray(array $resource): bool
public function all(): array
public function has(string|array $keys): bool
public function hasAny(string|array $keys): bool
public function get(string|int|array|null $key = null, mixed $default = null): mixed
public function getOrFail(string|int|array|null $key): mixed
public function getString(string|int|array|null $key, ?string $default = null): ?string
public function getInt(string|int|array|null $key, ?int $default = null): ?int
public function getFloat(string|int|array|null $key, ?float $default = null): ?float
public function getBool(string|int|array|null $key, ?bool $default = null): ?bool
public function getArray(string|int|array|null $key, ?array $default = null): ?array
public function getList(string|int|array|null $key, ?array $default = null): ?array
public function getEnum(string|int|array|null $key, string $enumClass, ?\UnitEnum $default = null): ?\UnitEnum
public function set(string|array|null $key = null, mixed $value = null, bool $overwrite = true): bool
public function fill(string|array $key, mixed $value = null): bool
public function forget(string|int|array $key): bool
public function prepend(string $key, mixed $value): bool
public function append(string $key, mixed $value): bool
public function replace(array $items): bool
public function reload(array|string $source): bool
public function merge(array $items): bool
public function overlay(array $overlay): bool
public function snapshot(string $name = 'default'): bool
public function restore(string $name = 'default'): bool
public function changed(string $snapshot = 'default'): bool
public function readonly(bool $enabled = true): static
public function isReadonly(): bool

LazyFileConfig#

LazyFileConfig loads top-level config files on first keyed access:

public function get(string|int|array|null $key = null, mixed $default = null): mixed
public function has(string|array $keys): bool
public function hasAny(string|array $keys): bool
public function set(string|array|null $key = null, mixed $value = null, bool $overwrite = true): bool
public function fill(string|array $key, mixed $value = null): bool
public function forget(string|int|array $key): bool
public function preload(string|array $namespaces): static
public function isLoaded(string $namespace): bool
public function loaded(string $namespace): bool
public function loadedNamespaces(): array
public function all(): array // throws (design choice)

Config Hook-Aware Variants#

Both Config and LazyFileConfig expose explicit hook-aware methods:

public function getWithHooks(int|string|array|null $key = null, mixed $default = null): mixed
public function setWithHooks(string|array|null $key = null, mixed $value = null, bool $overwrite = true): bool
public function fillWithHooks(string|array $key, mixed $value = null): bool
public function onGet(string $offset, callable $callback): static
public function onSet(string $offset, callable $callback): static

DTOTrait#

public static function create(array $values): static
public function fromArray(array $values): static
public function hydrate(array $values, array $mapping = [], bool $coerce = false): static
public function hydrateNested(array $values, array $mapping = [], bool $coerce = false): static
public function toArray(): array
public function toArrayDeep(): array
public function replaceFromArray(array $values, array $mapping = [], bool $coerce = false): static

HookTrait#

public function onGet(string $offset, callable $callback): static
public function onSet(string $offset, callable $callback): static

LazyCollection#

public static function from(iterable $source): self
public static function make(mixed $data = []): self
public function getIterator(): Traversable
public function cursor(): Generator
public function mapLazy(callable $callback): self
public function filterLazy(callable $callback): self
public function chunkLazy(int $size, bool $preserveKeys = false): self
public function take(int $limit): self
public function takeUntil(callable $callback): self
public function all(): array

Laravel Compatibility#

// Infocyph\ArrayKit\LaravelCompat\Arr
public static function get(iterable $array, string|int|array|null $key = null, mixed $default = null): mixed
public static function set(array &$array, string|array|null $key, mixed $value = null, bool $overwrite = true): bool
public static function has(iterable $array, int|string|array $keys): bool
public static function hasAny(iterable $array, int|string|array $keys): bool
public static function only(iterable $array, array|string $keys): array
public static function except(iterable $array, array|string $keys): array

// Infocyph\ArrayKit\LaravelCompat\Collection extends Collection