Версія фреймворка: 8.x

Колекції

Вступ

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

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

Як бачите,Collectionклас дозволяє зв’язати його методи для виконання плавного зіставлення та зменшення базового масиву. Загалом, колекції є незмінними, тобто коженCollectionметод повертає абсолютно новийCollectionінстанції.

Створення колекцій

Як зазначалося вище,collectПомічник повертає новийIlluminate\Support\Collectionекземпляр для даного масиву. Отже, створити колекцію просто:

$collection = collect([1, 2, 3]);
РезультатиКрасномовнийзапити завжди повертаються якCollectionекземпляри.

Розширення колекцій

Колекції є "макроздатними", що дозволяє додавати додаткові методи доCollectionклас під час виконання. Наприклад, наступний код додає atoUpperметод доCollectionклас:

use Illuminate\Support\Collection;
use Illuminate\Support\Str;

Collection::macro('toUpper', function () {
    return $this->map(function ($value) {
        return Str::upper($value);
    });
});

$collection = collect(['first', 'second']);

$upper = $collection->toUpper();

// ['FIRST', 'SECOND']

Як правило, ви повинні оголосити макроси колекції впостачальник послуг.

Доступні методи

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

всісереднійсершматокшматоккрахзбиратикомбінуватиконкатміститьміститьStrictрахуватиcountBycrossJoinddрізницяdiffAssocdiffKeysсмітникдублікатидублікати СтрогийкоженкоженРозширеннякоженкрімфільтрспочаткупершийДеflatMapсплющитиперевернутизабутиforPageотриматиgroupByмаєвибухнутиперетинаютьсяintersectByKeysпустоisNotEmptyприєднуватисяkeyByклавішіостанніймакросзробитикартавступmapSpreadmapToGroupsmapWithKeysмаксмедіанапітиmergeRecursiveхврежиміn-йлишеподушечкарозділтрубаπιπεΊντοзриватипоппопередньотягнутиштовхатипоставитивипадковізменшитивідкинутизамінитиreplaceRecursiveзворотнийпошукзмінаперетасуватипропуститиshipUtilskipWhileскибочкадещосортуватисортувати заsortByDescsortDescsortKeyssortKeysDescзрощеннярозколотиСплітсумаприйматиtakeUntiltakeWhileнатиснітьразівtoArrayдо ДжсонаперетворюватисоюзунікальнийuniqueStrictхіба щоelseEmptyifNotEmptyрозгорнутизначенняколиwhenEmptywhenNotEmptyдедеStrictде МіждеwhereInStrictwhereInstanceOfде не міждеНеВдеNotInStrictде неНульдеНульобернутизастібку-блискавку

Перелік методів

