README

Tiny PHP functions for indexing and grouping arrays and iterables by custom keys.

The package is intentionally small:

no framework dependency;
no service container;
no classes required;
works with arrays, objects, Doctrine entities, DTOs, generators and any iterable.

Useful when you receive a list of objects from a database and want fast access by id, uuid, slug, email, externalId, or any other calculated key.

Installation

After the package is published on Packagist:

composer require qaadee/php-array-indexer

Before publishing on Packagist, you can install it directly from GitHub:

composer config repositories.php-array-indexer vcs https://github.com/QaaDee/php-array-indexer
composer require qaadee/php-array-indexer:dev-main

Requirements

PHP 8.1+

Functions

QaaDee\PhpArrayIndexer\index_by()
QaaDee\PhpArrayIndexer\index_by_unique()
QaaDee\PhpArrayIndexer\group_by()

Basic usage

<?php

use function QaaDee\PhpArrayIndexer\index_by;

$usersById = index_by(
    $users,
    static fn (User $user): int => $user->getId()
);

$user = $usersById[123] ?? null;

Index array items

use function QaaDee\PhpArrayIndexer\index_by;

$items = [
    ['id' => 10, 'name' => 'Alice'],
    ['id' => 20, 'name' => 'Bob'],
];

$itemsById = index_by(
    $items,
    static fn (array $item): int => $item['id']
);

echo $itemsById[10]['name']; // Alice

Index objects

use function QaaDee\PhpArrayIndexer\index_by;

/** @var User[] $users */
$users = $userRepository->findAll();

$usersByEmail = index_by(
    $users,
    static fn (User $user): string => $user->getEmail()
);

$user = $usersByEmail['user@example.com'] ?? null;

Example with Doctrine repository

use function QaaDee\PhpArrayIndexer\index_by;

/** @var User[] $users */
$users = $userRepository->findBy(['active' => true]);

$usersById = index_by(
    $users,
    static fn (User $user): int => $user->getId()
);

Duplicate keys

index_by() uses the last item when several items produce the same key:

$result[$key] = $item;

Example:

$usersById = index_by(
    $users,
    static fn (User $user): int => $user->getId()
);

If two users have the same id, the last one will overwrite the previous one.

Unique index

Use index_by_unique() when duplicate keys are not allowed:

use function QaaDee\PhpArrayIndexer\index_by_unique;

$usersById = index_by_unique(
    $users,
    static fn (User $user): int => $user->getId()
);

If a duplicate key is found, InvalidArgumentException is thrown.

Group items

Use group_by() when many items can have the same key:

use function QaaDee\PhpArrayIndexer\group_by;

$ordersByUserId = group_by(
    $orders,
    static fn (Order $order): int => $order->getUser()->getId()
);

$userOrders = $ordersByUserId[123] ?? [];

Result structure:

[
    123 => [$order1, $order2],
    456 => [$order3],
]

Working with generators

use function QaaDee\PhpArrayIndexer\index_by;

$users = (static function (): iterable {
    yield new User(10, 'Alice');
    yield new User(20, 'Bob');
})();

$usersById = index_by(
    $users,
    static fn (User $user): int => $user->getId()
);

Function signatures

/**
 * @template T
 *
 * @param iterable<T> $items
 * @param callable(T): array-key $keySelector
 *
 * @return array<array-key, T>
 */
function index_by(iterable $items, callable $keySelector): array;

/**
 * @template T
 *
 * @param iterable<T> $items
 * @param callable(T): array-key $keySelector
 *
 * @return array<array-key, T>
 *
 * @throws InvalidArgumentException
 */
function index_by_unique(iterable $items, callable $keySelector): array;

/**
 * @template T
 *
 * @param iterable<T> $items
 * @param callable(T): array-key $keySelector
 *
 * @return array<array-key, list<T>>
 */
function group_by(iterable $items, callable $keySelector): array;

Development

Install dependencies:

composer install

Run tests:

composer test

Run static analysis:

composer analyse

Run all checks:

composer check

Regenerate Composer autoload files:

composer dump-autoload

GitHub first push

git init
git add .
git commit -m "Initial package structure"
git branch -M main
git remote add origin https://github.com/QaaDee/php-array-indexer.git
git push -u origin main

License

MIT. See LICENSE.

qaadee / php-array-indexer

Maintainers

Package info

Statistics

Security