README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Collection

Иммутабельная флюентная коллекция для PHP 8.1+: 112 методов в стиле Laravel Collection (map, filter, reduce, pluck, groupBy, flatten и др.), строгая типизация и иммутабельность по умолчанию. Нулевые внешние зависимости.

Установка

composer require cloud-castle/collection

Требуется PHP 8.1+.

Быстрый старт

<?php

use CloudCastle\Collection\Collection;

$result = (new Collection([1, 2, 3, 4, 5, 6]))
    ->map(fn (int $x): int => $x * 2)      // [2,4,6,8,10,12]
    ->filter(fn (int $x): bool => $x % 3 === 0)  // [6,12]
    ->values()
    ->all();

// Исходная коллекция не мутирует — каждый шаг возвращает новый экземпляр.
$users = new Collection([
    ['name' => 'Ann', 'role' => 'admin'],
    ['name' => 'Bob', 'role' => 'user'],
]);
$byRole = $users->groupBy('role');
$names = $users->pluck('name')->all();     // ['Ann', 'Bob']
$admin = $users->firstWhere('role', 'admin');

Возможности

112 методов в стиле Laravel Collection: map, filter, reduce, pluck, groupBy, flatten, collapse, sort*, chunk, zip и др.
Иммутабельность по умолчанию: преобразования возвращают новый экземпляр, исходная коллекция неизменна — безопасно для разделяемого состояния.
Строгая типизация: firstOrFail / sole бросают исключение вместо тихого null; предсказуемые типы возврата (static).
Нулевые внешние зависимости — в отличие от illuminate/collections, тянущего контракты и macroable фреймворка.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	illuminate	doctrine	ramsey	loophp	array_*¹
Флюентный конвейер map/filter/reduce	✅	✅	✅	✅	✅	❌
Богатый набор (pluck/groupBy/flatten, 100+ методов)	✅	✅	❌	❌	✅	❌
Иммутабельность по умолчанию	✅	✅	❌	❌	✅	✅
Строгий отказ (firstOrFail/sole)	✅	✅	❌	❌	❌	❌
Нулевые внешние зависимости	✅	❌	✅	✅	❌	✅
Всего	🏆 5	4	2	2	3	2

2. Безопасность и корректность

Свойство	🏆 CloudCastle	illuminate	doctrine	ramsey	loophp	array_*¹
Иммутабельность (map не мутирует источник)	✅	✅	❌	❌	✅	✅
Строгий отказ вместо тихого null	✅	✅	❌	❌	❌	❌
Без зависимости от фреймворка	✅	❌	✅	✅	✅	✅
Предсказуемый тип возврата (static)	✅	✅	✅	✅	✅	❌
Всего	🏆 4	3	2	2	3	2

3. Производительность

Конвейер map→filter→values над 100 элементами, 100 000 раз (минимум из 4).

Решение	Время (мс)	Итог
array_*¹	997,2	базовый уровень (не библиотека)
🏆 CloudCastle	1 105,2	быстрейшее среди библиотек
doctrine	1 169,9	аналог
illuminate	1 427,8	аналог
ramsey	4 710	аналог
loophp	7 782,2	аналог

4. Потребление памяти

Пик памяти на 100 000 конвейеров (изолированный процесс).

Решение	Пиковая память (KB)	Итог
🏆 doctrine	6 991	быстрейшее среди библиотек
ramsey	6 991	аналог
array_*¹	6 991	базовый уровень (не библиотека)
CloudCastle	7 003	аналог
loophp	7 046	аналог
illuminate	7 192	аналог

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/collection
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия