В Laravel 12.49 добавлен метод hasSole() для коллекций

В Laravel 12.49 появилась новая удобная функция в API коллекций - метод hasSole(). Он позволяет просто и выразительно проверить, содержит ли коллекция ровно один элемент, соответствующий заданному условию. Это делает код чище и понятнее по сравнению с предыдущими способами проверки.

Что делает hasSole()

Метод hasSole() возвращает булево значение: true, если в коллекции найден ровно один элемент, либо false, если элементов нет или их несколько. По сути он заменяет устаревший метод containsOneItem(), сохраняя совместимость, но предлагая более современный и однозначный интерфейс.

В отличие от метода sole(), который выбрасывает исключение, когда условие не выполняется, hasSole() лишь возвращает false. Это избавляет от необходимости оборачивать проверку в блок try/catch или писать дополнительные условия для подсчёта элементов.

Какие фильтры поддерживаются

Метод hasSole() поддерживает те же варианты фильтрации, что и sole():

• Без фильтра - проверяет, есть ли ровно один элемент в коллекции.

• Callback‑фильтр - передаётся анонимная функция, по которой отбираются элементы.

• Проверка по ключ‑значение - ищет совпадения по определённому полю.

• С операторами сравнения (<, >= и т. п.) - удобно для числовых значений.

Примеры использования

Без фильтра

Проверяем, что коллекция содержит только один элемент:

$users = collect(['Alice']);

if ($users->hasSole()) {
    echo "Найден ровно один пользователь.";
}

С callback

Ищем ровно одного активного пользователя:

$users = collect([
    ['name' => 'Alice', 'active' => true],
    ['name' => 'Bob',   'active' => false],
]);

if ($users->hasSole(fn ($user) => $user['active'])) {
    echo "Найден ровно один активный пользователь.";
}

По ключ‑значению

Проверка единственного заказа со статусом pending:

$orders = collect([
    ['id' => 1, 'status' => 'pending'],
    ['id' => 2, 'status' => 'completed'],
]);

if ($orders->hasSole('status', 'pending')) {
    echo "Есть ровно один заказ в состоянии pending.";
}

С оператором

Ищем ровно одного пользователя старше 25 лет:

$users = collect([
    ['name' => 'Alice', 'age' => 22],
    ['name' => 'Bob',   'age' => 25],
]);

if ($users->hasSole('age', '>=', 25)) {
    echo "Найден ровно один пользователь 25 лет или старше.";
}

Поддержка LazyCollection

Метод hasSole() также работает с LazyCollection, сохраняя ленивую обработку. Это значит, что проверка будет раньше прекращена, как только станет понятно, что условие (ровно один элемент) нарушено. Например, найдено более одного совпадения или ни одного. Такой подход эффективен при обработке больших наборов данных.

Устаревший метод containsOneItem()

Старая функция containsOneItem() теперь делегирует работу hasSole() и считается устаревшей. Это даёт обратную совместимость и плавный переход к новой, более выразительной форме API. В будущих версиях Laravel (13.x) containsOneItem() будет полностью удалён, а hasSole() станет частью интерфейса Enumerable.