all(){# collection-method .first-collection-method}

allметод повертає базовий масив, представлений колекцією:

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

// [1, 2, 3]

average(){# collection-method}

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

avg(){# collection-method}

avgметод повертаєсереднє значенняданого ключа:

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

// 20

$average = collect([1, 1, 2, 4])->avg();

// 2

chunk(){# collection-method}

chunkметод розбиває колекцію на кілька менших колекцій заданого розміру:

$collection = collect([1, 2, 3, 4, 5, 6, 7]);

$chunks = $collection->chunk(4);

$chunks->all();

// [[1, 2, 3, 4], [5, 6, 7]]

Цей метод особливо корисний упоглядипри роботі з сітковою системою, такою якBootstrap. Уявіть, у вас є колекціяКрасномовниймоделі, які потрібно відобразити в сітці:

@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(){# collection-method}

chunkWhileметод розбиває колекцію на кілька менших колекцій на основі оцінки даного зворотного виклику:

$collection = collect(str_split('AABBCCCD'));

$chunks = $collection->chunkWhile(function ($current, $key, $chunk) {
    return $current === $chunk->last();
});

$chunks->all();

// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]

collapse(){# collection-method}

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]

combine(){# collection-method}

combineметод поєднує значення колекції, як ключі, зі значеннями іншого масиву або колекції:

$collection = collect(['name', 'age']);

$combined = $collection->combine(['George', 29]);

$combined->all();

// ['name' => 'George', 'age' => 29]

collect(){# collection-method}

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();

get_class($collection);

// 'Illuminate\Support\Collection'

$collection->all();

// [1, 2, 3]
Thecollectметод особливо корисний, коли у вас є екземплярEnumerableі потрібен не ледачий екземпляр колекції. Оскількиcollect()є частиноюEnumerableконтракту, ви можете сміливо використовувати його для отриманняCollectionінстанції.

concat(){# collection-method}

concatметод додає поданийarrayабо значення колекції в кінці колекції:

$collection = collect(['John Doe']);

$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);

$concatenated->all();

// ['John Doe', 'Jane Doe', 'Johnny Doe']

contains(){# collection-method}

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спосіб провести власний тест на істину:

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

$collection->contains(function ($value, $key) {
    return $value > 5;
});

// false

containsметод використовує "вільні" порівняння при перевірці значень елементів, тобто рядок із цілим значенням вважатиметься рівним цілому числу того самого значення. ВикористовуватиcontainsStrictметод фільтрації за допомогою "суворих" порівнянь.

containsStrict(){# collection-method}

Цей метод має той самий підпис, що іcontainsметод; однак усі значення порівнюються за допомогою "суворих" порівнянь.

Поведінка цього методу змінюється під час використанняКрасномовні колекції.

count(){# collection-method}

countметод повертає загальну кількість предметів у колекції:

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

$collection->count();

// 4

countBy(){# collection-method}

countByметод підраховує випадки значень у колекції. За замовчуванням метод враховує випадки кожного елемента:

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

$counted = $collection->countBy();

$counted->all();

// [1 => 1, 2 => 3, 3 => 1]

Однак ви передаєте зворотний дзвінок наcountByметод для підрахунку всіх елементів за власним значенням:

$collection = collect(['alice@gmail.com', 'bob@yahoo.com', 'carlos@gmail.com']);

$counted = $collection->countBy(function ($email) {
    return substr(strrchr($email, "@"), 1);
});

$counted->all();

// ['gmail.com' => 2, 'yahoo.com' => 1]

crossJoin(){# collection-method}

crossJoinметод cross поєднує значення колекції серед даних масивів або колекцій, повертаючи декартовий твір з усіма можливими перестановками:

$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(){# collection-method}

ddметод скидає елементи колекції і закінчує виконання сценарію:

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dd();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

Якщо ви не хочете припиняти виконання сценарію, використовуйтеdumpзамість цього.

diff(){# collection-method}

diffметод порівнює колекцію з іншою колекцією або звичайним PHParrayвиходячи з його цінностей. Цей метод поверне значення у вихідній колекції, яких немає у даній колекції:

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

$diff = $collection->diff([2, 4, 6, 8]);

$diff->all();

// [1, 3, 5]
Поведінка цього методу змінюється під час використанняКрасномовні колекції.

diffAssoc(){# collection-method}

diffAssocметод порівнює колекцію з іншою колекцією або звичайним PHParrayна основі його ключів та значень. Цей метод повертає пари ключ / значення в вихідній колекції, яких немає у даній колекції:

$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]

diffKeys(){# collection-method}

diffKeysметод порівнює колекцію з іншою колекцією або звичайним PHParrayна основі його ключів. Цей метод повертає пари ключ / значення в вихідній колекції, яких немає у даній колекції:

$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]

dump(){# collection-method}

dumpметод скидає елементи колекції:

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dump();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

Якщо ви хочете припинити виконання сценарію після скидання колекції, використовуйтеddзамість цього.

duplicates(){# collection-method}

duplicatesметод отримує та повертає повторювані значення з колекції:

$collection = collect(['a', 'b', 'a', 'c', 'b']);

$collection->duplicates();

// [2 => 'a', 4 => 'b']

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

$employees = collect([
    ['email' => 'abigail@example.com', 'position' => 'Developer'],
    ['email' => 'james@example.com', 'position' => 'Designer'],
    ['email' => 'victoria@example.com', 'position' => 'Developer'],
])

$employees->duplicates('position');

// [2 => 'Developer']

duplicatesStrict(){# collection-method}

Цей метод має той самий підпис, що іduplicatesметод; однак усі значення порівнюються за допомогою "суворих" порівнянь.

each(){# collection-method}

eachметод перебирає елементи в колекції і передає кожен елемент до зворотного виклику:

$collection->each(function ($item, $key) {
    //
});

Якщо ви хочете припинити перегляд елементів, ви можете повернутисяfalseз вашого зворотного дзвінка:

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

eachSpread(){# collection-method}

eachSpreadметод перебирає елементи колекції, передаючи кожне вкладене значення елемента в заданий зворотний виклик:

$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);

$collection->eachSpread(function ($name, $age) {
    //
});

Ви можете припинити перегляд елементів, повернувшисьfalseіз зворотного дзвінка:

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

every(){# collection-method}

everyметод може бути використаний для перевірки того, що всі елементи колекції проходять заданий тест на істинність:

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

// false

Якщо колекція порожня,everyповерне true:

$collection = collect([]);

$collection->every(function ($value, $key) {
    return $value > 2;
});

// true

except(){# collection-method}

exceptметод повертає всі елементи колекції, крім тих, що мають вказані ключі:

$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);

$filtered = $collection->except(['price', 'discount']);

$filtered->all();

// ['product_id' => 1]

Для оберненого доexcept, дивлишеметод.

Поведінка цього методу змінюється під час використанняКрасномовні колекції.

filter(){# collection-method}

filterметод фільтрує колекцію за допомогою заданого зворотного виклику, зберігаючи лише ті елементи, які проходять заданий тест на істинність:

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

$filtered = $collection->filter(function ($value, $key) {
    return $value > 2;
});

$filtered->all();

// [3, 4]

Якщо зворотного виклику не надано, усі записи колекції, які еквівалентніfalseбуде видалено:

$collection = collect([1, 2, 3, null, false, '', 0, []]);

$collection->filter()->all();

// [1, 2, 3]

Для оберненого доfilter, диввідкинутиметод.

first(){# collection-method}

firstметод повертає перший елемент у колекції, який проходить заданий тест на істинність:

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

// 3

Ви також можете зателефонувати доfirstметод без аргументів для отримання першого елемента в колекції. Якщо колекція порожня,nullповертається:

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

// 1

firstWhere(){# collection-method}

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]

Подобаєтьсядеметод, ви можете передати один аргумент доfirstWhereметод. У цьому випадку сценарійfirstWhereметод поверне перший елемент, де значення даного ключа елемента "істинно":

$collection->firstWhere('age');

// ['name' => 'Linda', 'age' => 14]

flatMap(){# collection-method}

flatMapметод перебирає колекцію та передає кожне значення до заданого зворотного виклику. Зворотний дзвінок може змінювати товар та повертати його, таким чином формуючи нову колекцію модифікованих елементів. Потім масив згладжується рівнем:

$collection = collect([
    ['name' => 'Sally'],
    ['school' => 'Arkansas'],
    ['age' => 28]
]);

$flattened = $collection->flatMap(function ($values) {
    return array_map('strtoupper', $values);
});

$flattened->all();

// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];

flatten(){# collection-method}

flattenметод вирівнює багатовимірну колекцію в один вимір:

$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);

$flattened = $collection->flatten();

$flattened->all();

// ['taylor', 'php', 'javascript'];

За бажанням ви можете передати функції аргумент "глибина":

$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(){# collection-method}

flipметод міняє місцями ключі колекції з відповідними значеннями:

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

$flipped = $collection->flip();

$flipped->all();

// ['taylor' => 'name', 'laravel' => 'framework']

forget(){# collection-method}

forgetметод видаляє елемент із колекції за його ключем:

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

$collection->forget('name');

$collection->all();

// ['framework' => 'laravel']
На відміну від більшості інших методів збору,forgetне повертає нову змінену колекцію; він змінює колекцію, до якої його викликають.

forPage(){# collection-method}

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

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);

$chunk = $collection->forPage(2, 3);

$chunk->all();

// [4, 5, 6]

get(){# collection-method}

getметод повертає елемент за заданим ключем. Якщо ключ не існує,nullповертається:

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

$value = $collection->get('name');

// taylor

Ви можете додатково передати значення за замовчуванням як другий аргумент:

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

$value = $collection->get('foo', 'default-value');

// default-value

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

$collection->get('email', function () {
    return 'default-value';
});

// default-value

groupBy(){# collection-method}

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 ($item, $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 ($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(){# collection-method}

hasМетод визначає, чи існує даний колекція в колекції:

$collection = collect(['account_id' => 1, 'product' => 'Desk', 'amount' => 5]);

$collection->has('product');

// true

$collection->has(['product', 'amount']);

// true

$collection->has(['amount', 'price']);

// false

implode(){# collection-method}

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'

intersect(){# collection-method}

intersectметод видаляє будь-які значення з вихідної колекції, які відсутні в даномуarrayабо колекція. Отримана колекція збереже ключі оригінальної колекції:

$collection = collect(['Desk', 'Sofa', 'Chair']);

$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);

$intersect->all();

// [0 => 'Desk', 2 => 'Chair']
Поведінка цього методу змінюється під час використанняКрасномовні колекції.

intersectByKeys(){# collection-method}

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(){# collection-method}

isEmptyметод повертаєtrueякщо колекція порожня; інакше,falseповертається:

collect([])->isEmpty();

// true

isNotEmpty(){# collection-method}

isNotEmptyметод повертаєtrueякщо колекція не порожня; інакше,falseповертається:

collect([])->isNotEmpty();

// false

join(){# collection-method}

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(){# collection-method}

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 ($item) {
    return strtoupper($item['product_id']);
});

$keyed->all();

/*
    [
        'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
        'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
    ]
*/

keys(){# collection-method}

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(){# collection-method}

lastметод повертає останній елемент у колекції, який проходить заданий тест на істинність:

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

// 2

Ви також можете зателефонувати доlastметод без аргументів для отримання останнього елемента в колекції. Якщо колекція порожня,nullповертається:

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

// 4

macro(){# collection-method}

Статичнийmacroметод дозволяє додавати методи доCollectionклас під час виконання. Зверніться до документації нарозширення колекційдля отримання додаткової інформації.

make(){# collection-method}

Статичнийmakeметод створює новий екземпляр колекції. ДивСтворення колекційрозділ.

map(){# collection-method}

mapметод перебирає колекцію та передає кожне значення до заданого зворотного виклику. Зворотний дзвінок може змінювати товар та повертати його, таким чином формуючи нову колекцію модифікованих елементів:

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

$multiplied = $collection->map(function ($item, $key) {
    return $item * 2;
});

$multiplied->all();

// [2, 4, 6, 8, 10]
Як і більшість інших методів збору,mapповертає новий екземпляр колекції; він не змінює колекцію, до якої його викликають. Якщо ви хочете перетворити оригінальну колекцію, використовуйтеtransformметод.

mapInto(){# collection-method}

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

class Currency
{
    /**
     * Create a new currency instance.
     *
     * @param  string  $code
     * @return void
     */
    function __construct(string $code)
    {
        $this->code = $code;
    }
}

$collection = collect(['USD', 'EUR', 'GBP']);

$currencies = $collection->mapInto(Currency::class);

$currencies->all();

// [Currency('USD'), Currency('EUR'), Currency('GBP')]

mapSpread(){# collection-method}

mapSpreadметод перебирає елементи колекції, передаючи кожне вкладене значення елемента в заданий зворотний виклик. Зворотний дзвінок може змінювати товар та повертати його, таким чином формуючи нову колекцію модифікованих елементів:

$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

$chunks = $collection->chunk(2);

$sequence = $chunks->mapSpread(function ($even, $odd) {
    return $even + $odd;
});

$sequence->all();

// [1, 5, 9, 13, 17]

mapToGroups(){# collection-method}

mapToGroupsметод групує елементи колекції за даним зворотним викликом. Зворотний виклик повинен повернути асоціативний масив, що містить одну пару ключ / значення, формуючи таким чином нову колекцію згрупованих значень:

$collection = collect([
    [
        'name' => 'John Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Jane Doe',
        'department' => 'Sales',
    ],
    [
        'name' => 'Johnny Doe',
        'department' => 'Marketing',
    ]
]);

$grouped = $collection->mapToGroups(function ($item, $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(){# collection-method}

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

$collection = collect([
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => 'john@example.com',
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => 'jane@example.com',
    ]
]);

$keyed = $collection->mapWithKeys(function ($item) {
    return [$item['email'] => $item['name']];
});

$keyed->all();

/*
    [
        'john@example.com' => 'John',
        'jane@example.com' => 'Jane',
    ]
*/

max(){# collection-method}

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

$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');

// 20

$max = collect([1, 2, 3, 4, 5])->max();

// 5

median(){# collection-method}

medianметод повертаєсерединне значенняданого ключа:

$median = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->median('foo');

// 15

$median = collect([1, 1, 2, 4])->median();

// 1.5

merge(){# collection-method}

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(){# collection-method}

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(){# collection-method}

minметод повертає мінімальне значення даного ключа:

$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');

// 10

$min = collect([1, 2, 3, 4, 5])->min();

// 1

mode(){# collection-method}

modeметод повертаєзначення режимуданого ключа:

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

// [10]

$mode = collect([1, 1, 2, 4])->mode();

// [1]

nth(){# collection-method}

nthметод створює нову колекцію, що складається з кожного n-го елемента:

$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);

$collection->nth(4);

// ['a', 'e']

Ви можете додатково передати зміщення як другий аргумент:

$collection->nth(4, 1);

// ['b', 'f']

only(){# collection-method}

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, дивкрімметод.

Поведінка цього методу змінюється під час використанняКрасномовні колекції.

pad(){# collection-method}

padметод буде заповнювати масив заданим значенням, поки масив не досягне заданого розміру. Цей метод поводиться якarray_padФункція PHP.

Щоб додати ліворуч, слід вказати від’ємний розмір. Заповнення не відбудеться, якщо абсолютне значення заданого розміру менше або дорівнює довжині масиву:

$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(){# collection-method}

partitionметод може поєднуватися зlistФункція PHP для відокремлення елементів, які проходять заданий тест на істину, від тих, які цього не роблять:

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

list($underThree, $equalOrAboveThree) = $collection->partition(function ($i) {
    return $i < 3;
});

$underThree->all();

// [1, 2]

$equalOrAboveThree->all();

// [3, 4, 5, 6]

pipe(){# collection-method}

pipeметод передає колекцію даному зворотному виклику і повертає результат:

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

$piped = $collection->pipe(function ($collection) {
    return $collection->sum();
});

// 6

pipeInto(){# collection-method}

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

class ResourceCollection
{
    /**
     * The Collection instance.
     */
    public $collection;

    /**
     * Create a new ResourceCollection instance.
     *
     * @param  Collection  $resource
     * @return void
     */
    public function __construct(Collection $collection)
    {
        $this->collection = $collection;
    }
}

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

$resource = $collection->pipeInto(ResourceCollection::class);

$resource->collection->all();

// [1, 2, 3]

pluck(){# collection-method}

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([
    [
        'speakers' => [
            'first_day' => ['Rosa', 'Judith'],
            'second_day' => ['Angela', 'Kathleen'],
        ],
    ],
]);

$plucked = $collection->pluck('speakers.first_day');

$plucked->all();

// ['Rosa', 'Judith']

Якщо існують повторювані ключі, останній відповідний елемент буде вставлений до зібраної колекції:

$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(){# collection-method}

popметод видаляє та повертає останній елемент із колекції:

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

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

prepend(){# collection-method}

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(){# collection-method}

pullметод видаляє та повертає елемент із колекції за його ключем:

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

$collection->pull('name');

// 'Desk'

$collection->all();

// ['product_id' => 'prod-100']

push(){# collection-method}

pushметод додає елемент до кінця колекції:

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

$collection->push(5);

$collection->all();

// [1, 2, 3, 4, 5]

put(){# collection-method}

putметод встановлює заданий ключ і значення в колекції:

$collection = collect(['product_id' => 1, 'name' => 'Desk']);

$collection->put('price', 100);

$collection->all();

// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]

random(){# collection-method}

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)

Якщо у колекції менше предметів, ніж запитувалося, метод видастьInvalidArgumentException.

reduce(){# collection-method}

reduceметод зменшує колекцію до одного значення, передаючи результат кожної ітерації в наступну ітерацію:

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

$total = $collection->reduce(function ($carry, $item) {
    return $carry + $item;
});

// 6

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

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

// 10

reject(){# collection-method}

rejectметод фільтрує колекцію за допомогою заданого зворотного виклику. Зворотний дзвінок повинен повернутисяtrueякщо предмет слід вилучити з отриманої колекції:

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

$filtered = $collection->reject(function ($value, $key) {
    return $value > 2;
});

$filtered->all();

// [1, 2]

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

replace(){# collection-method}

replaceметод поводиться подібно доmerge; однак, на додаток до перезапису відповідних елементів за допомогою рядкових ключів,replaceметод також перезапише елементи в колекції, які мають відповідні числові клавіші:

$collection = collect(['Taylor', 'Abigail', 'James']);

$replaced = $collection->replace([1 => 'Victoria', 3 => 'Finn']);

$replaced->all();

// ['Taylor', 'Victoria', 'James', 'Finn']

replaceRecursive(){# collection-method}

Цей метод працює якreplace, але він перетвориться на масиви і застосує той самий процес заміни до внутрішніх значень:

$collection = collect(['Taylor', 'Abigail', ['James', 'Victoria', 'Finn']]);

$replaced = $collection->replaceRecursive(['Charlie', 2 => [1 => 'King']]);

$replaced->all();

// ['Charlie', 'Abigail', ['James', 'King', 'Finn']]

reverse(){# collection-method}

reverseметод змінює порядок предметів колекції, зберігаючи оригінальні ключі:

$collection = collect(['a', 'b', 'c', 'd', 'e']);

$reversed = $collection->reverse();

$reversed->all();

/*
    [
        4 => 'e',
        3 => 'd',
        2 => 'c',
        1 => 'b',
        0 => 'a',
    ]
*/

search(){# collection-method}

searchметод шукає в колекції задане значення і повертає його ключ, якщо його знайдено. Якщо предмет не знайдено,falseповертається.

$collection = collect([2, 4, 6, 8]);

$collection->search(4);

// 1

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

$collection->search('4', true);

// false

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

$collection->search(function ($item, $key) {
    return $item > 5;
});

// 2

shift(){# collection-method}

shiftметод видаляє та повертає перший елемент із колекції:

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

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

shuffle(){# collection-method}

shuffleметод випадковим чином перетасовує елементи колекції:

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

$shuffled = $collection->shuffle();

$shuffled->all();

// [3, 2, 5, 1, 4] - (generated randomly)

skip(){# collection-method}

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(){# collection-method}

skipUntilметод пропускає елементи, поки не повернеться даний зворотний викликtrueа потім повертає решту елементів у колекції:

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

$subset = $collection->skipUntil(function ($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(){# collection-method}

skipWhileметод пропускає елементи, поки наданий зворотний виклик повертаєтьсяtrueа потім повертає решту елементів у колекції:

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

$subset = $collection->skipWhile(function ($item) {
    return $item <= 3;
});

$subset->all();

// [4]
Якщо зворотний дзвінок ніколи не повернетьсяtrue,skipWhileметод поверне порожню колекцію.

slice(){# collection-method}

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метод їх переіндексації.

some(){# collection-method}

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

sort(){# collection-method}

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(){# collection-method}

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],
    ]
*/

Цей метод приймаєсортувати прапорияк другий аргумент:

$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 ($product, $key) {
    return count($product['colors']);
});

$sorted->values()->all();

/*
    [
        ['name' => 'Chair', 'colors' => ['Black']],
        ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
        ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
    ]
*/

sortByDesc(){# collection-method}

Цей метод має той самий підпис, що іsortByметод, але сортуватиме колекцію в зворотному порядку.

sortDesc(){# collection-method}

Цей метод сортує колекцію в протилежному порядку якsortметод:

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

$sorted = $collection->sortDesc();

$sorted->values()->all();

// [5, 4, 3, 2, 1]

На відміну відsort, Ви не можете передати зворотній дзвінокsortDesc. Якщо ви хочете скористатися зворотним дзвінком, вам слід скористатисяsortта оберніть своє порівняння.

sortKeys(){# collection-method}

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

$collection = collect([
    'id' => 22345,
    'first' => 'John',
    'last' => 'Doe',
]);

$sorted = $collection->sortKeys();

$sorted->all();

/*
    [
        'first' => 'John',
        'id' => 22345,
        'last' => 'Doe',
    ]
*/

sortKeysDesc(){# collection-method}

Цей метод має той самий підпис, що іsortKeysметод, але сортуватиме колекцію в зворотному порядку.

splice(){# collection-method}

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(){# collection-method}

splitметод розбиває колекцію на задану кількість груп:

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

$groups = $collection->split(3);

$groups->all();

// [[1, 2], [3, 4], [5]]

splitIn(){# collection-method}

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(){# collection-method}

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 ($product) {
    return count($product['colors']);
});

// 6

take(){# collection-method}

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(){# collection-method}

takeUntilметод повертає елементи в колекції, поки не повернеться даний зворотний викликtrue:

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

$subset = $collection->takeUntil(function ($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(){# collection-method}

takeWhileметод повертає елементи в колекції, поки не повернеться даний зворотний викликfalse:

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

$subset = $collection->takeWhile(function ($item) {
    return $item < 3;
});

$subset->all();

// [1, 2]
Якщо зворотний дзвінок ніколи не повернетьсяfalse,takeWhileметод поверне всі елементи колекції.

tap(){# collection-method}

tapметод передає колекцію даному зворотному виклику, дозволяючи "натискати" на колекцію в певний момент і робити щось із елементами, не впливаючи на саму колекцію:

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

// 1

times(){# collection-method}

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

$collection = Collection::times(10, function ($number) {
    return $number * 9;
});

$collection->all();

// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]

Цей метод може бути корисним у поєднанні з фабриками для створенняКрасномовниймоделі:

$categories = Collection::times(3, function ($number) {
    return Category::factory()->create(['name' => "Category No. $number"]);
});

$categories->all();

/*
    [
        ['id' => 1, 'name' => 'Category No. 1'],
        ['id' => 2, 'name' => 'Category No. 2'],
        ['id' => 3, 'name' => 'Category No. 3'],
    ]
*/

toArray(){# collection-method}

toArrayметод перетворює колекцію на звичайний PHParray. Якщо значення колекціїКрасномовниймоделі, моделі також будуть перетворені в масиви:

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

$collection->toArray();

/*
    [
        ['name' => 'Desk', 'price' => 200],
    ]
*/
toArrayтакож перетворює всі вкладені об'єкти колекції, які є екземпляромArrayableдо масиву. Якщо ви хочете отримати необроблений базовий масив, використовуйтеallзамість цього.

toJson(){# collection-method}

toJsonметод перетворює колекцію в серіалізований рядок JSON:

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

$collection->toJson();

// '{"name":"Desk", "price":200}'

transform(){# collection-method}

transformметод перебирає колекцію та викликає заданий зворотний виклик з кожним елементом у колекції. Елементи колекції будуть замінені значеннями, повернутими зворотним викликом:

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

$collection->transform(function ($item, $key) {
    return $item * 2;
});

$collection->all();

// [2, 4, 6, 8, 10]
На відміну від більшості інших методів збору,transformмодифікує саму колекцію. Якщо замість цього ви хочете створити нову колекцію, використовуйтеmapметод.

union(){# collection-method}

unionметод додає даний масив до колекції. Якщо даний масив містить ключі, які вже є в оригінальній колекції, переважними будуть значення оригінальної колекції:

$collection = collect([1 => ['a'], 2 => ['b']]);

$union = $collection->union([3 => ['c'], 1 => ['b']]);

$union->all();

// [1 => ['a'], 2 => ['b'], 3 => ['c']]

unique(){# collection-method}

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 = $collection->unique(function ($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метод фільтрації за допомогою "суворих" порівнянь.

Поведінка цього методу змінюється під час використанняКрасномовні колекції.

uniqueStrict(){# collection-method}

Цей метод має той самий підпис, що іuniqueметод; однак усі значення порівнюються за допомогою "суворих" порівнянь.

unless(){# collection-method}

unlessmethod виконає даний зворотний виклик, якщо перший аргумент, наданий методу, не має значенняtrue:

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

$collection->unless(true, function ($collection) {
    return $collection->push(4);
});

$collection->unless(false, function ($collection) {
    return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 5]

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

unlessEmpty(){# collection-method}

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

unlessNotEmpty(){# collection-method}

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

unwrap(){# collection-method}

Статичнийunwrapметод повертає основні елементи колекції із заданого значення, коли це застосовно:

Collection::unwrap(collect('John Doe'));

// ['John Doe']

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

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'

values(){# collection-method}

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(){# collection-method}

whenmethod виконає даний зворотний виклик, коли перший аргумент, наданий методу, оцінюється якtrue:

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

$collection->when(true, function ($collection) {
    return $collection->push(4);
});

$collection->when(false, function ($collection) {
    return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 4]

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

whenEmpty(){# collection-method}

whenEmptyметод виконає даний зворотний виклик, коли колекція порожня:

$collection = collect(['michael', 'tom']);

$collection->whenEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// ['michael', 'tom']


$collection = collect();

$collection->whenEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// ['adam']


$collection = collect(['michael', 'tom']);

$collection->whenEmpty(function ($collection) {
    return $collection->push('adam');
}, function ($collection) {
    return $collection->push('taylor');
});

$collection->all();

// ['michael', 'tom', 'taylor']

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

whenNotEmpty(){# collection-method}

whenNotEmptyметод виконає даний зворотний виклик, коли колекція не порожня:

$collection = collect(['michael', 'tom']);

$collection->whenNotEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// ['michael', 'tom', 'adam']


$collection = collect();

$collection->whenNotEmpty(function ($collection) {
    return $collection->push('adam');
});

$collection->all();

// []


$collection = collect();

$collection->whenNotEmpty(function ($collection) {
    return $collection->push('adam');
}, function ($collection) {
    return $collection->push('taylor');
});

$collection->all();

// ['taylor']

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

where(){# collection-method}

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(){# collection-method}

Цей метод має той самий підпис, що іwhereметод; однак усі значення порівнюються за допомогою "суворих" порівнянь.

whereBetween(){# collection-method}

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(){# collection-method}

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(){# collection-method}

Цей метод має той самий підпис, що іwhereInметод; однак усі значення порівнюються за допомогою "суворих" порівнянь.

whereInstanceOf(){# collection-method}

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(){# collection-method}

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(){# collection-method}

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(){# collection-method}

Цей метод має той самий підпис, що іwhereNotInметод; однак усі значення порівнюються за допомогою "суворих" порівнянь.

whereNotNull(){# collection-method}

whereNotNullметод фільтрує елементи, де даний ключ не має значення null:

$collection = collect([
    ['name' => 'Desk'],
    ['name' => null],
    ['name' => 'Bookcase'],
]);

$filtered = $collection->whereNotNull('name');

$filtered->all();

/*
    [
        ['name' => 'Desk'],
        ['name' => 'Bookcase'],
    ]
*/

whereNull(){# collection-method}

whereNullметод фільтрує елементи, де даний ключ має значення null:

$collection = collect([
    ['name' => 'Desk'],
    ['name' => null],
    ['name' => 'Bookcase'],
]);

$filtered = $collection->whereNull('name');

$filtered->all();

/*
    [
        ['name' => null],
    ]
*/

wrap(){# collection-method}

Статичнийwrapметод обертає задане значення у колекції, коли це застосовно:

$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(){# collection-method}

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повідомлення вищого порядку для виклику методу для кожного об’єкта в колекції:

$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 ($lines) {
    return LogEntry::fromLines($lines);
})->each(function (LogEntry $logEntry) {
    // Process the log entry...
});

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

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

Однак запит розробникаcursorметод повертає aLazyCollectionінстанції. Це дозволяє виконувати лише один запит до бази даних, але одночасно зберігати в пам'яті лише одну модель Eloquent. У цьому прикладіfilterзворотний виклик не виконується, поки ми фактично не повторимо кожного користувача окремо, що дозволить різко зменшити використання пам'яті:

$users = App\Models\User::cursor()->filter(function ($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контракт, який визначає такі методи:

Методи, що мутують колекцію (наприкладshift,pop,prependтощо)_ні_доступні наLazyCollectionклас.

Методи лінивого збору

На додаток до методів, визначених уEnumerableконтракт,LazyCollectionклас містить такі методи:

tapEach(){# collection-method}

Покиeachметод викликає даний зворотний виклик для кожного елемента в колекції відразу,tapEachметод викликає лише даний зворотний виклик, оскільки елементи витягуються зі списку по одному:

$lazyCollection = LazyCollection::times(INF)->tapEach(function ($value) {
    dump($value);
});

// Nothing has been dumped so far...

$array = $lazyCollection->take(3)->all();

// 1
// 2
// 3

remember(){# collection-method}

rememberМетод повертає нову ліниву колекцію, яка запам'ятає всі перераховані значення і не отримає їх знову, коли колекція буде перерахована знову:

$users = User::cursor()->remember();

// No query has been executed yet...

$users->take(5)->all();

// The query has been executed and the first 5 users have been hydrated from the database...

$users->take(20)->all();

// First 5 users come from the collection's cache... The rest are hydrated from the database...