Laravel 10.x Collections: Работа с Коллекциями в Laravel

Введение
- Создание Коллекций
- Расширение Коллекций
Доступные Методы
Сообщения Более Высокого Порядка
Ленивые Коллекции

Введение

Класс Illuminate\Support\Collection предоставляет удобную оболочку для работы с массивами данных. Например, рассмотрим следующий код. Мы будем использовать вспомогательную функцию collect для создания нового экземпляра коллекции из массива, выполнять функцию strtoupper для каждого элемента, а затем удалять все пустые элементы:

$collection = collect(['taylor', 'abigail', null])->map(function (string $name) {
    return strtoupper($name);
})->reject(function (string $name) {
    return empty($name);
});

Как видите, класс Collection позволяет объединять свои методы для выполнения связанного отображения и уменьшения базового массива. В общем случае коллекции являются неизменяемыми, что означает, что каждый метод Collection возвращает совершенно новый экземпляр Collection.

Создание Коллекций

Как уже упоминалось выше, вспомогательная функция collect возвращает новый экземпляр Illuminate\Support\Collection для заданного массива. Так что создать коллекцию просто:

$collection = collect([1, 2, 3]);

Примечание Результаты запросов Eloquent всегда возвращаются в виде экземпляров Collection.

Расширение Коллекций

Коллекции поддерживают "макрорасширение", что позволяет добавлять дополнительные методы к классу Collection во время выполнения. Метод macro класса Illuminate\Support\Collection принимает замыкание, которое будет выполнено при вызове вашего макроса. Замыкание макроса может обращаться к другим методам коллекции через $this, как если бы оно было реальным методом класса коллекции. Например, следующий код добавляет метод toUpper к классу Collection:

use Illuminate\Support\Collection;
use Illuminate\Support\Str;
Collection::macro('toUpper', function () {
    return $this->map(function (string $value) {
        return Str::upper($value);
    });
});
$collection = collect(['first', 'second']);
$upper = $collection->toUpper();
// ['FIRST', 'SECOND']

Обычно следует объявлять макросы коллекций в методе boot поставщика услуг.

Аргументы Макроса

При необходимости вы можете определять макросы, принимающие дополнительные аргументы:

use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Lang;
Collection::macro('toLocale', function (string $locale) {
    return $this->map(function (string $value) use ($locale) {
        return Lang::get($value, [], $locale);
    });
});
$collection = collect(['first', 'second']);
$translated = $collection->toLocale('es');

Доступные Методы

Для большинства оставшихся разделов документации по коллекциям мы рассмотрим каждый метод, доступный в классе Collection. Помните, что все эти методы можно цеплять для плавного манипулирования базовым массивом. Кроме того, почти каждый метод возвращает новый экземпляр Collection, позволяя вам сохранить оригинальную копию коллекции, когда это необходимо:

all average avg chunk chunkWhile collapse collect combine concat contains containsOneItem containsStrict count countBy crossJoin dd diff diffAssoc diffAssocUsing diffKeys doesntContain dot dump duplicates duplicatesStrict each eachSpread ensure every except filter first firstOrFail firstWhere flatMap flatten flip forget forPage get groupBy has hasAny implode intersect intersectAssoc intersectByKeys isEmpty isNotEmpty join keyBy keys last lazy macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition percentage pipe pipeInto pipeThrough pluck pop prepend pull push put random range reduce reduceSpread reject replace replaceRecursive reverse search shift shuffle skip skipUntil skipWhile slice sliding sole some sort sortBy sortByDesc sortDesc sortKeys sortKeysDesc sortKeysUsing splice split splitIn sum take takeUntil takeWhile tap times toArray toJson transform undot union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap value values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict whereNotNull whereNull wrap zip

Список Методов

`all()`

Метод all возвращает базовый массив, представленный коллекцией:

collect([1, 2, 3])->all();
// [1, 2, 3]

`average()`

Псевдоним для метода avg.

`avg()`

Метод avg возвращает среднее значение для заданного ключа:

$average = collect([
    ['foo' => 10],
    ['foo' => 10],
    ['foo' => 20],
    ['foo' => 40]
])->avg('foo');
// 20
$average = collect([1, 1, 2, 4])->avg();
// 2

`chunk()`

Метод chunk разбивает коллекцию на несколько более мелких коллекций с заданным размером:

$collection = collect([1, 2, 3, 4, 5, 6, 7]);
$chunks = $collection->chunk(4);
$chunks->all();
// [[1, 2, 3, 4], [5, 6, 7]]

Этот метод особенно полезен в шаблонах, когда вы работаете с сеткой, такой как Bootstrap. Например, представьте, что у вас есть коллекция моделей Eloquent, которые вы хотите отобразить в сетке:

@foreach ($products->chunk(3) as $chunk)
    <div class="row">
        @foreach ($chunk as $product)
            <div class="col-xs-4">{{ $product->name }}</div>
        @endforeach
    </div>
@endforeach

`chunkWhile()`

Метод chunkWhile разбивает коллекцию на несколько более мелких коллекций на основе оценки заданного замыкания. Переменную $chunk, переданную замыканию, можно использовать для проверки предыдущего элемента:

$collection = collect(str_split('AABBCCCD'));
$chunks = $collection->chunkWhile(function (string $value, int $key, Collection $chunk) {
    return $value === $chunk->last();
});
$chunks->all();
// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]

`collapse()`

Метод collapse объединяет коллекцию массивов в одну плоскую коллекцию:

$collection = collect([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]);
$collapsed = $collection->collapse();
$collapsed->all();
// [1, 2, 3, 4, 5, 6, 7, 8, 9]

`collect()`

Метод collect возвращает новый экземпляр Collection с элементами, находящимися в данный момент в коллекции:

$collectionA = collect([1, 2, 3]);
$collectionB = $collectionA->collect();
$collectionB->all();
// [1, 2, 3]

Метод collect в основном полезен для преобразования ленивых коллекций в стандартные экземпляры Collection:

$lazyCollection = LazyCollection::make(function () {
    yield 1;
    yield 2;
    yield 3;
});
$collection = $lazyCollection->collect();
$collection::class;
// 'Illuminate\Support\Collection'
$collection->all();
// [1, 2, 3]

Примечание Метод collect особенно полезен, когда у вас есть экземпляр Enumerable, и вам нужен экземпляр коллекции, который не является ленивым. Поскольку collect() является частью контракта Enumerable, вы можете безопасно использовать его для получения экземпляра Collection.

`combine()`

Метод combine объединяет значения коллекции в качестве ключей с значениями другого массива или коллекции:

$collection = collect(['name', 'age']);
$combined = $collection->combine(['George', 29]);
$combined->all();
// ['name' => 'George', 'age' => 29]

`concat()`

Метод concat добавляет значения заданного array или коллекции в конец другой коллекции:

$collection = collect(['John Doe']);
$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
$concatenated->all();
// ['John Doe', 'Jane Doe', 'Johnny Doe']

Метод concat переиндексирует ключи численно для элементов, добавленных в конец исходной коллекции. Чтобы сохранить ключи в ассоциативных коллекциях, см. метод merge.

`contains()`

Метод contains определяет, содержит ли коллекция заданный элемент. Вы можете передать замыкание методу contains, чтобы определить, существует ли в коллекции элемент, соответствующий заданному условию:

$collection = collect([1, 2, 3, 4, 5]);
$collection->contains(function (int $value, int $key) {
    return $value > 5;
});
// false

В качестве альтернативы, вы можете передать строку методу contains, чтобы определить, содержит ли коллекция заданное значение элемента:

$collection = collect(['name' => 'Desk', 'price' => 100]);
$collection->contains('Desk');
// true
$collection->contains('New York');
// false

Вы также можете передать пару ключ / значение методу contains, который определит, существует ли данная пара в коллекции:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
]);
$collection->contains('product', 'Bookcase');
// false

Метод contains использует "мягкие" сравнения при проверке значений элементов, что означает, что строка с числовым значением будет считаться равной целому числу с тем же значением. Используйте метод containsStrict, чтобы фильтровать с использованием "строгих" сравнений.

Для обратного действия от contains см. метод doesntContain.

`containsOneItem()`

Метод containsOneItem определяет, содержит ли коллекция единственный элемент:

collect([])->containsOneItem();
// false
collect(['1'])->containsOneItem();
// true
collect(['1', '2'])->containsOneItem();
// false

`containsStrict()`

Этот метод имеет такую же сигнатуру, как у метода contains; однако все значения сравниваются с использованием "строгих" сравнений.

Примечание Поведение этого метода изменяется при использовании Eloquent Collections.

`count()`

Метод count возвращает общее количество элементов в коллекции:

$collection = collect([1, 2, 3, 4]);
$collection->count();
// 4

`countBy()`

Метод countBy подсчитывает количество вхождений значений в коллекции. По умолчанию метод подсчитывает количество вхождений каждого элемента, позволяя вам подсчитывать определенные "типы" элементов в коллекции:

$collection = collect([1, 2, 2, 2, 3]);
$counted = $collection->countBy();
$counted->all();
// [1 => 1, 2 => 3, 3 => 1]

Передайте замыкание методу countBy, чтобы подсчитать все элементы по пользовательскому значению:

$collection = collect(['[email protected]', '[email protected]', '[email protected]']);
$counted = $collection->countBy(function (string $email) {
    return substr(strrchr($email, "@"), 1);
});
$counted->all();
// ['gmail.com' => 2, 'yahoo.com' => 1]

`crossJoin()`

Метод crossJoin выполняет кросс-соединение значений коллекции среди заданных массивов или коллекций, возвращая декартово произведение со всеми возможными перестановками:

$collection = collect([1, 2]);
$matrix = $collection->crossJoin(['a', 'b']);
$matrix->all();
/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/
$collection = collect([1, 2]);
$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
$matrix->all();
/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

`dd()`

Метод dd выводит элементы коллекции и завершает выполнение сценария:

