alison4kk/items

Items - Hybrid array manipulation utility for PHP 7.4+ and PHP 8

Maintainers

Package info

github.com/Alison4kk/Items

pkg:composer/alison4kk/items

Statistics

Installs: 5

Dependents: 0

Suggesters: 0

Stars: 3

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

1.2.0 2026-03-28 17:45 UTC

Requires

  • php: ^7.4 || ^8.0

Requires (Dev)

MIT cf574115df564f4e06a709ad71b67739322c2c10

This package is auto-updated.

Last update: 2026-04-28 18:01:01 UTC

README

Hybrid array/object manipulation library for PHP 7.4+ and PHP 8 with:

  • Static immutable operations
  • Static in-place operations
  • Fluent instance operations
  • Dot notation for nested arrays/objects (user.address.city)

Installation

composer require alison4kk/items

For local development:

composer install

Quick start

<?php

require __DIR__ . '/vendor/autoload.php';

use Items\Items;
use Items\ItemBag;

$users = [
    ['id' => 1, 'name' => 'Alice', 'city' => 'São Paulo', 'age' => 28, 'active' => true],
    ['id' => 2, 'name' => 'Bob', 'city' => 'Rio', 'age' => 35, 'active' => false],
    ['id' => 3, 'name' => 'Charlie', 'city' => 'São Paulo', 'age' => 42, 'active' => true],
];

// Static API - immutable
$active = Items::filtered($users, ['active' => true]);

// Static API - in-place
Items::filter($users, ['city' => 'São Paulo']);

// Fluent API - in-place chaining
$result = (new ItemBag($users))
    ->filter(['active' => true])
    ->sort('age', 'asc')
    ->map(fn($u) => ['name' => $u['name'], 'age' => $u['age']])
    ->all();

API Reference

Filter (search, find matching items)

Static immutable:

Items::filtered(array $items, ...$conditions): array

Static in-place:

Items::filter(array &$items, ...$conditions): void

Fluent in-place:

$collection->filter(...$conditions): ItemBag

Returns array or instance with only items matching all conditions.

Sort (order items)

Static immutable:

Items::sorted(array $items, string $field, string $direction = 'ASC'): array
Items::sorted(array $items, callable $comparator): array

Static in-place:

Items::sort(array &$items, string $field, string $direction = 'ASC'): void
Items::sort(array &$items, callable $comparator): void

Fluent in-place:

$collection->sort(string $field, string $direction = 'ASC'): ItemBag
$collection->sort(callable $comparator): ItemBag

Supports 'ASC' and 'DESC' directions. Works with dot notation paths.

Map (transform items)

Static immutable:

Items::mapped(array $items, callable $mapper): array

Static in-place:

Items::map(array &$items, callable $mapper): void

Fluent in-place:

$collection->map(callable $mapper): ItemBag

Mapper receives ($item, $key) and returns transformed value.

Unique (remove duplicates)

Static immutable:

Items::uniqued(array $items, string|callable $key): array

Static in-place:

Items::unique(array &$items, string|callable $key): void

Fluent in-place:

$collection->unique(string|callable $key): ItemBag

Removes duplicate items based on field or callable key.

Index (create indexed map)

Static immutable:

Items::indexed(array $items, string|callable $key): array

Static in-place:

Items::index(array &$items, string|callable $key): void

Fluent in-place:

$collection->index(string|callable $key): ItemBag

Changes array keys to values from a field or callable.

Group (organize by field)

Static immutable:

Items::grouped(array $items, string|callable $key, ?string $subKey = null): array

Static in-place:

Items::group(array &$items, string|callable $key, ?string $subKey = null): void

Fluent in-place:

$collection->group(string|callable $key, ?string $subKey = null): ItemBag

Reorganizes array into groups keyed by field values.

Column (extract column)

Static:

Items::column(array $items, string|callable $key): array

Fluent:

$collection->column(string|callable $key): array

Extract values from a field or callable into a new array.

Find (get first/last matching)

Items::first(array $items, $condition = null): mixed
Items::last(array $items, $condition = null): mixed
$collection->first($condition = null): mixed
$collection->last($condition = null): mixed

Returns first/last item optionally matching condition.

Check (test conditions)

Items::every(array $items, callable|array $condition): bool
Items::some(array $items, callable|array $condition): bool
Items::contains(array $items, array $search): bool
$collection->every(callable|array $condition): bool
$collection->some(callable|array $condition): bool
$collection->contains(array $search): bool

Test if all/any items match, or if any item contains all search fields.

Count & Sum

Items::count(array $items, $condition = null): int
Items::sum(array $items, string $field): float|int
Items::average(array $items, string $field): float|int
Items::max(array $items, string $field): float|int
Items::min(array $items, string $field): float|int
$collection->count($condition = null): int
$collection->sum(string $field): float|int
$collection->average(string $field): float|int
$collection->max(string $field): float|int
$collection->min(string $field): float|int

Aggregate operations. Count optionally filters by condition.

Group Aggregates

Items::countBy(array $items, string $field): array
Items::sumBy(array $items, string $groupField, string $sumField): array
$collection->countBy(string $field): array
$collection->sumBy(string $groupField, string $sumField): array

Count/sum items grouped by field.

Transform Keys/Values

Items::keyValue(array $items, string $keyField, string $valueField): array
Items::mapKeys(array $items, callable $mapper): array
$collection->keyValue(string $keyField, string $valueField): array
$collection->mapKeys(callable $mapper): array

Create key-value maps or transform keys using callable.

Dot Notation (nested access)

Static:

Items::getPath($item, string $path, $default = null): mixed
Items::setPath(&$item, string $path, $value): void

Fluent:

$collection->get(string $path, $default = null): mixed
$collection->set(string $path, $value): ItemBag
$collection->with(string $path, $value): ItemBag

Access nested arrays and objects using dot notation:

Items::getPath($user, 'profile.address.city');
$collection->set('0.user.settings.theme', 'dark');

Conditions Format

Pass conditions as associative arrays (all must match):

['field' => 'value']                           // equality
['active' => true, 'city' => 'São Paulo']     // AND logic

Or as indexed arrays with operators:

['field', 'value']                             // equality
['field', '>=', 10]                            // comparison
['field', 'IN', ['A', 'B']]                    // membership
['field', 'CONTAINS', 'substring']             // contains
fn (array $item): bool => $item['id'] > 10    // callable

Data Types

Works with arrays and objects (using stdClass or custom classes). All methods support:

  • Nested arrays and objects
  • Mixed structures
  • Dot notation paths like user.profile.address.zip

Testing

composer test

All 46 tests validate filter, sort, map, unique, group, index, find, count, sum, average, min, max, grouping aggregates, key-value operations, and dot notation functionality.

PHP Version

Requires PHP 7.4+ with full PHP 8.x support.

License

MIT

This package is compatible with PHP 7.4+ and PHP 8.x, and uses PHPDoc generics (@template) instead of union/mixed type declarations.