Feature Access

🔎 Доступ и проверки

← Возможности · Главная · Сравнение

Чтение элементов и проверки состава коллекции: first/last/get с default-значениями и предикатами, контрактные firstOrFail/sole, строгие contains/search, has/hasAny/every/some.

Принцип работы

Методы доступа не выбрасывают ошибок на промахе — возвращают null или переданный default. Когда отсутствие элемента — ошибка бизнес-логики, используются контрактные firstOrFail/sole: они бросают ItemNotFoundException/MultipleItemsFoundException с различением «коллекция пуста» и «нет совпадения». Все сравнения — строгие (===).

use CloudCastle\Collection\Collection;

$c = Collection::make(['a' => 1, 'b' => 2, 'c' => 3]);

$c->get('a');                 // 1
$c->get('zz', 'default');     // 'default'
$c->first();                  // 1
$c->last(fn ($v) => $v < 3);  // 2

// Контрактные исключения
$c->firstOrFail(fn ($v) => $v > 99); // ItemNotFoundException («нет элемента»)
Collection::make([5])->sole();       // 5
Collection::make([1, 1])->sole();    // MultipleItemsFoundException

// Строгие проверки
$c->contains(2);      // true
$c->contains('2');    // false — строка не равна int
$c->search(3);        // 'c'
$c->has('a', 'b');    // true (все ключи)
$c->hasAny('zz', 'a');// true (хотя бы один)
$c->every(fn ($v) => $v > 0); // true

Плюсы

• Строгий contains исключает ловушки 0 == 'admin' и '0e123' == '0e456'.
• firstOrFail/sole делают «ровно один результат» проверяемым контрактом.
• Предикаты доступны везде: first/last/search/contains принимают замыкание.
• Различение empty()/noMatch() в исключениях упрощает диагностику.

Минусы

• Мигрирующим с illuminate нужно помнить: нестрогого режима нет — contains('1') на коллекции [1] вернёт false (это намеренно).

✅ Рекомендуется

• Проверять права/идентификаторы только строгим contains/whereIn.
• Использовать sole() там, где дубль — ошибка данных (уникальный e-mail, один активный договор).
• Передавать default в get/first вместо проверок isEmpty() перед чтением.

❌ Антипаттерны

• $c->filter(...)->count() > 0 вместо $c->some(...) — лишний проход и аллокация.
• Полагаться на приведение типов при поиске: приводите значение явно до contains.