Коллекции

Статистика: Символов — 37 002/30 968 без пробелов (15 481/13 331 без кода):, слов — 2 151
Разметка: Wiki
{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11}}
immutable
== Введение ==

Класс %%(t)Illuminate\Support\Collection%% предоставляет гибкую и удобную обёртку для работы с массивами данных. Например, посмотрите на следующий код. Мы будем использовать вспомогательную функцию %%collect()%%, чтобы создать новый экземпляр коллекции из массива, выполним функцию %%strtoupper()%% для каждого элемента, а затем удалим все пустые элементы:
%%
$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
  return strtoupper($name);
})
->reject(function ($name) {
  return empty($name);
});
%%

Как видите, класс %%(t)Collection%% позволяет использовать свои методы в связке для гибкого отображения и уменьшения исходного массива. В общем, коллекции "неизменны", то есть каждый метод класса %%(t)Collection%% возвращает совершенно новый экземпляр %%(t)Collection%%.

=== Создание коллекций ===
Как упоминалось выше, вспомогательная функция %%collect()%% возвращает новый экземпляр класса %%(t)Illuminate\Support\Collection%% для заданного массива. Поэтому создать коллекцию очень просто:
%%
$collection = collect([1, 2, 3]);
%%

.(alert)
Результаты запросов ((/docs/v5/eloquent Eloquent)) всегда возвращаются в виде экземпляров класса %%(t)Collection%%.

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