$collection = collect(['John Doe', 'Jane Doe']);
$collection->dd();
/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

Если вы не хотите остановить выполнение сценария, используйте вместо этого метод dump.

`diff()`

Метод diff сравнивает коллекцию с другой коллекцией или обычным массивом PHP на основе их значений. Этот метод вернет значения в исходной коллекции, которых нет в заданной коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();
// [1, 3, 5]

Примечание Поведение этого метода изменяется при использовании Eloquent Collections.

`diffAssoc()`

Метод diffAssoc сравнивает коллекцию с другой коллекцией или обычным массивом PHP на основе их ключей и значений. Этот метод вернет пары ключ / значение в исходной коллекции, которых нет в заданной коллекции:

$collection = collect([
    'color' => 'orange',
    'type' => 'fruit',
    'remain' => 6,
]);
$diff = $collection->diffAssoc([
    'color' => 'yellow',
    'type' => 'fruit',
    'remain' => 3,
    'used' => 6,
]);
$diff->all();
// ['color' => 'orange', 'remain' => 6]

`diffAssocUsing()`

В отличие от diffAssoc, diffAssocUsing принимает функцию обратного вызова пользователя для сравнения индексов:

$collection = collect([
    'color' => 'orange',
    'type' => 'fruit',
    'remain' => 6,
]);
$diff = $collection->diffAssocUsing([
    'Color' => 'yellow',
    'Type' => 'fruit',
    'Remain' => 3,
], 'strnatcasecmp');
$diff->all();
// ['color' => 'orange', 'remain' => 6]

Функция обратного вызова должна быть функцией сравнения, возвращающей целое число меньше, равное или большее нуля. Дополнительную информацию можно найти в документации PHP по array_diff_uassoc, функции PHP, которую использует метод diffAssocUsing внутренне.

`diffKeys()`

Метод diffKeys сравнивает коллекцию с другой коллекцией или обычным массивом PHP на основе их ключей. Этот метод вернет пары ключ / значение в исходной коллекции, которых нет в заданной коллекции:

$collection = collect([
    'one' => 10,
    'two' => 20,
    'three' => 30,
    'four' => 40,
    'five' => 50,
]);
$diff = $collection->diffKeys([
    'two' => 2,
    'four' => 4,
    'six' => 6,
    'eight' => 8,
]);
$diff->all();
// ['one' => 10, 'three' => 30, 'five' => 50]

`doesntContain()`

Метод doesntContain определяет, не содержит ли коллекция заданный элемент. Вы можете передать замыкание методу doesntContain, чтобы определить, не существует ли в коллекции элемента, соответствующего заданному условию:

$collection = collect([1, 2, 3, 4, 5]);
$collection->doesntContain(function (int $value, int $key) {
    return $value < 5;
});
// false

В качестве альтернативы, вы можете передать строку методу doesntContain, чтобы определить, не содержит ли коллекция заданное значение элемента:

$collection = collect(['name' => 'Desk', 'price' => 100]);
$collection->doesntContain('Table');
// true
$collection->doesntContain('Desk');
// false

Вы также можете передать пару ключ / значение методу doesntContain, который определит, не существует ли данная пара в коллекции:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
]);
$collection->doesntContain('product', 'Bookcase');
// true

Метод doesntContain использует "мягкие" сравнения при проверке значений элементов, что означает, что строка с числовым значением будет считаться равной целому числу с тем же значением.

`dot()`

Метод dot выравнивает многомерную коллекцию в одноуровневую коллекцию, используя "точечную" нотацию для обозначения глубины:

$collection = collect(['products' => ['desk' => ['price' => 100]]]);
$flattened = $collection->dot();
$flattened->all();
// ['products.desk.price' => 100]

`dump()`

Метод dump выводит элементы коллекции:

$collection = collect(['John Doe', 'Jane Doe']);
$collection->dump();
/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

Если вы хотите остановить выполнение сценария после вывода коллекции, используйте метод dd.

`duplicates()`

Метод duplicates извлекает и возвращает повторяющиеся значения из коллекции:

$collection = collect(['a', 'b', 'a', 'c', 'b']);
$collection->duplicates();
// [2 => 'a', 4 => 'b']

Если в коллекции есть массивы или объекты, вы можете передать ключ атрибутов, которые вы хотите проверить на наличие повторяющихся значений:

$employees = collect([
    ['email' => '[email protected]', 'position' => 'Developer'],
    ['email' => '[email protected]', 'position' => 'Designer'],
    ['email' => '[email protected]', 'position' => 'Developer'],
]);
$employees->duplicates('position');
// [2 => 'Developer']

`duplicatesStrict()`

Этот метод имеет такую же сигнатуру, как у метода duplicates; однако все значения сравниваются с использованием "строгих" сравнений.

`each()`

Метод each выполняет итерацию по элементам коллекции и передает каждый элемент замыканию:

$collection = collect([1, 2, 3, 4]);
$collection->each(function (int $item, int $key) {
    // ...
});

Если вы хотите прекратить итерацию по элементам, вы можете вернуть false из вашего замыкания:

$collection->each(function (int $item, int $key) {
    if (/* condition */) {
        return false;
    }
});

`eachSpread()`

Метод eachSpread выполняет итерацию по элементам коллекции, передавая каждое вложенное значение элемента в заданное замыкание:

$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
$collection->eachSpread(function (string $name, int $age) {
    // ...
});

Вы можете прекратить итерацию по элементам, вернув false из замыкания:

$collection->eachSpread(function (string $name, int $age) {
    return false;
});

`ensure()`

Метод ensure можно использовать для проверки того, что все элементы коллекции имеют заданный тип. В противном случае будет вызвано исключение UnexpectedValueException:

return $collection->ensure(User::class);

Также можно указывать примитивные типы, такие как string, int, float, bool и array:

return $collection->ensure('int');

Внимание Метод ensure не гарантирует, что элементы разных типов не будут добавлены в коллекцию впоследствии.

`every()`

Метод every можно использовать для проверки того, что все элементы коллекции проходят заданное условие истинности:

collect([1, 2, 3, 4])->every(function (int $value, int $key) {
    return $value > 2;
});
// false

Если коллекция пуста, метод every вернет true:

$collection = collect([]);
$collection->every(function (int $value, int $key) {
    return $value > 2;
});
// true

`except()`

Метод except возвращает все элементы в коллекции, за исключением тех, у которых указаны ключи:

$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
$filtered = $collection->except(['price', 'discount']);
$filtered->all();
// ['product_id' => 1]

Для обратного действия от except см. метод only.

Примечание Поведение этого метода изменяется при использовании Eloquent Collections.

`filter()`

Метод filter фильтрует коллекцию с использованием заданного замыкания, оставляя только те элементы, которые проходят заданное условие истинности:

$collection = collect([1, 2, 3, 4]);
$filtered = $collection->filter(function (int $value, int $key) {
    return $value > 2;
});
$filtered->all();
// [3, 4]

Если замыкание не предоставлено, будут удалены все записи коллекции, эквивалентные false:

$collection = collect([1, 2, 3, null, false, '', 0, []]);
$collection->filter()->all();
// [1, 2, 3]

Для обратного действия от filter см. метод reject.

`first()`

Метод first возвращает первый элемент в коллекции, проходящий заданное условие истинности:

collect([1, 2, 3, 4])->first(function (int $value, int $key) {
    return $value > 2;
});
// 3

Вы также можете вызвать метод first без аргументов, чтобы получить первый элемент в коллекции. Если коллекция пуста, будет возвращено null:

collect([1, 2, 3, 4])->first();
// 1

`firstOrFail()`

Метод firstOrFail идентичен методу first; однако, если результат не найден, будет сгенерировано исключение Illuminate\Support\ItemNotFoundException:

collect([1, 2, 3, 4])->firstOrFail(function (int $value, int $key) {
    return $value > 5;
});
// Throws ItemNotFoundException...

Вы также можете вызвать метод firstOrFail без аргументов, чтобы получить первый элемент в коллекции. Если коллекция пуста, будет сгенерировано исключение Illuminate\Support\ItemNotFoundException:

collect([])->firstOrFail();
// Throws ItemNotFoundException...

`firstWhere()`

Метод firstWhere возвращает первый элемент в коллекции с указанной парой ключ / значение:

$collection = collect([
    ['name' => 'Regena', 'age' => null],
    ['name' => 'Linda', 'age' => 14],
    ['name' => 'Diego', 'age' => 23],
    ['name' => 'Linda', 'age' => 84],
]);
$collection->firstWhere('name', 'Linda');
// ['name' => 'Linda', 'age' => 14]

Вы также можете вызвать метод firstWhere с оператором сравнения:

$collection->firstWhere('age', '>=', 18);
// ['name' => 'Diego', 'age' => 23]

Как и метод where, вы можете передать методу firstWhere только один аргумент. В этом случае метод firstWhere вернет первый элемент, где значение ключа заданного элемента является «истинным»:

$collection->firstWhere('age');
// ['name' => 'Linda', 'age' => 14]

`flatMap()`

Метод flatMap проходит через коллекцию и передает каждое значение заданному замыканию. Замыкание в свою очередь может изменять элемент и возвращать его, таким образом формируя новую коллекцию измененных элементов. Затем массив уплощается на один уровень:

$collection = collect([
    ['name' => 'Sally'],
    ['school' => 'Arkansas'],
    ['age' => 28]
]);
$flattened = $collection->flatMap(function (array $values) {
    return array_map('strtoupper', $values);
});
$flattened->all();
// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];

`flatten()`

Метод flatten уплощает многомерную коллекцию до одного уровня:

$collection = collect([
    'name' => 'taylor',
    'languages' => [
        'php', 'javascript'
    ]
]);
$flattened = $collection->flatten();
$flattened->all();
// ['taylor', 'php', 'javascript'];

При необходимости вы можете передать методу flatten аргумент "глубина":

