Open Source реализация иммутабельных коллекций с ковариантными темплейт-параметрами и выстроенной иерархией пустых и непустых коллекций.
4К открытий4К показов
Столкнулся с проблемой нормальной реализации коллекций в PHP. Доктриновские коллекции мутабельны и инвариантны. PSL коллекции инвариантны. Нигде не видел непустых коллекций.
Везде меня что-то не устраивало. Было принято решение написать свою Open Source реализацию иммутабельных коллекций с ковариантными темплейт-параметрами и выстроенной иерархией пустых и непустых коллекций.
В качестве статического анализатора был выбран Psalm. С помощью него можно контролировать изменение типов элементов коллекции при выполнении таких операций, как map, filter, reduce и т.п.
Коллекции делятся по возможности содержать пустой список элементов на Collection и NonEmptyCollection. Получается две иерархии коллекций: обычные коллекции и непустые коллекции.
Обычные коллекции (интерфейс Collection) делятся на интерфейсы Seq, Map и Set.
Seq — это сокращение от Sequence. Упорядоченный набор элементов с порядковым номером в рамках коллекции. Типичный представитель Seq — это связный список LinkedList.
Map представляет набор пар ключ-значение. Типичный представитель HashMap.
Set — это множество уникальных элементов. Типичный представитель HashSet.
Непустые коллекции (интерфейс NonEmptyCollection) делятся на интерфейсы по такому же принципу, как и обычные коллекции, но у них добавляется префикс NonEmpty к соответствующим названиям классов и интерфейсов.
В библиотеке написаны плагины для статического анализатора Psalm, которые позволяют производить рефайнинг типов элементов и ключей коллекций при выполнении таких операций, как filter и filterNotNull.
/**
* Выведенный тип NonEmptyLinkedList<1|2|3>
*/
$collection = NonEmptyLinkedList::collectNonEmpty([1, 2, 3]);
/**
* Выведенный тип NonEmptyLinkedList<int>
*
* Литеральные типы пропали после трансформации элементов коллекции
* Но NonEmpty префикс коллекции сохранился,
* Т.к. количество элементов в коллекции не изменилось
*/
$mappedCollection = $collection->map(fn($elem) => $elem - 1);
/**
* Выведенный тип LinkedList<positive-int>
*
* NonEmpty префикс пропал после фильтрации
* Т.к. количество элементов могло уменьшиться
* И коллекция могла стать пустой
*/
$filteredCollection = $mappedCollection->filter(fn(int $elem) => $elem > 0);
/**
* Выведенный тип non-empty-list<Foo|null|Bar>
*/
$source = [new Foo(1), null, new Bar(2)];
/**
* Выведенный тип ArrayList<Foo|Bar>
*
* Null был исключен из типа элементов коллекции
*
* NonEmpty префикс коллекции так же пропал после фильтрации
* Т.к. количество элементов могло уменьшиться
* И коллекция могла стать пустой
*/
$withoutNulls = NonEmptyArrayList::collectNonEmpty($source)->filterNotNull();
/**
* Выведенный тип ArrayList<Foo>
*
* Bar был исключен из типа элементов коллекции
*/
$onlyFoos = $withoutNulls->filter(fn($elem) => $elem instanceof Foo);
Ковариантность
Тайп-параметры коллекций ковариантны, в отличие от коллекций доктрины и PHP Standart Library (PSL).
class User {}
class Admin extends User {}
/**
* @param NonEmptyCollection<User> $collection
*/
function acceptUsers(NonEmptyCollection $collection): void {}
/**
* @var NonEmptyLinkedList<Admin> $collection
*/
$collection = NonEmptyLinkedList::collectNonEmpty([new Admin()]);
/**
* Можно передавать коллекцию админов вместо коллекции пользователей
* Из-за ковариантности тайп-параметра коллекции
*/
acceptUsers($collection);
Иммутабельность
Коллекции не изменяются после создания. Все мутирующие операции над коллекциями возвращают новые независимые коллекции.
$originalCollection = LinkedList::collect([1, 2, 3]);
/**
* $originalCollection не модифицируется
* И создаётся новая коллекция на основе предыдущей
*/
$prependedCollection = $originalCollection->prepended(0);
/**
* $prependedCollection не модифицируется
* И создаётся новая коллекция на основе предыдущей
*/
$mappedCollection = $prependedCollection->map(fn(int $elem) => $elem + 1);
Null-безопасность
Использование монады Option позволяет избежать null pointer исключений. В либе вместо null возвращается всегда либо Some, либо None .
/**
* @var Collection<int> $emptyCollection
*/
$emptyCollection = getEmptyCollection();
/**
* Операция reduce предполагает работу с непустой коллекцией
*
* Вместо того, чтобы кидать исключение или возвращать null,
* если в коллекции нет элементов,
* в библиотеке в таких случаях возвращается
* экземпляр монады Option<T> (Some<T>|None)
*
* Такой подход позволяет получить значение
* или продолжить вычисление без проверок на null
*/
$resultWithDefaultValue = $emptyCollection
->reduce(fn(int $accumulator, int $element) => $accumulator + $element)
->getOrElse(0);
class Order
{
public function __construct(public int $id, public int $price) {}
}
/**
* In-memory хранилище проиндексированных по ID заказов
*/
$ordersInMemoryStorage = HashMap::collect([
[$orderId1 = rand(), new Order(id: $orderId1, price: 0)],
[$orderId2 = rand(), new Order(id: $orderId2, price: 999)],
]);
/**
* Безопасное деление
*
* Эту операцию можно вставить в качестве промежуточного элемента
* цепочки вычислений с помощью метода Option::flatMap
*
* @return Option<float>
*/
function div(int $dividend, int $divisor): Option {
return 0 === $divisor
? Option::none()
: Option::some($dividend / $divisor);
}
/**
* Поиск по ключу в Map-коллекции возвращает монаду Option
*
* Это позволяет продолжить описывать цепочку вычислений
* с помощью map, flatMap и подобных методов класса Option.
*
* Цепочка вычислений не продолжится,
* если элемент не найден в хранилище
* или если произошло деление на ноль
*
* В случае, если на каком-то этапе вычисления произошла ошибка,
* то при вызове getOrElse(0) возвратится 0,
* вместо успешного результата вычисления
*/
$ordersInMemoryStorage
->get($orderId1)
->map(fn(Order $order): int => $order->price)
->flatMap(fn(int $price): Option => div(1, $price))
->getOrElse(0);
Связь HashSet, HashMap и HashContract
HashSet под капотом использует HashMap.
Чем отличается HashMap от обычного массива в PHP? Ключи массивов в PHP могут быть целыми числами или строками. Тип ключей в HashMap ничем не ограничен. Это вполне могут быть экземпляры классов. Numeric-string ключи в массивах PHP преобразуются в целочисленные ключи. В HashMap такого не происходит и элемент с ключем "1" нельзя достать по ключу 1.
HashMap проверяет, не реализует ли объект, который используется в качестве ключа, интерфейс HashContract. Если реализует, то используются реализуемые в классе ключа-объекта методы hashCode и equals, чтобы находить элементы коллекции по ключам.
/**
* Если реализовать HashContract (методы hashCode и equals),
* то можно использовать объекты класса
* в качестве ключей в HashMap
* и в качестве элементов коллекции HashSet
*/
class Foo implements HashContract
{
public function __construct(public int $a, public bool $b = true)
{
}
/**
* Сравнивает на равенство текущий объект
* с переданным аргументом
* по типу и значимым полям класса
*
* Используется, чтобы находить элементы в бакете
* по ключу-объекту данного класса
*/
public function equals(mixed $rhs): bool
{
return $rhs instanceof self
&& $this->a === $rhs->a
&& $this->b === $rhs->b;
}
/**
* Хэш значимых полей класса
*
* Используется, чтобы попадать в нужный бакет
* в HashMap'е
*/
public function hashCode(): string
{
return md5(implode(',', [$this->a, $this->b]));
}
}
/**
* Сборка коллекции происходит с помощью пар ключ-значение,
* которые передаются в виде массивов вида array{TKey, TValue}
*/
$hashMap = HashMap::collect([
[new Foo(1), 1], [new Foo(2), 2],
[new Foo(3), 3], [new Foo(4), 4]
]);
/**
* Пример использования коллекции HashMap
* и чейнинга операций над коллекцией
*/
$hashMap
->map(fn($elem) => $elem + 1)
->filter(fn($elem) => $elem > 2)
->reindex(fn($elem, Foo $key) => $key->a)
->fold(0, fn(int $acc, array $pair) => $acc + $pair[1]); // 3+4+5=12
/**
* При сборке коллекции
* дублирующиейся элементы будут удалены
*
* Останутся только Foo(1), Foo(2), Foo(3), Foo(4)
*/
$hashSet = HashSet::collect([
new Foo(1), new Foo(2), new Foo(2),
new Foo(3), new Foo(3), new Foo(4),
]);
/**
* Пример использования коллекции HashSet
* и чейнинга операций над коллекцией
*/
$hashSet
->map(fn(Foo $elem) => $elem->a)
->filter(fn(int $elem) => $elem > 1)
->reduce(fn($acc, $elem) => $acc + $elem)
->getOrElse(0); // 9