((/docs/v5/collections#all all))
((/docs/v5/collections#avg avg))
((/docs/v5/collections#chunk chunk))
((/docs/v5/collections#collapse collapse))
((/docs/v5/collections#combine combine))
((/docs/v5/collections#contains contains))
((/docs/v5/collections#count count))
((/docs/v5/collections#diff diff))
((/docs/v5/collections#diffkeys diffKeys))
((/docs/v5/collections#each each))
((/docs/v5/collections#every every))
((/docs/v5/collections#except except))
((/docs/v5/collections#filter filter))
((/docs/v5/collections#first first))
((/docs/v5/collections#flatmap flatMap))
((/docs/v5/collections#flatten flatten))
((/docs/v5/collections#flip flip))
((/docs/v5/collections#forget forget))
((/docs/v5/collections#forpage forPage))
((/docs/v5/collections#get get))
((/docs/v5/collections#groupby groupBy))
((/docs/v5/collections#has has))
((/docs/v5/collections#implode implode))
((/docs/v5/collections#intersect intersect))
((/docs/v5/collections#isempty isEmpty))
((/docs/v5/collections#keyby keyBy))
((/docs/v5/collections#keys keys))
((/docs/v5/collections#last last))
((/docs/v5/collections#map map))
((/docs/v5/collections#mapwithkeys mapWithKeys))
((/docs/v5/collections#max max))
((/docs/v5/collections#merge merge))
((/docs/v5/collections#min min))
((/docs/v5/collections#only only))
((/docs/v5/collections#pipe pipe))
((/docs/v5/collections#pluck pluck))
((/docs/v5/collections#pop pop))
((/docs/v5/collections#prepend prepend))
((/docs/v5/collections#pull pull))
((/docs/v5/collections#push push))
((/docs/v5/collections#put put))
((/docs/v5/collections#random random))
((/docs/v5/collections#reduce reduce))
((/docs/v5/collections#reject reject))
((/docs/v5/collections#reverse reverse))
((/docs/v5/collections#search search))
((/docs/v5/collections#shift shift))
((/docs/v5/collections#shuffle shuffle))
((/docs/v5/collections#slice slice))
((/docs/v5/collections#sort sort))
((/docs/v5/collections#sortby sortBy))
((/docs/v5/collections#sortbydesc sortByDesc))
((/docs/v5/collections#splice splice))
((/docs/v5/collections#split split))
((/docs/v5/collections#sum sum))
((/docs/v5/collections#take take))
((/docs/v5/collections#toarray toArray))
((/docs/v5/collections#tojson toJson))
((/docs/v5/collections#transform transform))
((/docs/v5/collections#union union))
((/docs/v5/collections#unique unique))
((/docs/v5/collections#values values))
((/docs/v5/collections#where where))
((/docs/v5/collections#wherestrict whereStrict))
((/docs/v5/collections#whereloose whereLoose))
((/docs/v5/collections#wherein whereIn))
((/docs/v5/collections#whereinstrict whereInStrict))
((/docs/v5/collections#whereinloose whereInLoose))
((/docs/v5/collections#zip zip))

== Список методов ==

((#all))
**all()**

Метод %%all()%% возвращает заданный массив, представленный коллекцией:
%%
collect([1, 2, 3])->all();

// [1, 2, 3]
%%

((#avg)) 
**avg()**

Метод %%avg()%% возвращает среднее значение всех элементов в коллекции:
%%
collect([1, 2, 3, 4, 5])->avg();

// 3
%%

Если коллекция содержит вложенные массивы или объекты, то вы должны передать ключ, чтобы определить, среднее значение каких значений необходимо вычислить:
%%
$collection = collect([
  ['name' => 'JavaScript: The Good Parts', 'pages' => 176],
  ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);

$collection->avg('pages');

// 636
%%

((#chunk))
**chunk()**

Метод %%chunk()%% разбивает коллекцию на множество мелких коллекций заданного размера:
%%
$collection = collect([1, 2, 3, 4, 5, 6, 7]);

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

$chunks->toArray();

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

Этот метод особенно полезен в ((/docs/v5/views представлениях)) при работе с системой сеток, такой как ((https://getbootstrap.com/css/#grid Bootstrap)). Представьте, что у вас есть коллекция моделей ((/docs/v5/eloquent Eloquent)), которую вы хотите отобразить в сетке:
%%
@foreach ($products->chunk(3) as $chunk)
  <div class="row">
    @foreach ($chunk as $product)
      <div class="col-xs-4">{{ $product->name }}</div>
    @endforeach
  </div>
@endforeach
%%

((#collapse))
**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]
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
((#combine))
**combine()**

Метод %%combine()%% комбинирует ключи коллекции со значениями другого массива или коллекции:
~%%
$collection = collect(['name', 'age']);

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

$combined->all();

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

((#contains))
**contains()**

Метод %%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
%%

((#count))
**count()**

Метод %%count()%% возвращает общее количество элементов в коллекции:
%%
$collection = collect([1, 2, 3, 4]);

$collection->count();

// 4
%%

((#diff))
**diff()**

Метод %%diff()%% сравнивает одну коллекцию с другой коллекцией или с простым PHP %%array%% на основе их значений. Этот метод вернёт те значения исходной коллекции, которых нет в переданной для сравнения коллекции:
%%
$collection = collect([1, 2, 3, 4, 5]);

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

$diff->all();

// [1, 3, 5]
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
((#diffkeys))
**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]
~%%
%%

((#each))
**each()**

Метод %%each()%% перебирает элементы в коллекции и передает каждый элемент в функцию обратного вызова:
%%
$collection = $collection->each(function ($item, $key) {
  //
});
%%

Верните %%(t)false%% из функции обратного вызова, чтобы выйти из цикла:
%%
$collection = $collection->each(function ($item, $key) {
  if (/* ваше условие */) {
    return false;
  }
});
%%

((#every))
**every()**

Метод %%every()%% создает новую коллекцию, состоящую из каждого n-го элемента:
%%
$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);

$collection->every(4);

// ['a', 'e']
%%

Вы можете дополнительно передать смещение элементов вторым параметром:
%%
$collection->every(4, 1);

// ['b', 'f']
%%

((#except))
**except()**

Метод %%except()%% возвращает все элементы в коллекции, кроме тех, чьи ключи указаны в передаваемом массиве:
%%
$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);

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

$filtered->all();

// ['product_id' => 1]
%%

Метод ((#only only)) - инверсный методу %%except%%.

((#filter))
**filter()**

Метод %%filter()%% фильтрует коллекцию с помощью переданной функции обратного вызова, оставляя только те элементы, которые соответствуют заданному условию:
%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
~%%
$collection = collect([1, 2, 3, 4]);

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

$filtered->all();

// [3, 4]
~%%
%%

%%(DOCNEW 5.1=f60f8b3697b3ffe381df4ddb7e2875ffce940643 1.04.2016 17:39:10, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
~%%
$collection = collect([1, 2, 3, 4]);

$filtered = $collection->filter(function ($item) {
  return $item > 2;
});

$filtered->all();

// [3, 4]
~%%
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Если функция обратного вызова не указана, будут удалены все элементы коллекции, эквивалентные %%false%%:
~%%
$collection = collect([1, 2, 3, null, false, '', 0, []]);

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

// [1, 2, 3]
~%%
%%

Метод ((#reject reject() )) - инверсный методу %%filter()%%.

((#first))
**first()**

Метод %%first()%% возвращает первый элемент в коллекции, который подходит под заданное условие:
%%
collect([1, 2, 3, 4])->first(function ($value, $key) {
  return $value > 2;
});

// 3
%%

Также вы можете вызвать метод %%first()%% без параметров, чтобы получить первый элемент в коллекции. Если коллекция пуста, то вернётся %%null%%:
%%
collect([1, 2, 3, 4])->first();

// 1
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
((#flatmap))
**flatMap()**

Метод %%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))
**flatten()**

Метод %%flatten()%% преобразует многомерную коллекцию в одномерную:
%%
$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);

$flattened = $collection->flatten();

$flattened->all();

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

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
При необходимости вы можете передать в метод аргумент "глубины":
~%%
$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()%% без указания глубины, то вложенные массивы тоже "расплющатся", и получим %%(t)['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']%%. Глубина задаёт уровень вложенности массивов, ниже которого "расплющивать" не нужно.
%%

((#flip))
**flip()**

Метод %%flip()%% меняет местами ключи и значения в коллекции:
%%
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$flipped = $collection->flip();

$flipped->all();

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

((#forget))
**forget()**

Метод %%forget()%% удаляет элемент из коллекции по его ключу:
%%
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);

$collection->forget('name');

$collection->all();

// ['framework' => 'laravel']
%%

.(alert)
В отличие от большинства других методов коллекции, %%forget()%% не возвращает новую модифицированную коллекцию. Он изменяет коллекцию при вызове.

((#forPage))
**forPage()**

Метод %%forPage()%% возвращает новую коллекцию, содержащую элементы, которые будут присутствовать на странице с заданным номером. Первый аргумент метода - номер страницы, второй аргумент - число элементов для вывода на странице:
%%
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);

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

$chunk->all();

// [4, 5, 6]
%%

((#get))
**get()**

Метод %%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))
**groupBy()**

Метод %%groupBy()%% группирует элементы коллекции по заданному ключу:
%%
$collection = collect([
  ['account_id' => 'account-x10', 'product' => 'Chair'],
  ['account_id' => 'account-x10', 'product' => 'Bookcase'],
  ['account_id' => 'account-x11', 'product' => 'Desk'],
]);

$grouped = $collection->groupBy('account_id');

$grouped->toArray();

/*
  [
    'account-x10' => [
      ['account_id' => 'account-x10', 'product' => 'Chair'],
      ['account_id' => 'account-x10', 'product' => 'Bookcase'],
    ],
    'account-x11' => [
      ['account_id' => 'account-x11', 'product' => 'Desk'],
    ],
  ]
*/
%%

В дополнение к передаваемой строке %%(t)key%%, вы можете также передать функцию обратного вызова. Она должна возвращать значение, по которому вы хотите группировать:
%%
$grouped = $collection->groupBy(function ($item, $key) {
  return substr($item['account_id'], -3);
});

$grouped->toArray();

/*
  [
    'x10' => [
      ['account_id' => 'account-x10', 'product' => 'Chair'],
      ['account_id' => 'account-x10', 'product' => 'Bookcase'],
    ],
    'x11' => [
      ['account_id' => 'account-x11', 'product' => 'Desk'],
    ],
  ]
*/
%%

((#has))
**has()**

Метод %%has()%% определяет, существует ли заданный ключ в коллекции:
%%
$collection = collect(['account_id' => 1, 'product' => 'Desk']);

$collection->has('product');

// true
%%

((#implode))
**implode()**

Метод %%implode()%% соединяет элементы в коллекции. Его параметры зависят от типа элементов в коллекции. Если коллекция содержит массивы или объекты, вы должны передать ключ атрибутов, значения которых вы хотите соединить, и "промежуточную" строку, которую вы хотите поместить между значениями:
%%
$collection = collect([
  ['account_id' => 1, 'product' => 'Desk'],
  ['account_id' => 2, 'product' => 'Chair'],
]);

$collection->implode('product', ', ');

// Desk, Chair
%%

Если коллекция содержит простые строки или числовые значения, просто передайте только "промежуточный" параметр в метод:
%%
collect([1, 2, 3, 4, 5])->implode('-');

// '1-2-3-4-5
%%

((#intersect))
**intersect()**

Метод %%Intersect()%% удаляет любые значения из исходной коллекции, которых нет в переданном массиве или коллекции. Результирующая коллекция сохранит ключи оригинальной коллекции:
%%
$collection = collect(['Desk', 'Sofa', 'Chair']);

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

$intersect->all();

// [0 => 'Desk', 2 => 'Chair']
%%

((#isEmpty))
**isEmpty()**

Метод %%isEmpty()%% возвращает %%(t)true%%, если коллекция пуста. В противном случае вернётся %%(t)false%%:
%%
collect([])->isEmpty();

// true
%%

((#keyBy))
**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 ($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))
**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()**

Метод %%last()%% возвращает последний элемент в коллекции, для которого выполняется заданное условие:
%%
collect([1, 2, 3, 4])->last(function ($value, $key) {
  return $value < 3;
});

// 2
%%

Также вы можете вызвать метод %%last()%% без параметров, чтобы получить последний элемент в коллекции. Если коллекция пуста, то вернётся %%null%%:
%%
collect([1, 2, 3, 4])->last();

// 4
%%

((#map))
**map()**

Метод %%map()%% перебирает коллекцию и передаёт каждое значению в функцию обратного вызова. Функция обратного вызова может свободно изменять элемент и возвращать его, формируя тем самым новую коллекцию измененных элементов:
%%
$collection = collect([1, 2, 3, 4, 5]);

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

$multiplied->all();

// [2, 4, 6, 8, 10]
%%

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

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
((#mapwithkeys))
**mapWithKeys()**

Метод %%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))
**max()**

Метод %%max()%% возвращает максимальное значение по заданному ключу:
%%
$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');

// 20

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

// 5
%%

((#merge))
**merge()**

Метод %%merge()%% добавляет указанный массив в исходную коллекцию. Значения исходной коллекции, имеющие тот же строковый ключ, что и значение в массиве, будут перезаписаны:
%%
$collection = collect(['product_id' => 1, 'price' => 100]);

$merged = $collection->merge(['price' => 200, 'discount' => false]);

$merged->all();

// ['product_id' => 1, 'price' => 200, 'discount' => false]
%%

Если заданные ключи в массиве числовые, то значения будут добавляться в конец коллекции:
%%
$collection = collect(['Desk', 'Chair']);

$merged = $collection->merge(['Bookcase', 'Door']);

$merged->all();

// ['Desk', 'Chair', 'Bookcase', 'Door']
%%

((#min))
**min()**

Метод %%min()%% возвращает минимальное значение по заданному ключу:
%%
$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');

// 10

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

// 1
%%

((#only))
**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']
%%

Метод ((#except except() )) - инверсный для метода %%only()%%.

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
((#pipe))
**pipe()**

Метод %%pipe()%% передаёт коллекцию в функцию замыкание и возвращает результат:
~%%
$collection = collect([1, 2, 3]);

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

// 6
~%%
%%

((#pluck))
**pluck()**

Метод %%pluck()%% извлекает все значения по заданному ключу:
%%
 $collection = collect([
  ['product_id' => 'prod-100', 'name' => 'Desk'],
  ['product_id' => 'prod-200', 'name' => 'Chair'],
]);

$plucked = $collection->pluck('name');

$plucked->all();

// ['Desk', 'Chair']
%%

Также вы можете указать, с каким ключом вы хотите получить коллекцию:
%%
$plucked = $collection->pluck('name', 'product_id');

$plucked->all();

// ['prod-100' => 'Desk', 'prod-200' => 'Chair']
%%

((#pop))
**pop()**

Метод %%pop()%% удаляет и возвращает последний элемент из коллекции:
%%
$collection = collect([1, 2, 3, 4, 5]);

$collection->pop();

// 5

$collection->all();

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

((#prepend))
**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()**

Метод %%pull()%% удаляет и возвращает элемент из коллекции по его ключу:
%%
$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);

$collection->pull('name');

// 'Desk'

$collection->all();

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

((#push))
**push()**

Метод %%push()%% добавляет элемент в конец коллекции:
%%
$collection = collect([1, 2, 3, 4]);

$collection->push(5);

$collection->all();

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

((#put))
**put()**

Метод %%put()%% устанавливает заданный ключ и значение в коллекцию:
%%
$collection = collect(['product_id' => 1, 'name' => 'Desk']);

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

$collection->all();

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

((#random))
**random()**

Метод %%random()%% возвращает случайный элемент из коллекции:
%%
$collection = collect([1, 2, 3, 4, 5]);

$collection->random();

// 4 - (получен в случайном порядке)
%%

Также вы можете передать целое число в %%random()%%, чтобы указать, сколько случайных элементов необходимо получить. Если это число больше, чем %%(t)1%%, то возвращается коллекция элементов:
%%
$random = $collection->random(3);

$random->all();

// [2, 4, 5] - (получены в случайном порядке)
%%

((#reduce))
**reduce()**

Метод %%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))
**reject()**

Метод %%reject()%% фильтрует коллекцию, используя заданную функцию обратного вызова. Функция обратного вызова должна возвращать %%(t)true%% для элементов, которые необходимо удалить из результирующей коллекции:
%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
~%%
$collection = collect([1, 2, 3, 4]);

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

$filtered->all();

// [1, 2]
~%%
%%

%%(DOCNEW 5.1=f60f8b3697b3ffe381df4ddb7e2875ffce940643 1.04.2016 17:39:10, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
~%%
$collection = collect([1, 2, 3, 4]);

$filtered = $collection->reject(function ($item) {
  return $item > 2;
});

$filtered->all();

// [1, 2]
~%%
%%

Метод ((#filter filter() )) - инверсный для метода %%reject()%%.

((#reverse))
**reverse()**

Метод %%reverse()%% меняет порядок элементов коллекции:
%%
$collection = collect([1, 2, 3, 4, 5]);

$reversed = $collection->reverse();

$reversed->all();

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

((#search))
**search()**

Метод %%search()%% ищет в коллекции заданное значение и возвращает его ключ при успешном поиске. Если элемент не найден, то возвращается %%(t)false%%.
%%
$collection = collect([2, 4, 6, 8]);

$collection->search(4);

// 1
%%

Поиск проводится с помощью "неточного" сравнения, то есть строка с числовым значением будет считаться равной числу с таким же значением. Чтобы использовать строгое сравнение, передайте %%(t)true%% вторым параметром метода:
%%
$collection->search('4', true);

// false
%%

В качестве альтернативы, вы можете передать свою собственную функцию обратного вызова для поиска первого элемента, для которого выполняется ваше условие:
%%
$collection->search(function ($item, $key) {
  return $item > 5;
});

// 2
%%

((#shift))
**shift()**

Метод %%shift()%% удаляет и возвращает первый элемент из коллекции:
%%
$collection = collect([1, 2, 3, 4, 5]);

$collection->shift();

// 1

$collection->all();

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

((#shuffle))
**shuffle()**

Метод %%shuffle()%% перемешивает элементы в коллекции случайным образом:
%%
$collection = collect([1, 2, 3, 4, 5]);

$shuffled = $collection->shuffle();

$shuffled->all();

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

((#slice))
**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]
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Полученная часть коллекции сохранит оригинальные ключи. Если вы не хотите сохранять оригинальные ключи, то можете использовать метод %%values()%%, чтобы переиндексировать их.
%%

%%(DOCNEW 5.1=f60f8b3697b3ffe381df4ddb7e2875ffce940643 1.04.2016 17:39:10, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Полученная часть коллекции будет иметь новые числовые проиндексированные ключи. Если вы хотите сохранить оригинальные ключи, передайте %%(t)true%% третьим параметром в метод.
%%

((#sort))
**sort()**

Метод %%sort()%% сортирует коллекцию. Отсортированная коллекция сохраняет оригинальные ключи массива, поэтому в этом примере мы используем метод ((#values values() )) для сброса ключей и последовательной нумерации индексов:
%%
$collection = collect([5, 3, 1, 2, 4]);

$sorted = $collection->sort();

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

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

Если вам необходимо отсортировать коллекцию с дополнительными условиями, вы можете передать функцию обратного вызова в метод %%sort()%% с вашим собственным алгоритмом. Найдите в документации по PHP метод ((https://secure.php.net/manual/en/function.usort.php#refsect1-function.usort-parameters usort)), который вызывается внутри метода %%sort()%% вашей коллекции.

.(alert)
Для сортировки коллекции вложенных массивов или объектов, смотрите методы ((#sortby sortBy() )) и ((#sortbydesc sortByDesc() )).

((#sortBy))
**sortBy()**

Метод %%sortBy()%% сортирует коллекцию по заданному ключу. Отсортированная коллекция сохраняет оригинальные ключи массива, поэтому в этом примере мы используем метод ((#values 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([
  ['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))
**sortByDesc()**

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

((#splice))
**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]
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
((#split))
**split()**

Метод %%split()%% разбивает коллекцию на заданное число групп:
~%%
$collection = collect([1, 2, 3, 4, 5]);

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

$groups->toArray();

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

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

// 6
%%

((#take))
**take()**

Метод %%take()%% возвращает новую коллекцию с заданным числом элементов:
%%
$collection = collect([0, 1, 2, 3, 4, 5]);

$chunk = $collection->take(3);

chunk->all();

// [0, 1, 2]
%%

Также вы можете передать отрицательное целое число, чтобы получить определенное количество элементов с конца коллекции:
%%
$collection = collect([0, 1, 2, 3, 4, 5]);

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

$chunk->all();

// [4, 5]
%%

((#toarray))
**toArray()**

Метод %%toArray()%% преобразует коллекцию в простой PHP %%array%%. Если значения коллекции являются моделями ((/docs/v5/eloquent Eloquent)), то модели также будут преобразованы в массивы:
%%
$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toArray();

/*
  [
    ['name' => 'Desk', 'price' => 200],
  ]
*/
%%

.(alert)
Метод %%toArray()%% также преобразует все вложенные объекты коллекции в массив. Если вы хотите получить базовый массив, используйте вместо этого метод ((#all all() )).

((#tojson))
**toJson()**

Метод %%toJson()%% преобразует коллекцию в JSON:
%%
$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toJson();

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

((#transform))
**transform()**

Метод %%transform()%% перебирает коллекцию и вызывает заданную функцию обратного вызова для каждого элемента коллекции. Элементы коллекции будут заменены на значения, полученный из функции обратного вызова:
%%
$collection = collect([1, 2, 3, 4, 5]);

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

$collection->all();

// [2, 4, 6, 8, 10]
%%

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

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
((#union))
**union()**

Метод %%union()%% добавляет данный массив в коллекцию. Если массив содержит ключи, которые уже есть в исходной коллекции, то будут оставлены значения исходной коллекции:
~%%
$collection = collect([1 => ['a'], 2 => ['b']]);

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

$union->all();

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

((#unique))
**unique()**

Метод %%unique()%% возвращает все уникальные элементы в коллекции. Полученная коллекция сохраняет оригинальные ключи массива, поэтому в этом примере мы используем метод ((#values 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'],
  ]
*/
%%

((#values))
**values()**

Метод %%values()%% возвращает новую коллекцию со сброшенными ключами и последовательно пронумерованными индексами:
%%
$collection = collect([
  10 => ['product' => 'Desk', 'price' => 200],
  11 => ['product' => 'Desk', 'price' => 200]
]);

$values = $collection->values();

$values->all();

/*
  [
    0 => ['product' => 'Desk', 'price' => 200],
    1 => ['product' => 'Desk', 'price' => 200],
  ]
*/
%%

((#where))
**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],
]
*/
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Метод %%where()%% использует "неточное" сравнение при проверке значений элементов. Используйте метод ((#wherestrict whereStrict() )) для фильтрации с использованием строгого сравнения.

((#wherestrict))
**whereStrict()**

Этот метод имеет такую же сигнатуру, что и метод %%where()%%. Однако, все значения сравниваются с использованием строгого сравнения.
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Метод %%where()%% использует строгое сравнение при проверке значений элементов. Используйте метод ((#whereloose whereLoose() )) для фильтрации с использованием "неточного" сравнения.

((#whereloose))
**whereLoose()**

Этот метод имеет такую же сигнатуру, что и метод %%where()%%. Однако, все значения сравниваются с использованием "неточного" сравнения.
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
((#wherein))
**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' => 'Bookcase', 'price' => 150],
  ['product' => 'Desk', 'price' => 200],
]
*/
~%%
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Метод %%whereIn()%% использует "неточное" сравнение при проверке значений элементов. Используйте метод ((#whereinstrict whereInStrict() )) для фильтрации с использованием строгого сравнения.

((#whereinstrict))
**whereInStrict()**

Этот метод имеет такую же сигнатуру, что и метод %%whereIn()%%. Однако, все значения сравниваются с использованием строгого сравнения.
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Метод %%whereIn()%% использует строгое сравнение при проверке значений элементов. Используйте метод ((#whereinloose whereInLoose() )) для фильтрации с использованием "неточного" сравнения.

((#whereinloose))
**whereInLoose()**

Этот метод имеет такую же сигнатуру, что и метод %%whereIn()%%. Однако, все значения сравниваются с использованием "неточного" сравнения.
%%

((#zip))
**zip()**

Метод %%zip()%% объединяет все значения заданного массива со значениями исходной коллекции на соответствующем индексе:
%%
$collection = collect(['Chair', 'Desk']);

$zipped = $collection->zip([100, 200]);

$zipped->all();

// [['Chair', 100], ['Desk', 200]]
%%