$collection = collect([
    'Apple' => [
        [
            'name' => 'iPhone 6S',
            'brand' => 'Apple'
        ],
    ],
    'Samsung' => [
        [
            'name' => 'Galaxy S7',
            'brand' => 'Samsung'
        ],
    ],
]);
$products = $collection->flatten(1);
$products->values()->all();
/*
    [
        ['name' => 'iPhone 6S', 'brand' => 'Apple'],
        ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
    ]
*/

В этом примере вызов flatten без указания глубины также был бы уплощен вложенные массивы, что привело бы к ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']. Указание глубины позволяет указать количество уровней вложенных массивов, которые будут уплощены.

`flip()`

Метод flip меняет ключи коллекции на их соответствующие значения:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$flipped = $collection->flip();
$flipped->all();
// ['taylor' => 'name', 'laravel' => 'framework']

`forget()`

Метод forget удаляет элемент из коллекции по его ключу:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$collection->forget('name');
$collection->all();
// ['framework' => 'laravel']

Внимание В отличие от большинства других методов коллекций, forget не возвращает новую измененную коллекцию; он изменяет саму коллекцию, на которой он вызывается.

`forPage()`

Метод forPage возвращает новую коллекцию, содержащую элементы, которые присутствовали бы на заданной странице. Метод принимает номер страницы в качестве первого аргумента и количество элементов для отображения на странице в качестве второго аргумента:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunk = $collection->forPage(2, 3);
$chunk->all();
// [4, 5, 6]

`get()`

Метод get возвращает элемент по заданному ключу. Если ключ не существует, возвращается null:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('name');
// taylor

Вы можете передать вторым аргументом значение по умолчанию:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('age', 34);
// 34

Вы даже можете передать в метод значение по умолчанию в виде замыкания. Результатом замыкания будет возвращено, если указанный ключ не существует:

$collection->get('email', function () {
    return '[email protected]';
});
// [email protected]

`groupBy()`

Метод groupBy группирует элементы коллекции по заданному ключу:

$collection = collect([
    ['account_id' => 'account-x10', 'product' => 'Chair'],
    ['account_id' => 'account-x10', 'product' => 'Bookcase'],
    ['account_id' => 'account-x11', 'product' => 'Desk'],
]);
$grouped = $collection->groupBy('account_id');
$grouped->all();
/*
    [
        'account-x10' => [
            ['account_id' => 'account-x10', 'product' => 'Chair'],
            ['account_id' => 'account-x10', 'product' => 'Bookcase'],
        ],
        'account-x11' => [
            ['account_id' => 'account-x11', 'product' => 'Desk'],
        ],
    ]
*/

Вместо передачи строки key вы можете передать замыкание. Замыкание должно возвращать значение, по которому вы хотите сгруппировать:

$grouped = $collection->groupBy(function (array $item, int $key) {
    return substr($item['account_id'], -3);
});
$grouped->all();
/*
    [
        'x10' => [
            ['account_id' => 'account-x10', 'product' => 'Chair'],
            ['account_id' => 'account-x10', 'product' => 'Bookcase'],
        ],
        'x11' => [
            ['account_id' => 'account-x11', 'product' => 'Desk'],
        ],
    ]
*/

Множественные критерии группировки могут быть переданы в виде массива. Каждый элемент массива будет применен к соответствующему уровню в многомерном массиве:

$data = new Collection([
    10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
    20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
    30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
    40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
]);
$result = $data->groupBy(['skill', function (array $item) {
    return $item['roles'];
}], preserveKeys: true);
/*
[
    1 => [
        'Role_1' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_2' => [
            20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
        ],
        'Role_3' => [
            10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
        ],
    ],
    2 => [
        'Role_1' => [
            30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
        ],
        'Role_2' => [
            40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
        ],
    ],
];
*/

`has()`

Метод has определяет, существует ли заданный ключ в коллекции:

$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
$collection->has('product');
// true
$collection->has(['product', 'amount']);
// true
$collection->has(['amount', 'price']);
// false

`hasAny()`

Метод hasAny определяет, существует ли хотя бы один из указанных ключей в коллекции:

$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
$collection->hasAny(['product', 'price']);
// true
$collection->hasAny(['name', 'price']);
// false

`implode()`

Метод implode объединяет элементы в коллекции. Его аргументы зависят от типа элементов в коллекции. Если коллекция содержит массивы или объекты, вы должны передать ключ атрибутов, которые вы хотите объединить, и строку "клея", которую вы хотите поместить между значениями:

$collection = collect([
    ['account_id' => 1, 'product' => 'Desk'],
    ['account_id' => 2, 'product' => 'Chair'],
]);
$collection->implode('product', ', ');
// Desk, Chair

Если коллекция содержит простые строки или числовые значения, вы должны передать "клей" в качестве единственного аргумента методу:

collect([1, 2, 3, 4, 5])->implode('-');
// '1-2-3-4-5'

Вы можете передать в implode метод замыкание, если хотите форматировать значения, которые объединяются:

$collection->implode(function (array $item, int $key) {
    return strtoupper($item['product']);
}, ', ');
// DESK, CHAIR

`intersect()`

Метод intersect удаляет из оригинальной коллекции любые значения, которых нет в заданном array или коллекции. Результирующая коллекция сохранит ключи оригинальной коллекции:

$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();
// [0 => 'Desk', 2 => 'Chair']

Примечание Поведение этого метода изменяется при использовании Eloquent Collections.

`intersectAssoc()`

Метод intersectAssoc сравнивает оригинальную коллекцию с другой коллекцией или array, возвращая пары ключ / значение, присутствующие во всех заданных коллекциях:

$collection = collect([
    'color' => 'red',
    'size' => 'M',
    'material' => 'cotton'
]);
$intersect = $collection->intersectAssoc([
    'color' => 'blue',
    'size' => 'M',
    'material' => 'polyester'
]);
$intersect->all();
// ['size' => 'M']

`intersectByKeys()`

Метод intersectByKeys удаляет из оригинальной коллекции любые ключи и соответствующие значения, которых нет в заданном array или коллекции:

$collection = collect([
    'serial' => 'UX301', 'type' => 'screen', 'year' => 2009,
]);
$intersect = $collection->intersectByKeys([
    'reference' => 'UX404', 'type' => 'tab', 'year' => 2011,
]);
$intersect->all();
// ['type' => 'screen', 'year' => 2009]

`isEmpty()`

Метод isEmpty возвращает true, если коллекция пуста, в противном случае возвращается false:

collect([])->isEmpty();
// true

`isNotEmpty()`

Метод isNotEmpty возвращает true, если коллекция не пуста, в противном случае возвращается false:

collect([])->isNotEmpty();
// false

`join()`

Метод join объединяет значения коллекции строкой. Используя второй аргумент этого метода, вы также можете указать, какой элемент должен быть добавлен к строке в конце:

collect(['a', 'b', 'c'])->join(', '); // 'a, b, c'
collect(['a', 'b', 'c'])->join(', ', ', and '); // 'a, b, and c'
collect(['a', 'b'])->join(', ', ' and '); // 'a and b'
collect(['a'])->join(', ', ' and '); // 'a'
collect([])->join(', ', ' and '); // ''

`keyBy()`

Метод keyBy ключирует коллекцию по заданному ключу. Если у нескольких элементов одинаковый ключ, в новой коллекции будет только последний:

$collection = collect([
    ['product_id' => 'prod-100', 'name' => 'Desk'],
    ['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$keyed = $collection->keyBy('product_id');
$keyed->all();
/*
    [
        'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

Вы также можете передать замыкание методу. Замыкание должно возвращать значение, по которому вы хотите сгруппировать коллекцию:

$keyed = $collection->keyBy(function (array $item, int $key) {
    return strtoupper($item['product_id']);
});
$keyed->all();
/*
    [
        'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

`keys()`

Метод keys возвращает все ключи коллекции:

$collection = collect([
    'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
    'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$keys = $collection->keys();
$keys->all();
// ['prod-100', 'prod-200']

`last()`

Метод last возвращает последний элемент в коллекции, который проходит заданное условие истинности:

collect([1, 2, 3, 4])->last(function (int $value, int $key) {
    return $value < 3;
});
// 2

Вы также можете вызвать метод last без аргументов, чтобы получить последний элемент в коллекции. Если коллекция пуста, возвращается null:

collect([1, 2, 3, 4])->last();
// 4

`lazy()`

Метод lazy возвращает новый экземпляр LazyCollection из базового массива элементов:

$lazyCollection = collect([1, 2, 3, 4])->lazy();
$lazyCollection::class;
// Illuminate\Support\LazyCollection
$lazyCollection->all();
// [1, 2, 3, 4]

Это особенно полезно, когда вам нужно выполнять преобразования в огромной коллекции, содержащей много элементов:

$count = $hugeCollection
    ->lazy()
    ->where('country', 'FR')
    ->where('balance', '>', '100')
    ->count();

Преобразовав коллекцию в LazyCollection, мы избегаем выделения большого количества дополнительной памяти. Хотя оригинальная коллекция все еще хранит свои значения в памяти, последующие фильтры этого не будут делать. Следовательно, при фильтрации результатов коллекции практически не выделяется дополнительной памяти.

`macro()`

Статический метод macro позволяет добавлять методы к классу Collection на лету. См. документацию по расширению коллекций для получения дополнительной информации.

`make()`

Статический метод make создает новый экземпляр коллекции. См. раздел Создание коллекций.

`map()`

Метод map перебирает коллекцию и передает каждое значение заданному замыканию. Замыкание вправе изменять элемент и возвращать его, образуя таким образом новую коллекцию измененных элементов:

$collection = collect([1, 2, 3, 4, 5]);
$multiplied = $collection->map(function (int $item, int $key) {
    return $item * 2;
});
$multiplied->all();
// [2, 4, 6, 8, 10]

Внимание Как и большинство других методов коллекций, map возвращает новый экземпляр коллекции; он не изменяет коллекцию, на которой вызывается. Если вы хотите преобразовать исходную коллекцию, используйте метод transform.

`mapInto()`

Метод mapInto() перебирает коллекцию, создавая новый экземпляр заданного класса, передавая значение в конструктор:

class Currency
{
    /**
     * Create a new currency instance.
     */
    function __construct(
        public string $code
    ) {}
}
$collection = collect(['USD', 'EUR', 'GBP']);
$currencies = $collection->mapInto(Currency::class);
$currencies->all();
// [Currency('USD'), Currency('EUR'), Currency('GBP')]

`mapSpread()`

Метод mapSpread перебирает элементы коллекции, передавая каждое вложенное значение в заданное замыкание. Замыкание вправе изменять элемент и возвращать его, образуя таким образом новую коллекцию измененных элементов:

$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunks = $collection->chunk(2);
$sequence = $chunks->mapSpread(function (int $even, int $odd) {
    return $even + $odd;
});
$sequence->all();
// [1, 5, 9, 13, 17]

`mapToGroups()`

Метод mapToGroups группирует элементы коллекции по заданному замыканию. Замыкание должно возвращать ассоциативный массив, содержащий одну пару ключ / значение, образуя таким образом новую коллекцию сгруппированных значений:

$collection = collect([
    [
        'name' => 'John Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Jane Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Johnny Doe',
        'department' => 'Marketing',
    ]
]);
$grouped = $collection->mapToGroups(function (array $item, int $key) {
    return [$item['department'] => $item['name']];
});
$grouped->all();
/*
    [
        'Sales' => ['John Doe', 'Jane Doe'],
        'Marketing' => ['Johnny Doe'],
    ]
*/
$grouped->get('Sales')->all();
// ['John Doe', 'Jane Doe']

`mapWithKeys()`

Метод mapWithKeys перебирает коллекцию и передает каждое значение заданному замыканию. Замыкание должно возвращать ассоциативный массив, содержащий одну пару ключ / значение:

$collection = collect([
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => '[email protected]',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => '[email protected]',
    ]
]);
$keyed = $collection->mapWithKeys(function (array $item, int $key) {
    return [$item['email'] => $item['name']];
});
$keyed->all();
/*
    [
        '[email protected]' => 'John',
        '[email protected]' => 'Jane',
    ]
*/

`max()`

Метод max возвращает максимальное значение заданного ключа:

$max = collect([
    ['foo' => 10],
    ['foo' => 20]
])->max('foo');
// 20
$max = collect([1, 2, 3, 4, 5])->max();
// 5

`median()`

Метод median возвращает медианное значение заданного ключа:

$median = collect([
    ['foo' => 10],
    ['foo' => 10],
    ['foo' => 20],
    ['foo' => 40]
])->median('foo');
// 15
$median = collect([1, 1, 2, 4])->median();
// 1.5

`merge()`

Метод merge объединяет данный массив или коллекцию с оригинальной коллекцией. Если строковой ключ в данных элементах совпадает со строковым ключом в оригинальной коллекции, значение элемента в данных перезапишет значение в оригинальной коллекции:

$collection = collect(['product_id' => 1, 'price' => 100]);
$merged = $collection->merge(['price' => 200, 'discount' => false]);
$merged->all();
// ['product_id' => 1, 'price' => 200, 'discount' => false]

Если ключи данного элемента являются числовыми, значения будут добавлены в конец коллекции:

$collection = collect(['Desk', 'Chair']);
$merged = $collection->merge(['Bookcase', 'Door']);
$merged->all();
// ['Desk', 'Chair', 'Bookcase', 'Door']

`mergeRecursive()`

Метод mergeRecursive рекурсивно объединяет данный массив или коллекцию с оригинальной коллекцией. Если строковой ключ в данных элементах совпадает со строковым ключом в оригинальной коллекции, значения для этих ключей объединяются в массив, и это делается рекурсивно:

$collection = collect(['product_id' => 1, 'price' => 100]);
$merged = $collection->mergeRecursive([
    'product_id' => 2,
    'price' => 200,
    'discount' => false
]);
$merged->all();
// ['product_id' => [1, 2], 'price' => [100, 200], 'discount' => false]

`min()`

Метод min возвращает минимальное значение заданного ключа:

$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');
// 10
$min = collect([1, 2, 3, 4, 5])->min();
// 1

`mode()`

Метод mode возвращает модальное значение заданного ключа:

$mode = collect([
    ['foo' => 10],
    ['foo' => 10],
    ['foo' => 20],
    ['foo' => 40]
])->mode('foo');
// [10]
$mode = collect([1, 1, 2, 4])->mode();
// [1]
$mode = collect([1, 1, 2, 2])->mode();
// [1, 2]

`nth()`

Метод nth создает новую коллекцию, состоящую из каждого n-го элемента:

$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
$collection->nth(4);
// ['a', 'e']

Вы также можете передать начальное смещение вторым аргументом:

$collection->nth(4, 1);
// ['b', 'f']

`only()`

Метод only возвращает элементы коллекции с указанными ключами:

$collection = collect([
    'product_id' => 1,
    'name' => 'Desk',
    'price' => 100,
    'discount' => false
]);
$filtered = $collection->only(['product_id', 'name']);
$filtered->all();
// ['product_id' => 1, 'name' => 'Desk']

Для обратной операции по отношению к only, см. метод except.

Примечание Поведение этого метода изменяется при использовании Eloquent Collections.

`pad()`

Метод pad заполнит массив заданным значением до достижения указанного размера. Этот метод ведет себя подобно функции PHP array_pad.

Для заполнения слева вы должны указать отрицательный размер. Заполнение не произойдет, если абсолютное значение заданного размера меньше или равно длине массива:

$collection = collect(['A', 'B', 'C']);
$filtered = $collection->pad(5, 0);
$filtered->all();
// ['A', 'B', 'C', 0, 0]
$filtered = $collection->pad(-5, 0);
$filtered->all();
// [0, 0, 'A', 'B', 'C']

`partition()`

Метод partition может быть объединен с деструктивизацией массивов PHP для разделения элементов, проходящих заданное условие истинности, от тех, которые этого не делают:

$collection = collect([1, 2, 3, 4, 5, 6]);
[$underThree, $equalOrAboveThree] = $collection->partition(function (int $i) {
    return $i < 3;
});
$underThree->all();
// [1, 2]
$equalOrAboveThree->all();
// [3, 4, 5, 6]

`percentage()`

Метод percentage может использоваться для быстрого определения процента элементов коллекции, проходящих заданное условие истинности:

$collection = collect([1, 1, 2, 2, 2, 3]);
$percentage = $collection->percentage(fn ($value) => $value === 1);
// 33.33

По умолчанию процент будет округлен до двух знаков после запятой. Однако вы можете настроить это поведение, предоставив второй аргумент методу:

$percentage = $collection->percentage(fn ($value) => $value === 1, precision: 3);
// 33.333

`pipe()`

Метод pipe передает коллекцию заданному замыканию и возвращает результат выполненного замыкания:

$collection = collect([1, 2, 3]);
$piped = $collection->pipe(function (Collection $collection) {
    return $collection->sum();
});
// 6

`pipeInto()`

Метод pipeInto создает новый экземпляр заданного класса и передает коллекцию в его конструктор:

class ResourceCollection
{
    /**
     * Create a new ResourceCollection instance.
     */
    public function __construct(
      public Collection $collection,
    ) {}
}
$collection = collect([1, 2, 3]);
$resource = $collection->pipeInto(ResourceCollection::class);
$resource->collection->all();
// [1, 2, 3]

`pipeThrough()`

Метод pipeThrough передает коллекцию заданному массиву замыканий и возвращает результат выполненных замыканий:

use Illuminate\Support\Collection;
$collection = collect([1, 2, 3]);
$result = $collection->pipeThrough([
    function (Collection $collection) {
        return $collection->merge([4, 5]);
    },
    function (Collection $collection) {
        return $collection->sum();
    },
]);
// 15

`pluck()`

Метод pluck извлекает все значения для заданного ключа:

$collection = collect([
    ['product_id' => 'prod-100', 'name' => 'Desk'],
    ['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$plucked = $collection->pluck('name');
$plucked->all();
// ['Desk', 'Chair']

Вы также можете указать, как вы хотите, чтобы результирующая коллекция была проиндексирована:

$plucked = $collection->pluck('name', 'product_id');
$plucked->all();
// ['prod-100' => 'Desk', 'prod-200' => 'Chair']

Метод pluck также поддерживает извлечение вложенных значений с использованием нотации "точка":

$collection = collect([
    [
        'name' => 'Laracon',
        'speakers' => [
            'first_day' => ['Rosa', 'Judith'],
        ],
    ],
    [
        'name' => 'VueConf',
        'speakers' => [
            'first_day' => ['Abigail', 'Joey'],
        ],
    ],
]);
$plucked = $collection->pluck('speakers.first_day');
$plucked->all();
// [['Rosa', 'Judith'], ['Abigail', 'Joey']]

Если существуют дублирующиеся ключи, в коллекцию выбирается последний совпадающий элемент:

$collection = collect([
    ['brand' => 'Tesla',  'color' => 'red'],
    ['brand' => 'Pagani', 'color' => 'white'],
    ['brand' => 'Tesla',  'color' => 'black'],
    ['brand' => 'Pagani', 'color' => 'orange'],
]);
$plucked = $collection->pluck('color', 'brand');
$plucked->all();
// ['Tesla' => 'black', 'Pagani' => 'orange']

`pop()`

Метод pop удаляет и возвращает последний элемент из коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$collection->pop();
// 5
$collection->all();
// [1, 2, 3, 4]

Вы можете передать целое число методу pop, чтобы удалить и вернуть несколько элементов с конца коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$collection->pop(3);
// collect([5, 4, 3])
$collection->all();
// [1, 2]

`prepend()`

Метод prepend добавляет элемент в начало коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$collection->prepend(0);
$collection->all();
// [0, 1, 2, 3, 4, 5]

Вы также можете передать второй аргумент, чтобы указать ключ вставленного элемента:

$collection = collect(['one' => 1, 'two' => 2]);
$collection->prepend(0, 'zero');
$collection->all();
// ['zero' => 0, 'one' => 1, 'two' => 2]

`pull()`

Метод pull удаляет и возвращает элемент из коллекции по его ключу:

$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);
$collection->pull('name');
// 'Desk'
$collection->all();
// ['product_id' => 'prod-100']

`push()`

Метод push добавляет элемент в конец коллекции:

$collection = collect([1, 2, 3, 4]);
$collection->push(5);
$collection->all();
// [1, 2, 3, 4, 5]

`put()`

Метод put устанавливает заданный ключ и значение в коллекции:

$collection = collect(['product_id' => 1, 'name' => 'Desk']);
$collection->put('price', 100);
$collection->all();
// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]

`random()`

Метод random возвращает случайный элемент из коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$collection->random();
// 4 - (retrieved randomly)

Вы можете передать целое число методу random, чтобы указать, сколько элементов вы хотели бы случайным образом получить. Коллекция элементов всегда возвращается, если явно передано количество элементов, которое вы хотите получить:

$random = $collection->random(3);
$random->all();
// [2, 4, 5] - (retrieved randomly)

Если у экземпляра коллекции меньше элементов, чем запрошено, метод random выбросит исключение InvalidArgumentException.

Метод random также принимает замыкание, которое получит текущий экземпляр коллекции:

use Illuminate\Support\Collection;
$random = $collection->random(fn (Collection $items) => min(10, count($items)));
$random->all();
// [1, 2, 3, 4, 5] - (retrieved randomly)

`range()`

Метод range возвращает коллекцию, содержащую целые числа в указанном диапазоне:

$collection = collect()->range(3, 6);
$collection->all();
// [3, 4, 5, 6]

`reduce()`

Метод reduce сводит коллекцию к единственному значению, передавая результат каждой итерации в последующую:

$collection = collect([1, 2, 3]);
$total = $collection->reduce(function (?int $carry, int $item) {
    return $carry + $item;
});
// 6

Значение для $carry на первой итерации равно null; однако вы можете указать его начальное значение, передав второй аргумент методу reduce:

$collection->reduce(function (int $carry, int $item) {
    return $carry + $item;
}, 4);
// 10

Метод reduce также передает ключи массива в ассоциативных коллекциях заданному замыканию:

$collection = collect([
    'usd' => 1400,
    'gbp' => 1200,
    'eur' => 1000,
]);
$ratio = [
    'usd' => 1,
    'gbp' => 1.37,
    'eur' => 1.22,
];
$collection->reduce(function (int $carry, int $value, int $key) use ($ratio) {
    return $carry + ($value * $ratio[$key]);
});
// 4264

`reduceSpread()`

Метод reduceSpread сводит коллекцию к массиву значений, передавая результаты каждой итерации в последующую. Этот метод аналогичен методу reduce; однако он может принимать несколько начальных значений:

[$creditsRemaining, $batch] = Image::where('status', 'unprocessed')
    ->get()
    ->reduceSpread(function (int $creditsRemaining, Collection $batch, Image $image) {
        if ($creditsRemaining >= $image->creditsRequired()) {
            $batch->push($image);
            $creditsRemaining -= $image->creditsRequired();
        }
        return [$creditsRemaining, $batch];
    }, $creditsAvailable, collect());

`reject()`

Метод reject фильтрует коллекцию с использованием заданного замыкания. Замыкание должно возвращать true, если элемент должен быть удален из результирующей коллекции:

$collection = collect([1, 2, 3, 4]);
$filtered = $collection->reject(function (int $value, int $key) {
    return $value > 2;
});
$filtered->all();
// [1, 2]

Для обратной операции метода reject см. метод filter.

`replace()`

Метод replace ведет себя аналогично методу merge; однако, помимо перезаписи совпадающих элементов с ключами строками, метод replace также перезаписывает элементы в коллекции с совпадающими числовыми ключами:

$collection = collect(['Taylor', 'Abigail', 'James']);
$replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);
$replaced->all();
// ['Taylor', 'Victoria', 'James', 'Finn']

`replaceRecursive()`

Этот метод работает как replace, но рекурсивно обрабатывает массивы и применяет тот же процесс замены к внутренним значениям:

$collection = collect([
    'Taylor',
    'Abigail',
    [
        'James',
        'Victoria',
        'Finn'
    ]
]);
$replaced = $collection->replaceRecursive([
    'Charlie',
    2 => [1 => 'King']
]);
$replaced->all();
// ['Charlie', 'Abigail', ['James', 'King', 'Finn']]

`reverse()`

Метод reverse изменяет порядок элементов в коллекции, сохраняя исходные ключи:

$collection = collect(['a', 'b', 'c', 'd', 'e']);
$reversed = $collection->reverse();
$reversed->all();
/*
    [
        4 => 'e',
        3 => 'd',
        2 => 'c',
        1 => 'b',
        0 => 'a',
    ]
*/

`search()`

Метод search ищет в коллекции заданное значение и возвращает его ключ, если оно найдено. Если элемент не найден, возвращается false:

$collection = collect([2, 4, 6, 8]);
$collection->search(4);
// 1

Поиск выполняется с использованием "нестрогого" сравнения, что означает, что строка с целочисленным значением будет считаться равной целому числу с тем же значением. Чтобы использовать "строгое" сравнение, передайте true вторым аргументом методу:

collect([2, 4, 6, 8])->search('4', $strict = true);
// false

В качестве альтернативы вы можете предоставить свое собственное замыкание для поиска первого элемента, проходящего заданное условие истинности:

collect([2, 4, 6, 8])->search(function (int $item, int $key) {
    return $item > 5;
});
// 2

`shift()`

Метод shift удаляет и возвращает первый элемент из коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$collection->shift();
// 1
$collection->all();
// [2, 3, 4, 5]

Вы можете передать целое число методу shift, чтобы удалить и вернуть несколько элементов с начала коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$collection->shift(3);
// collect([1, 2, 3])
$collection->all();
// [4, 5]

`shuffle()`

Метод shuffle случайным образом перемешивает элементы в коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$shuffled = $collection->shuffle();
$shuffled->all();
// [3, 2, 5, 1, 4] - (generated randomly)

`skip()`

Метод skip возвращает новую коллекцию с указанным количеством элементов, удаленных с начала коллекции:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$collection = $collection->skip(4);
$collection->all();
// [5, 6, 7, 8, 9, 10]

`skipUntil()`

Метод skipUntil пропускает элементы из коллекции до тех пор, пока заданное замыкание не вернет true, и затем возвращает оставшиеся элементы в виде нового экземпляра коллекции:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->skipUntil(function (int $item) {
    return $item >= 3;
});
$subset->all();
// [3, 4]

Вы также можете передать простое значение методу skipUntil, чтобы пропустить все элементы до тех пор, пока не будет найдено заданное значение:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->skipUntil(3);
$subset->all();
// [3, 4]

Внимание Если заданное значение не найдено или обратный вызов никогда не возвращает true, метод skipUntil вернет пустую коллекцию.

`skipWhile()`

Метод skipWhile пропускает элементы из коллекции, пока заданное замыкание возвращает true, и затем возвращает оставшиеся элементы в виде новой коллекции:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->skipWhile(function (int $item) {
    return $item <= 3;
});
$subset->all();
// [4]

Внимание Если обратный вызов никогда не возвращает false, метод skipWhile вернет пустую коллекцию.

`slice()`

Метод slice возвращает срез коллекции, начиная с указанного индекса:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$slice = $collection->slice(4);
$slice->all();
// [5, 6, 7, 8, 9, 10]

Если вы хотите ограничить размер возвращаемого среза, передайте желаемый размер вторым аргументом методу:

$slice = $collection->slice(4, 2);
$slice->all();
// [5, 6]

Возвращенный срез будет по умолчанию сохранять ключи. Если вы не хотите сохранять исходные ключи, вы можете использовать метод values, чтобы заново проиндексировать их.

`sliding()`

Метод sliding возвращает новую коллекцию частей, представляющих собой "скользящее окно" элементов в коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$chunks = $collection->sliding(2);
$chunks->toArray();
// [[1, 2], [2, 3], [3, 4], [4, 5]]

Это особенно полезно в сочетании с методом eachSpread:

$transactions->sliding(2)->eachSpread(function (Collection $previous, Collection $current) {
    $current->total = $previous->total + $current->amount;
});

По желанию вы можете передать второе значение "шаг", которое определяет расстояние между первым элементом каждого блока:

$collection = collect([1, 2, 3, 4, 5]);
$chunks = $collection->sliding(3, step: 2);
$chunks->toArray();
// [[1, 2, 3], [3, 4, 5]]

`sole()`

Метод sole возвращает первый элемент в коллекции, который проходит заданное условие истинности, но только в том случае, если условие истинности соответствует ровно одному элементу:

collect([1, 2, 3, 4])->sole(function (int $value, int $key) {
    return $value === 2;
});
// 2

Вы также можете передать пару ключ / значение методу sole, который вернет первый элемент в коллекции, соответствующий заданной паре, но только если ровно один элемент соответствует:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
]);
$collection->sole('product', 'Chair');
// ['product' => 'Chair', 'price' => 100]

