Документация Laravel 10.x
Здесь ты найдешь сниппеты по 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
, чтобы подсчитать все элементы по пользовательскому значению:
$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([]); $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 () {});
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', ], [ 'name' => 'Jane', 'department' => 'Marketing', ]]); $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; }});
Почти все методы, доступные в классе 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();