Колекції
Вступ
Клас 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]);Ви також можете створити колекцію, використовуючи методи make та fromJson.
Результати запитів Eloquent завжди повертаються як екземпляри Collection.
Розширення Колекцій
Колекції є "macroable", що дозволяє додавати додаткові методи до класу 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, що дозволяє зберегти оригінальну копію колекції, коли це необхідно:
after all average avg before chunk chunkWhile collapse collapseWithKeys 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 fromJson get groupBy has hasAny implode intersect intersectUsing intersectAssoc intersectAssocUsing intersectByKeys isEmpty isNotEmpty join keyBy keys last lazy macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode multiply nth only pad partition percentage pipe pipeInto pipeThrough pluck pop prepend pull push put random range reduce reduceSpread reject replace replaceRecursive reverse search select 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
Список Методів
after()
Метод after повертає елемент після заданого елемента. null повертається, якщо заданий елемент не знайдено або він є останнім елементом:
$collection = collect([1, 2, 3, 4, 5]);
$collection->after(3);
// 4
$collection->after(5);
// nullЦей метод шукає заданий елемент, використовуючи "нестроге" порівняння, тобто рядок, що містить ціле число, буде вважатися рівним цілому числу з тим самим значенням. Щоб використовувати "строге" порівняння, ви можете надати аргумент strict методу:
collect([2, 4, 6, 8])->after('4', strict: true);
// nullКрім того, ви можете надати власне замикання для пошуку першого елемента, який проходить заданий тест на істинність:
collect([2, 4, 6, 8])->after(function (int $item, int $key) {
return $item > 5;
});
// 8all()
Метод 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();
// 2before()
Метод before є протилежністю методу after. Він повертає елемент перед заданим елементом. Повертається null, якщо заданий елемент не знайдено або він є першим елементом:
$collection = collect([1, 2, 3, 4, 5]);
$collection->before(3);
// 2
$collection->before(1);
// null
collect([2, 4, 6, 8])->before('4', strict: true);
// null
collect([2, 4, 6, 8])->before(function (int $item, int $key) {
return $item > 5;
});
// 4chunk()
Метод 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>
@endforeachchunkWhile()
Метод 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]collapseWithKeys()
Метод collapseWithKeys сплющує колекцію масивів або колекцій в одну колекцію, зберігаючи оригінальні ключі. Якщо колекція вже є сплющеною, вона поверне порожню колекцію:
$collection = collect([
['first' => collect([1, 2, 3])],
['second' => [4, 5, 6]],
['third' => collect([7, 8, 9])]
]);
$collapsed = $collection->collapseWithKeys();
$collapsed->all();
// [
// 'first' => [1, 2, 3],
// 'second' => [4, 5, 6],
// 'third' => [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 додає значення переданого масиву або колекції до кінця іншої колекції:
$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
collect([1, 2, 3])->containsOneItem(fn (int $item) => $item === 2);
// truecontainsStrict()
Цей метод має такий самий підпис, як метод contains; однак, всі значення порівнюються за допомогою "строгих" порівнянь.
Ця поведінка методу змінюється при використанні Eloquent Collections.
count()
Метод count повертає загальну кількість елементів у колекції:
$collection = collect([1, 2, 3, 4]);
$collection->count();
// 4countBy()
Метод countBy рахує кількість появ значень у колекції. За замовчуванням метод рахує кількість появ кожного елемента, дозволяючи вам підраховувати певні "типи" елементів у колекції:
$collection = collect([1, 2, 2, 2, 3]);
$counted = $collection->countBy();
$counted->all();
// [1 => 1, 2 => 3, 3 => 1]Ви можете передати замикання до методу countBy, щоб підрахувати всі елементи за власним значенням:
$collection = collect(['example@example.com', 'example@example.com', 'example@example.com']);
$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();
/*
array:2 [
0 => "John Doe"
1 => "Jane Doe"
]
*/Якщо ви не хочете зупиняти виконання скрипта, використовуйте метод dump замість цього.
diff()
Метод diff порівнює колекцію з іншою колекцією або звичайним PHP array на основі її значень. Цей метод поверне значення з оригінальної колекції, які відсутні в заданій колекції:
$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();
// [1, 3, 5]Ця поведінка методу змінюється при використанні Eloquent Collections.
diffAssoc()
Метод diffAssoc порівнює колекцію з іншою колекцією або звичайним PHP array на основі її ключів і значень. Цей метод поверне пари ключ / значення в оригінальній колекції, які відсутні в заданій колекції:
$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 array на основі її ключів. Цей метод поверне пари ключ / значення в оригінальній колекції, які відсутні в заданій колекції:
$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();
/*
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' => 'example@example.com', 'position' => 'Developer'],
['email' => 'example@example.com', 'position' => 'Designer'],
['email' => 'example@example.com', '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 (/* умови */) { 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);
return $collection->ensure([User::class, Customer::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;
});
// trueexcept()
Метод 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();
// 1firstOrFail()
Метод 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(); // Генерує виняток 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'); // ['framework' => 'Laravel'] // Забути кілька ключів... $collection->forget(['name', 'framework']); // []
На відміну від більшості інших методів колекції, forget не повертає нову змінену колекцію; він змінює і повертає колекцію, на якій був викликаний.
forPage()
Метод forPage повертає нову колекцію, що містить елементи, які будуть присутні на заданому номері сторінки. Метод приймає номер сторінки як свій перший аргумент і кількість елементів для показу на сторінці як свій другий аргумент:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunk = $collection->forPage(2, 3);
$chunk->all();
// [4, 5, 6]fromJson()
Статичний метод fromJson створює новий екземпляр колекції шляхом декодування заданого JSON рядка за допомогою PHP функції json_decode:
use Illuminate\Support\Collection;
$json = json_encode([
'name' => 'Taylor Otwell',
'role' => 'Developer',
'status' => 'Active',
]);
$collection = Collection::fromJson($json);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 'example@example.com';
});
// example@example.comgroupBy()
Метод 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']);
// falsehasAny()
Метод hasAny визначає, чи існує будь-який з вказаних ключів у колекції:
$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);
$collection->hasAny(['product', 'price']);
// true
$collection->hasAny(['name', 'price']);
// falseimplode()
Метод 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 видаляє будь-які значення з оригінальної колекції, які не присутні в заданому масиві або колекції. Отримана колекція збереже ключі оригінальної колекції:
$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();
// [0 => 'Desk', 2 => 'Chair']Ця поведінка методу змінюється при використанні Eloquent Collections.
intersectUsing()
Метод intersectUsing видаляє будь-які значення з оригінальної колекції, які не присутні в заданому масиві або колекції, використовуючи спеціальний зворотний виклик для порівняння значень. Отримана колекція збереже ключі оригінальної колекції:
$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersectUsing(['desk', 'chair', 'bookcase'], function (string $a, string $b) {
return strcasecmp($a, $b);
});
$intersect->all();
// [0 => 'Desk', 2 => 'Chair']intersectAssoc()
Метод intersectAssoc порівнює оригінальну колекцію з іншою колекцією або масивом, повертаючи пари ключ / значення, які присутні у всіх заданих колекціях:
$collection = collect([
'color' => 'red',
'size' => 'M',
'material' => 'cotton'
]);
$intersect = $collection->intersectAssoc([
'color' => 'blue',
'size' => 'M',
'material' => 'polyester'
]);
$intersect->all();
// ['size' => 'M']intersectAssocUsing()
Метод intersectAssocUsing порівнює оригінальну колекцію з іншою колекцією або масивом, повертаючи пари ключ/значення, які присутні в обох, використовуючи власний зворотний виклик для порівняння, щоб визначити рівність як для ключів, так і для значень:
$collection = collect([
'color' => 'red',
'Size' => 'M',
'material' => 'cotton',
]);
$intersect = $collection->intersectAssocUsing([
'color' => 'blue',
'size' => 'M',
'material' => 'polyester',
], function (string $a, string $b) {
return strcasecmp($a, $b);
});
$intersect->all();
// ['Size' => 'M']intersectByKeys()
Метод intersectByKeys видаляє будь-які ключі та їх відповідні значення з оригінальної колекції, які не присутні в заданому масиві або колекції:
$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();
// trueisNotEmpty()
Метод isNotEmpty повертає true, якщо колекція не порожня; в іншому випадку повертається false:
collect([])->isNotEmpty();
// falsejoin()
Метод 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();
// 4lazy()
Метод lazy повертає новий екземпляр LazyCollection з базового масиву елементів:
$lazyCollection = collect([1, 2, 3, 4])->lazy();
$lazyCollection::class;
// Illuminate\Support\LazyCollection
$lazyCollection->all();
// [1, 2, 3, 4]Це особливо корисно, коли вам потрібно виконати перетворення на великій Collection, яка містить багато елементів:
$count = $hugeCollection
->lazy()
->where('country', 'FR')
->where('balance', '>', '100')
->count();Перетворюючи колекцію на LazyCollection, ми уникаємо необхідності виділяти велику кількість додаткової пам'яті. Хоча оригінальна колекція все ще зберігає свої значення в пам'яті, наступні фільтри цього не робитимуть. Таким чином, практично жодна додаткова пам'ять не буде виділена при фільтрації результатів колекції.
macro()
Статичний метод macro дозволяє додавати методи до класу Collection під час виконання. Зверніться до документації щодо розширення колекцій для отримання додаткової інформації.
make()
Статичний метод make створює новий екземпляр колекції. Дивіться розділ Створення Колекцій.
use Illuminate\Support\Collection;
$collection = Collection::make([1, 2, 3]);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 { /** * Створити новий екземпляр валюти. */ 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' => 'example@example.com',
],
[
'name' => 'Jane',
'department' => 'Marketing',
'email' => 'example@example.com',
]
]);
$keyed = $collection->mapWithKeys(function (array $item, int $key) {
return [$item['email'] => $item['name']];
});
$keyed->all();
/*
[
'example@example.com' => 'John',
'example@example.com' => 'Jane',
]
*/max()
Метод max повертає максимальне значення для заданого ключа:
$max = collect([
['foo' => 10],
['foo' => 20]
])->max('foo');
// 20
$max = collect([1, 2, 3, 4, 5])->max();
// 5median()
Метод median повертає медіанне значення заданого ключа:
$median = collect([
['foo' => 10],
['foo' => 10],
['foo' => 20],
['foo' => 40]
])->median('foo');
// 15
$median = collect([1, 1, 2, 4])->median();
// 1.5merge()
Метод 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();
// 1mode()
Метод 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]multiply()
Метод multiply створює вказану кількість копій всіх елементів у колекції:
$users = collect([
['name' => 'User #1', 'email' => 'example@example.com'],
['name' => 'User #2', 'email' => 'example@example.com'],
])->multiply(3);
/*
[
['name' => 'User #1', 'email' => 'example@example.com'],
['name' => 'User #2', 'email' => 'example@example.com'],
['name' => 'User #1', 'email' => 'example@example.com'],
['name' => 'User #2', 'email' => 'example@example.com'],
['name' => 'User #1', 'email' => 'example@example.com'],
['name' => 'User #2', 'email' => 'example@example.com'],
]
*/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]Ця поведінка методу змінюється при взаємодії з колекціями Eloquent.
percentage()
Метод percentage може бути використаний для швидкого визначення відсотка елементів у колекції, які проходять заданий тест на істинність:
$collection = collect([1, 1, 2, 2, 2, 3]);
$percentage = $collection->percentage(fn (int $value) => $value === 1);
// 33.33За замовчуванням відсоток буде округлено до двох десяткових знаків. Однак ви можете налаштувати цю поведінку, надавши другий аргумент методу:
$percentage = $collection->percentage(fn (int $value) => $value === 1, precision: 3);
// 33.333pipe()
Метод pipe передає колекцію в задане замикання і повертає результат виконаного замикання:
$collection = collect([1, 2, 3]);
$piped = $collection->pipe(function (Collection $collection) {
return $collection->sum();
});
// 6pipeInto()
Метод pipeInto створює новий екземпляр вказаного класу і передає колекцію в конструктор:
class ResourceCollection { /** * Створити новий екземпляр ResourceCollection. */ 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();
},
]);
// 15pluck()
Метод 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 видаляє та повертає останній елемент з колекції. Якщо колекція порожня, буде повернено null:
$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, string $key) use ($ratio) {
return $carry + ($value * $ratio[$key]);
}, 0);
// 4264reduceSpread()
Метод 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()
Метод 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;
});
// 2select()
Метод select вибирає задані ключі з колекції, подібно до SQL-оператора SELECT:
$users = collect([
['name' => 'Taylor Otwell', 'role' => 'Developer', 'status' => 'active'],
['name' => 'Victoria Faith', 'role' => 'Researcher', 'status' => 'active'],
]);
$users->select(['name', 'role']);
/*
[
['name' => 'Taylor Otwell', 'role' => 'Developer'],
['name' => 'Victoria Faith', 'role' => 'Researcher'],
],
*/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 пропускає елементи з колекції, поки наданий зворотний виклик повертає false. Як тільки зворотний виклик повертає 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. Як тільки зворотний виклик повертає false, всі інші елементи в колекції будуть повернені як нова колекція:
$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, яка є PHP-функцією, що метод 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']);
});
// 6take()
Метод 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();
// 1times()
Статичний метод 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 array. Якщо значення колекції є моделями 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 розширює одновимірну колекцію, яка використовує нотацію "dot", у багатовимірну колекцію:
$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. Екземпляр колекції та перший аргумент, переданий методу unless, будуть надані у замиканні:
$collection = collect([1, 2, 3]);
$collection->unless(true, function (Collection $collection, bool $value) {
return $collection->push(4);
});
$collection->unless(false, function (Collection $collection, bool $value) {
return $collection->push(5);
});
$collection->all();
// [1, 2, 3, 5]Другий зворотний виклик може бути переданий методу unless. Другий зворотний виклик буде виконано, коли перший аргумент, переданий методу unless, оцінюється як true:
$collection = collect([1, 2, 3]);
$collection->unless(true, function (Collection $collection, bool $value) {
return $collection->push(4);
}, function (Collection $collection, bool $value) {
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');
// 200values()
Метод 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, bool $value) {
return $collection->push(4);
});
$collection->when(false, function (Collection $collection, bool $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, bool $value) {
return $collection->push(4);
}, function (Collection $collection, bool $value) {
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; } fclose($handle); })->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;
}
fclose($handle);
});Контракт 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
// 3throttle()
Метод throttle буде обмежувати швидкість лінивої колекції таким чином, що кожне значення буде повертатися після вказаної кількості секунд. Цей метод особливо корисний у ситуаціях, коли ви можете взаємодіяти з зовнішніми API, які обмежують швидкість вхідних запитів:
use App\Models\User; User::where('vip', true) ->cursor() ->throttle(seconds: 1) ->each(function (User $user) { // Викликати зовнішній API... });
remember()
Метод remember повертає нову ліниву колекцію, яка запам'ятає будь-які значення, що вже були перераховані, і не буде отримувати їх знову при наступних перерахуваннях колекції:
// Ще жоден запит не було виконано...
$users = User::cursor()->remember();
// Запит виконується...
// Перші 5 користувачів завантажуються з бази даних...
$users->take(5)->all();
// Перші 5 користувачів надходять з кешу колекції...
// Решта заповнюється з бази даних...
$users->take(20)->all();