В качестве альтернативы вы также можете вызвать метод sole без аргументов, чтобы получить первый элемент в коллекции, если он единственный:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
]);
$collection->sole();
// ['product' => 'Desk', 'price' => 200]

Если в коллекции нет элементов, которые должны быть возвращены методом sole, будет вызвано исключение \Illuminate\Collections\ItemNotFoundException. Если элементов, которые должны быть возвращены, более одного, будет вызвано исключение \Illuminate\Collections\MultipleItemsFoundException.

`some()`

Псевдоним для метода contains.

`sort()`

Метод sort сортирует коллекцию. Отсортированная коллекция сохраняет исходные ключи массива, поэтому в следующем примере мы используем метод values для сброса ключей на последовательные номера индексов:

$collection = collect([5, 3, 1, 2, 4]);
$sorted = $collection->sort();
$sorted->values()->all();
// [1, 2, 3, 4, 5]

Если ваши потребности в сортировке более сложные, вы можете передать замыкание в sort с вашим собственным алгоритмом. Обратитесь к документации PHP по uasort, которую использует внутренне метод sort коллекции.

Примечание Если вам нужно отсортировать коллекцию вложенных массивов или объектов, обратитесь к методам sortBy и sortByDesc.

`sortBy()`

Метод sortBy сортирует коллекцию по заданному ключу. Отсортированная коллекция сохраняет исходные ключи массива, поэтому в следующем примере мы используем метод values для сброса ключей на последовательные номера индексов:

$collection = collect([
    ['name' => 'Desk', 'price' => 200],
    ['name' => 'Chair', 'price' => 100],
    ['name' => 'Bookcase', 'price' => 150],
]);
$sorted = $collection->sortBy('price');
$sorted->values()->all();
/*
    [
        ['name' => 'Chair', 'price' => 100],
        ['name' => 'Bookcase', 'price' => 150],
        ['name' => 'Desk', 'price' => 200],
    ]
*/

Метод sortBy принимает флаги сортировки в качестве второго аргумента:

$collection = collect([
    ['title' => 'Item 1'],
    ['title' => 'Item 12'],
    ['title' => 'Item 3'],
]);
$sorted = $collection->sortBy('title', SORT_NATURAL);
$sorted->values()->all();
/*
    [
        ['title' => 'Item 1'],
        ['title' => 'Item 3'],
        ['title' => 'Item 12'],
    ]
*/

В качестве альтернативы вы можете передать собственное замыкание для определения порядка сортировки значений коллекции:

$collection = collect([
    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
    ['name' => 'Chair', 'colors' => ['Black']],
    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);
$sorted = $collection->sortBy(function (array $product, int $key) {
    return count($product['colors']);
});
$sorted->values()->all();
/*
    [
        ['name' => 'Chair', 'colors' => ['Black']],
        ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
        ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
    ]
*/

Если вы хотите отсортировать коллекцию по нескольким атрибутам, вы можете передать массив операций сортировки методу sortBy. Каждая операция сортировки должна быть массивом, содержащим атрибут, по которому вы хотите выполнить сортировку, и направление желаемой сортировки:

$collection = collect([
    ['name' => 'Taylor Otwell', 'age' => 34],
    ['name' => 'Abigail Otwell', 'age' => 30],
    ['name' => 'Taylor Otwell', 'age' => 36],
    ['name' => 'Abigail Otwell', 'age' => 32],
]);
$sorted = $collection->sortBy([
    ['name', 'asc'],
    ['age', 'desc'],
]);
$sorted->values()->all();
/*
    [
        ['name' => 'Abigail Otwell', 'age' => 32],
        ['name' => 'Abigail Otwell', 'age' => 30],
        ['name' => 'Taylor Otwell', 'age' => 36],
        ['name' => 'Taylor Otwell', 'age' => 34],
    ]
*/

При сортировке коллекции по нескольким атрибутам вы также можете предоставить замыкания, определяющие каждую операцию сортировки:

$collection = collect([
    ['name' => 'Taylor Otwell', 'age' => 34],
    ['name' => 'Abigail Otwell', 'age' => 30],
    ['name' => 'Taylor Otwell', 'age' => 36],
    ['name' => 'Abigail Otwell', 'age' => 32],
]);
$sorted = $collection->sortBy([
    fn (array $a, array $b) => $a['name'] <=> $b['name'],
    fn (array $a, array $b) => $b['age'] <=> $a['age'],
]);
$sorted->values()->all();
/*
    [
        ['name' => 'Abigail Otwell', 'age' => 32],
        ['name' => 'Abigail Otwell', 'age' => 30],
        ['name' => 'Taylor Otwell', 'age' => 36],
        ['name' => 'Taylor Otwell', 'age' => 34],
    ]
*/

`sortByDesc()`

Этот метод имеет ту же сигнатуру, что и метод sortBy, но сортирует коллекцию в обратном порядке.

`sortDesc()`

Этот метод сортирует коллекцию в обратном порядке по сравнению с методом sort:

$collection = collect([5, 3, 1, 2, 4]);
$sorted = $collection->sortDesc();
$sorted->values()->all();
// [5, 4, 3, 2, 1]

В отличие от sort, вы не можете передать замыкание в sortDesc. Вместо этого используйте метод sort и инвертируйте ваше сравнение.

`sortKeys()`

Метод sortKeys сортирует коллекцию по ключам базового ассоциативного массива:

$collection = collect([
    'id' => 22345,
    'first' => 'John',
    'last' => 'Doe',
]);
$sorted = $collection->sortKeys();
$sorted->all();
/*
    [
        'first' => 'John',
        'id' => 22345,
        'last' => 'Doe',
    ]
*/

`sortKeysDesc()`

Этот метод имеет ту же сигнатуру, что и метод sortKeys, но сортирует коллекцию в обратном порядке.

`sortKeysUsing()`

Метод sortKeysUsing сортирует коллекцию по ключам базового ассоциативного массива с использованием замыкания:

$collection = collect([
    'ID' => 22345,
    'first' => 'John',
    'last' => 'Doe',
]);
$sorted = $collection->sortKeysUsing('strnatcasecmp');
$sorted->all();
/*
    [
        'first' => 'John',
        'ID' => 22345,
        'last' => 'Doe',
    ]
*/

Замыкание должно быть функцией сравнения, которая возвращает целое число меньше, равное или больше нуля. Дополнительную информацию смотрите в документации PHP по uksort, которую использует метод sortKeysUsing внутренне.

`splice()`

Метод splice удаляет и возвращает срез элементов, начиная с указанного индекса:

$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2);
$chunk->all();
// [3, 4, 5]
$collection->all();
// [1, 2]

Вы можете передать второй аргумент, чтобы ограничить размер результирующей коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1);
$chunk->all();
// [3]
$collection->all();
// [1, 2, 4, 5]

Кроме того, вы можете передать третий аргумент, содержащий новые элементы для замены удаленных элементов из коллекции:

$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1, [10, 11]);
$chunk->all();
// [3]
$collection->all();
// [1, 2, 10, 11, 4, 5]

`split()`

Метод split разбивает коллекцию на указанное количество групп:

$collection = collect([1, 2, 3, 4, 5]);
$groups = $collection->split(3);
$groups->all();
// [[1, 2], [3, 4], [5]]

`splitIn()`

Метод splitIn разбивает коллекцию на указанное количество групп, заполняя полностью непоследние группы, прежде чем выделять оставшуюся часть последней группе:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$groups = $collection->splitIn(3);
$groups->all();
// [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]

`sum()`

Метод sum возвращает сумму всех элементов в коллекции:

collect([1, 2, 3, 4, 5])->sum();
// 15

Если коллекция содержит вложенные массивы или объекты, вы должны передать ключ, который будет использоваться для определения значений для суммирования:

$collection = collect([
    ['name' => 'JavaScript: The Good Parts', 'pages' => 176],
    ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);
$collection->sum('pages');
// 1272

Кроме того, вы можете передать свое собственное замыкание, чтобы определить, какие значения коллекции суммировать:

$collection = collect([
    ['name' => 'Chair', 'colors' => ['Black']],
    ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
    ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);
$collection->sum(function (array $product) {
    return count($product['colors']);
});
// 6

`take()`

Метод take возвращает новую коллекцию с указанным количеством элементов:

$collection = collect([0, 1, 2, 3, 4, 5]);
$chunk = $collection->take(3);
$chunk->all();
// [0, 1, 2]

Вы также можете передать отрицательное целое число, чтобы взять указанное количество элементов с конца коллекции:

$collection = collect([0, 1, 2, 3, 4, 5]);
$chunk = $collection->take(-2);
$chunk->all();
// [4, 5]

`takeUntil()`

Метод takeUntil возвращает элементы в коллекции до тех пор, пока заданное замыкание не вернет true:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->takeUntil(function (int $item) {
    return $item >= 3;
});
$subset->all();
// [1, 2]

Вы также можете передать простое значение методу takeUntil, чтобы получить элементы до тех пор, пока не будет найдено указанное значение:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->takeUntil(3);
$subset->all();
// [1, 2]

Внимание Если заданное значение не найдено или обратный вызов никогда не возвращает true, метод takeUntil вернет все элементы в коллекции.

`takeWhile()`

Метод takeWhile возвращает элементы в коллекции до тех пор, пока заданное замыкание не вернет false:

$collection = collect([1, 2, 3, 4]);
$subset = $collection->takeWhile(function (int $item) {
    return $item < 3;
});
$subset->all();
// [1, 2]

Внимание Если обратный вызов никогда не возвращает false, метод takeWhile вернет все элементы в коллекции.

`tap()`

Метод tap передает коллекцию заданному замыканию, позволяя вам "подсоединиться" к коллекции в конкретной точке и сделать что-то с элементами, не затрагивая саму коллекцию. Затем метод tap возвращает коллекцию:

collect([2, 4, 3, 1, 5])
    ->sort()
    ->tap(function (Collection $collection) {
        Log::debug('Values after sorting', $collection->values()->all());
    })
    ->shift();
// 1

`times()`

Статический метод times создает новую коллекцию, вызывая заданное замыкание указанное количество раз:

$collection = Collection::times(10, function (int $number) {
    return $number * 9;
});
$collection->all();
// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]

`toArray()`

Метод toArray преобразует коллекцию в обычный массив PHP. Если значения в коллекции - это модели Eloquent, модели также будут преобразованы в массивы:

$collection = collect(['name' => 'Desk', 'price' => 200]);
$collection->toArray();
/*
    [
        ['name' => 'Desk', 'price' => 200],
    ]
*/

Внимание toArray также преобразует все вложенные объекты коллекции, являющиеся экземплярами Arrayable, в массив. Если вы хотите получить сырой массив, лежащий в основе коллекции, используйте метод all.

`toJson()`

Метод toJson преобразует коллекцию в сериализованную строку JSON:

$collection = collect(['name' => 'Desk', 'price' => 200]);
$collection->toJson();
// '{"name":"Desk", "price":200}'

`transform()`

Метод transform проходит по коллекции и вызывает заданное замыкание для каждого элемента в коллекции. Элементы в коллекции будут заменены значениями, возвращаемыми замыканием:

$collection = collect([1, 2, 3, 4, 5]);
$collection->transform(function (int $item, int $key) {
    return $item * 2;
});
$collection->all();
// [2, 4, 6, 8, 10]

Внимание В отличие от большинства других методов коллекций, transform изменяет саму коллекцию. Если вы хотите создать новую коллекцию, используйте метод map.

`undot()`

Метод undot преобразует одномерную коллекцию, использующую нотацию "точка", в многомерную коллекцию:

$person = collect([
    'name.first_name' => 'Marie',
    'name.last_name' => 'Valentine',
    'address.line_1' => '2992 Eagle Drive',
    'address.line_2' => '',
    'address.suburb' => 'Detroit',
    'address.state' => 'MI',
    'address.postcode' => '48219'
]);
$person = $person->undot();
$person->toArray();
/*
    [
        "name" => [
            "first_name" => "Marie",
            "last_name" => "Valentine",
        ],
        "address" => [
            "line_1" => "2992 Eagle Drive",
            "line_2" => "",
            "suburb" => "Detroit",
            "state" => "MI",
            "postcode" => "48219",
        ],
    ]
*/

`union()`

Метод union добавляет указанный массив к коллекции. Если в указанном массиве есть ключи, которые уже есть в исходной коллекции, предпочтение отдается значениям исходной коллекции:

$collection = collect([1 => ['a'], 2 => ['b']]);
$union = $collection->union([3 => ['c'], 1 => ['d']]);
$union->all();
// [1 => ['a'], 2 => ['b'], 3 => ['c']]

`unique()`

Метод unique возвращает все уникальные элементы в коллекции. Возвращенная коллекция сохраняет исходные ключи массива, поэтому в следующем примере мы используем метод values для сброса ключей на последовательные номера индексов:

$collection = collect([1, 1, 2, 2, 3, 4, 2]);
$unique = $collection->unique();
$unique->values()->all();
// [1, 2, 3, 4]

При работе с вложенными массивами или объектами вы можете указать ключ, используемый для определения уникальности:

$collection = collect([
    ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
    ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
    ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
    ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
    ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
]);
$unique = $collection->unique('brand');
$unique->values()->all();
/*
    [
        ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
        ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
    ]
*/

Наконец, вы также можете передать свое собственное замыкание методу unique, чтобы указать, какое значение должно определять уникальность элемента:

$unique = $collection->unique(function (array $item) {
    return $item['brand'].$item['type'];
});
$unique->values()->all();
/*
    [
        ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
        ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
        ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
        ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
    ]
*/

Метод unique использует "нелепые" сравнения при проверке значений элементов, что означает, что строка с целочисленным значением будет считаться равной целому числу с тем же значением. Используйте метод uniqueStrict, чтобы фильтровать с использованием "строгих" сравнений.

Примечание Поведение этого метода изменяется при использовании Eloquent Collections.

`uniqueStrict()`

Этот метод имеет тот же формат, что и метод unique; однако все значения сравниваются с использованием "строгих" сравнений.

`unless()`

Метод unless выполнит заданное замыкание, если первый аргумент, переданный методу, оценивается как true:

$collection = collect([1, 2, 3]);
$collection->unless(true, function (Collection $collection) {
    return $collection->push(4);
});
$collection->unless(false, function (Collection $collection) {
    return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 5]

Второе замыкание может быть передано методу unless. Второе замыкание будет выполнено, когда первый аргумент, переданный методу unless, оценивается как true:

$collection = collect([1, 2, 3]);
$collection->unless(true, function (Collection $collection) {
    return $collection->push(4);
}, function (Collection $collection) {
    return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 5]

Для обратного действия метода unless смотрите метод when.

`unlessEmpty()`

Псевдоним для метода whenNotEmpty.

`unlessNotEmpty()`

Псевдоним для метода whenEmpty.

`unwrap()`

Статический метод unwrap возвращает базовые элементы коллекции из заданного значения, когда это применимо:

Collection::unwrap(collect('John Doe'));
// ['John Doe']
Collection::unwrap(['John Doe']);
// ['John Doe']
Collection::unwrap('John Doe');
// 'John Doe'

`value()`

Метод value извлекает заданное значение из первого элемента коллекции:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Speaker', 'price' => 400],
]);
$value = $collection->value('price');
// 200

`values()`

Метод values возвращает новую коллекцию с ключами, сброшенными на последовательные целые числа:

$collection = collect([
    10 => ['product' => 'Desk', 'price' => 200],
    11 => ['product' => 'Desk', 'price' => 200],
]);
$values = $collection->values();
$values->all();
/*
    [
        0 => ['product' => 'Desk', 'price' => 200],
        1 => ['product' => 'Desk', 'price' => 200],
    ]
*/

`when()`

Метод when выполнит заданное замыкание, когда первый аргумент, переданный методу, оценивается как true. Экземпляр коллекции и первый аргумент, переданный методу when, будут предоставлены замыканию:

$collection = collect([1, 2, 3]);
$collection->when(true, function (Collection $collection, int $value) {
    return $collection->push(4);
});
$collection->when(false, function (Collection $collection, int $value) {
    return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 4]

Второе замыкание может быть передано методу when. Второе замыкание будет выполнено, когда первый аргумент, переданный методу when, оценивается как false:

$collection = collect([1, 2, 3]);
$collection->when(false, function (Collection $collection, int $value) {
    return $collection->push(4);
}, function (Collection $collection) {
    return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 5]

Для обратного действия метода when смотрите метод unless.

`whenEmpty()`

Метод whenEmpty выполнит заданное замыкание, когда коллекция пуста:

$collection = collect(['Michael', 'Tom']);
$collection->whenEmpty(function (Collection $collection) {
    return $collection->push('Adam');
});
$collection->all();
// ['Michael', 'Tom']
$collection = collect();
$collection->whenEmpty(function (Collection $collection) {
    return $collection->push('Adam');
});
$collection->all();
// ['Adam']

Второе замыкание может быть передано методу whenEmpty и будет выполнено, когда коллекция не пуста:

$collection = collect(['Michael', 'Tom']);
$collection->whenEmpty(function (Collection $collection) {
    return $collection->push('Adam');
}, function (Collection $collection) {
    return $collection->push('Taylor');
});
$collection->all();
// ['Michael', 'Tom', 'Taylor']

Для обратного действия метода whenEmpty смотрите метод whenNotEmpty.

`whenNotEmpty()`

Метод whenNotEmpty выполнит заданное замыкание, когда коллекция не пуста:

$collection = collect(['michael', 'tom']);
$collection->whenNotEmpty(function (Collection $collection) {
    return $collection->push('adam');
});
$collection->all();
// ['michael', 'tom', 'adam']
$collection = collect();
$collection->whenNotEmpty(function (Collection $collection) {
    return $collection->push('adam');
});
$collection->all();
// []

Второе замыкание может быть передано методу whenNotEmpty и будет выполнено, когда коллекция пуста:

$collection = collect();
$collection->whenNotEmpty(function (Collection $collection) {
    return $collection->push('adam');
}, function (Collection $collection) {
    return $collection->push('taylor');
});
$collection->all();
// ['taylor']

Для обратного действия метода whenNotEmpty смотрите метод whenEmpty.

`where()`

Метод where фильтрует коллекцию по заданной паре ключ / значение:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
    ['product' => 'Bookcase', 'price' => 150],
    ['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->where('price', 100);
$filtered->all();
/*
    [
        ['product' => 'Chair', 'price' => 100],
        ['product' => 'Door', 'price' => 100],
    ]
*/

Метод where использует "нелепые" сравнения при проверке значений элементов, что означает, что строка с целочисленным значением будет считаться равной целому числу с тем же значением. Используйте метод whereStrict, чтобы фильтровать с использованием "строгих" сравнений.

При необходимости вы можете передать оператор сравнения в качестве второго параметра. Поддерживаемые операторы: '===', '!==', '!=', '==', '=', '<>', '>', '<', '>=', и '<=':

$collection = collect([
    ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
    ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
    ['name' => 'Sue', 'deleted_at' => null],
]);
$filtered = $collection->where('deleted_at', '!=', null);
$filtered->all();
/*
    [
        ['name' => 'Jim', 'deleted_at' => '2019-01-01 00:00:00'],
        ['name' => 'Sally', 'deleted_at' => '2019-01-02 00:00:00'],
    ]
*/

`whereStrict()`

Этот метод имеет тот же формат, что и метод where; однако все значения сравниваются с использованием "строгих" сравнений.

`whereBetween()`

Метод whereBetween фильтрует коллекцию, определяя, находится ли указанное значение элемента в заданном диапазоне:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 80],
    ['product' => 'Bookcase', 'price' => 150],
    ['product' => 'Pencil', 'price' => 30],
    ['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereBetween('price', [100, 200]);
$filtered->all();
/*
    [
        ['product' => 'Desk', 'price' => 200],
        ['product' => 'Bookcase', 'price' => 150],
        ['product' => 'Door', 'price' => 100],
    ]
*/

`whereIn()`

Метод whereIn удаляет элементы из коллекции, у которых нет указанного значения элемента, содержащегося в заданном массиве:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
    ['product' => 'Bookcase', 'price' => 150],
    ['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereIn('price', [150, 200]);
$filtered->all();
/*
    [
        ['product' => 'Desk', 'price' => 200],
        ['product' => 'Bookcase', 'price' => 150],
    ]
*/

Метод whereIn использует "нелепые" сравнения при проверке значений элементов, что означает, что строка с целочисленным значением будет считаться равной целому числу с тем же значением. Используйте метод whereInStrict, чтобы фильтровать с использованием "строгих" сравнений.

`whereInStrict()`

Этот метод имеет тот же формат, что и метод whereIn; однако все значения сравниваются с использованием "строгих" сравнений.

`whereInstanceOf()`

Метод whereInstanceOf фильтрует коллекцию по заданному типу класса:

use App\Models\User;
use App\Models\Post;
$collection = collect([
    new User,
    new User,
    new Post,
]);
$filtered = $collection->whereInstanceOf(User::class);
$filtered->all();
// [App\Models\User, App\Models\User]

`whereNotBetween()`

Метод whereNotBetween фильтрует коллекцию, определяя, находится ли указанное значение элемента вне заданного диапазона:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 80],
    ['product' => 'Bookcase', 'price' => 150],
    ['product' => 'Pencil', 'price' => 30],
    ['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereNotBetween('price', [100, 200]);
$filtered->all();
/*
    [
        ['product' => 'Chair', 'price' => 80],
        ['product' => 'Pencil', 'price' => 30],
    ]
*/

`whereNotIn()`

Метод whereNotIn удаляет элементы из коллекции, у которых указанное значение элемента, содержится в заданном массиве:

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
    ['product' => 'Bookcase', 'price' => 150],
    ['product' => 'Door', 'price' => 100],
]);
$filtered = $collection->whereNotIn('price', [150, 200]);
$filtered->all();
/*
    [
        ['product' => 'Chair', 'price' => 100],
        ['product' => 'Door', 'price' => 100],
    ]
*/

Метод whereNotIn использует "нелепые" сравнения при проверке значений элементов, что означает, что строка с целочисленным значением будет считаться равной целому числу с тем же значением. Используйте метод whereNotInStrict, чтобы фильтровать с использованием "строгих" сравнений.

`whereNotInStrict()`

Этот метод имеет тот же формат, что и метод whereNotIn; однако все значения сравниваются с использованием "строгих" сравнений.

`whereNotNull()`

Метод whereNotNull возвращает элементы из коллекции, где указанный ключ не равен null:

$collection = collect([
    ['name' => 'Desk'],
    ['name' => null],
    ['name' => 'Bookcase'],
]);
$filtered = $collection->whereNotNull('name');
$filtered->all();
/*
    [
        ['name' => 'Desk'],
        ['name' => 'Bookcase'],
    ]
*/

`whereNull()`

Метод whereNull возвращает элементы из коллекции, где указанный ключ равен null:

$collection = collect([
    ['name' => 'Desk'],
    ['name' => null],
    ['name' => 'Bookcase'],
]);
$filtered = $collection->whereNull('name');
$filtered->all();
/*
    [
        ['name' => null],
    ]
*/

`wrap()`

Статический метод wrap оборачивает заданное значение в коллекцию, когда это применимо:

use Illuminate\Support\Collection;
$collection = Collection::wrap('John Doe');
$collection->all();
// ['John Doe']
$collection = Collection::wrap(['John Doe']);
$collection->all();
// ['John Doe']
$collection = Collection::wrap(collect('John Doe'));
$collection->all();
// ['John Doe']

`zip()`

Метод zip объединяет значения заданного массива со значениями исходной коллекции по соответствующему индексу:

$collection = collect(['Chair', 'Desk']);
$zipped = $collection->zip([100, 200]);
$zipped->all();
// [['Chair', 100], ['Desk', 200]]

Сообщения Более Высокого Порядка

Коллекции также поддерживают "высокоуровневые сообщения", которые представляют собой ярлыки для выполнения общих действий с коллекциями. Методы коллекций, предоставляющие высокоуровневые сообщения, включают: average, avg, contains, each, every, filter, first, flatMap, groupBy, keyBy, map, max, min, partition, reject, skipUntil, skipWhile, some, sortBy, sortByDesc, sum, takeUntil, takeWhile, и unique.

Каждое высокоуровневое сообщение можно использовать как динамическое свойство экземпляра коллекции. Например, давайте используем высокоуровневое сообщение each, чтобы вызвать метод для каждого объекта в коллекции:

use App\Models\User;
$users = User::where('votes', '>', 500)->get();
$users->each->markAsVip();

Точно так же мы можем использовать высокоуровневое сообщение sum для подсчета общего числа "голосов" для коллекции пользователей:

$users = User::where('group', 'Development')->get();
return $users->sum->votes;

Ленивые Коллекции

Введение

Внимание Прежде чем узнать больше о ленивых коллекциях Laravel, потратите некоторое время на ознакомление с генераторами PHP.

Для дополнения уже мощного класса Collection класс LazyCollection использует генераторы PHP, позволяя вам работать с очень большими наборами данных, при этом поддерживая низкое использование памяти.

Например, представьте, что ваше приложение должно обрабатывать многогигабайтный файл журнала с использованием методов коллекции Laravel для анализа журналов. Вместо чтения всего файла в память сразу, ленивые коллекции можно использовать для хранения в памяти только небольшой части файла в определенный момент времени:

use App\Models\LogEntry;
use Illuminate\Support\LazyCollection;
LazyCollection::make(function () {
    $handle = fopen('log.txt', 'r');
    while (($line = fgets($handle)) !== false) {
        yield $line;
    }
})->chunk(4)->map(function (array $lines) {
    return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
    // Обработка записи в журнал...
});

Или представьте, что вам нужно пройти через 10 000 моделей Eloquent. При использовании традиционных коллекций Laravel все 10 000 моделей Eloquent должны быть загружены в память одновременно:

use App\Models\User;
$users = User::all()->filter(function (User $user) {
    return $user->id > 500;
});

Однако метод cursor построителя запросов возвращает экземпляр LazyCollection. Это позволяет вам все равно выполнить только один запрос к базе данных, но также хранить в памяти всего одну модель Eloquent за один раз. В этом примере обратный вызов filter не выполняется, пока мы фактически не перебираем каждого пользователя по отдельности, что позволяет существенно снизить использование памяти:

use App\Models\User;
$users = User::cursor()->filter(function (User $user) {
    return $user->id > 500;
});
foreach ($users as $user) {
    echo $user->id;
}

Создание Ленивых Коллекций

Для создания экземпляра ленивой коллекции следует передать функцию генератора PHP методу make коллекции:

use Illuminate\Support\LazyCollection;
LazyCollection::make(function () {
    $handle = fopen('log.txt', 'r');
    while (($line = fgets($handle)) !== false) {
        yield $line;
    }
});

Контракт Enumerable

Почти все методы, доступные в классе Collection, также доступны в классе LazyCollection. Оба этих класса реализуют контракт Illuminate\Support\Enumerable, который определяет следующие методы:

all average avg chunk chunkWhile collapse collect combine concat contains containsStrict count countBy crossJoin dd diff diffAssoc diffKeys dump duplicates duplicatesStrict each eachSpread every except filter first firstOrFail firstWhere flatMap flatten flip forPage get groupBy has implode intersect intersectAssoc intersectByKeys isEmpty isNotEmpty join keyBy keys last macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition pipe pluck random reduce reject replace replaceRecursive reverse search shuffle skip slice sole some sort sortBy sortByDesc sortKeys sortKeysDesc split sum take tap times toArray toJson union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict wrap zip

Внимание Методы, изменяющие коллекцию (такие как shift, pop, prepend и т. д.), не доступны в классе LazyCollection.

Методы Ленивых Коллекций

Помимо методов, определенных в контракте Enumerable, класс LazyCollection содержит следующие методы:

`takeUntilTimeout()`

Метод takeUntilTimeout возвращает новую ленивую коллекцию, которая будет перечислять значения до указанного времени. После этого времени коллекция прекратит перечисление:

$lazyCollection = LazyCollection::times(INF)
    ->takeUntilTimeout(now()->addMinute());
$lazyCollection->each(function (int $number) {
    dump($number);
    sleep(1);
});
// 1
// 2
// ...
// 58
// 59

Чтобы проиллюстрировать использование этого метода, представьте себе приложение, которое отправляет счета из базы данных с использованием курсора. Вы можете определить задачу по расписанию, которая запускается каждые 15 минут и обрабатывает только счета в течение максимум 14 минут:

use App\Models\Invoice;
use Illuminate\Support\Carbon;
Invoice::pending()->cursor()
    ->takeUntilTimeout(
        Carbon::createFromTimestamp(LARAVEL_START)->add(14, 'minutes')
    )
    ->each(fn (Invoice $invoice) => $invoice->submit());

`tapEach()`

В то время как метод each вызывает заданный обратный вызов для каждого элемента коллекции немедленно, метод tapEach вызывает заданный обратный вызов только тогда, когда элементы извлекаются из списка по одному:

// Пока ничего не было выведено...
$lazyCollection = LazyCollection::times(INF)->tapEach(function (int $value) {
    dump($value);
});
// Выведены три элемента...
$array = $lazyCollection->take(3)->all();
// 1
// 2
// 3

`remember()`

Метод remember возвращает новую ленивую коллекцию, которая будет запоминать любые значения, которые уже были перечислены, и не будет извлекать их снова при последующих перечислениях коллекции:

// Запрос пока не был выполнен...
$users = User::cursor()->remember();
// Запрос выполняется...
// Первые 5 пользователей извлекаются из базы данных...
$users->take(5)->all();
// Первые 5 пользователей извлекаются из кеша коллекции...
// Остальные извлекаются из базы данных...
$users->take(20)->all();