Класс Collection

Конструктор. Вы можете предоставить массив или любой итерируемый объект

Parameters

Throws

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

Returns

Возвращает массив для сериализации этого объекта.

Returns

Восстанавливает экземпляр Collection.

Parameters

Returns

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

Parameters

Returns

Возвращает столбец из $data, который может быть извлечен путем итерации по именам столбцов, содержащимся в $path. Он будет возвращать массивы для элементов, представленных с помощью {*}

Parameters

Returns

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

Parameters

Returns

Возвращает столбец из $data, который может быть извлечен путем итерации по именам столбцов, содержащимся в $path

Parameters

Returns

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

Parameters

Returns

Добавляет один элемент, создавая новую коллекцию.

Parameters

Returns

Возвращает среднее значение всех значений, извлеченных с помощью $path или из этой коллекции.

Example:

$items = [
 ['invoice' => ['total' => 100]],
 ['invoice' => ['total' => 200]]
];

$total = (new Collection($items))->avg('invoice.total');

// Total: 150

$total = (new Collection([1, 2, 3]))->avg();
// Total: 2

Среднее значение пустого набора или 0 строк равно null. Коллекции со значениями null не считаются пустыми.

Parameters

Returns

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

Это также можно использовать для того, чтобы любой неперематываемый итератор стал перематываемым.

Returns

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

Для создания декартова произведения коллекция должна содержать одно измерение данных.

Example

$collection = new Collection([['A', 'B', 'C'], [1, 2, 3]]);
$result = $collection->cartesianProduct()->toArray();
$expected = [
    ['A', 1],
    ['A', 2],
    ['A', 3],
    ['B', 1],
    ['B', 2],
    ['B', 3],
    ['C', 1],
    ['C', 2],
    ['C', 3],
];

Parameters

Returns

Throws

Разбивает коллекцию на меньшие массивы заданного размера.

Example:

$items [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
$chunked = (new Collection($items))->chunk(3)->toList();
// Returns [[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11]]

Parameters

Returns

Разбивает коллекцию на меньшие массивы заданного размера.

Example:

$items ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5, 'f' => 6];
$chunked = (new Collection($items))->chunkWithKeys(3)->toList();
// Returns [['a' => 1, 'b' => 2, 'c' => 3], ['d' => 4, 'e' => 5, 'f' => 6]]

Parameters

Returns

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

Examples:

$items = [
 ['id' => 1, 'name' => 'foo', 'parent' => 'a'],
 ['id' => 2, 'name' => 'bar', 'parent' => 'b'],
 ['id' => 3, 'name' => 'baz', 'parent' => 'a'],
];

$combined = (new Collection($items))->combine('id', 'name');

// Result will look like this when converted to array
[
 1 => 'foo',
 2 => 'bar',
 3 => 'baz',
];

$combined = (new Collection($items))->combine('id', 'name', 'parent');

// Result will look like this when converted to array
[
 'a' => [1 => 'foo', 3 => 'baz'],
 'b' => [2 => 'bar']
];

Parameters

Returns

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

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

Example:

$collection->map($mapper)->sortBy('age')->extract('name');
$compiled = $collection->compile();
$isJohnHere = $compiled->some($johnMatcher);
$allButJohn = $compiled->filter($johnMatcher);

В приведенном выше примере, если бы коллекция не была скомпилирована ранее, итерации для map, sortBy и extract были бы выполнены дважды: один раз для получения $isJohnHere и один раз для $allButJohn

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

Parameters

Returns

Возвращает true, если $value присутствует в этой коллекции. Сравнения выполняются как по значению, так и по типу.

Parameters

Returns

Возвращает количество элементов в коллекции.

ПРЕДУПРЕЖДЕНИЯ:

Изменяет текущую позицию итератора:

Вызов этого метода во время итерации по этой коллекции, например, в цикле foreach, приведет к неопределенному поведению. Избегайте этого.

Потребляет все элементы для коллекций NoRewindIterator:

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

Для решения этой проблемы создайте новую коллекцию с помощью метода buffered()

Может сообщать о большем количестве элементов, чем уникальных ключей:

Любая коллекция, составленная путем объединения коллекций или содержащая внутренние итераторы, возвращающие дублирующие ключи, будет сообщать о большем количестве элементов с помощью этой функции, чем фактическое количество элементов при преобразовании коллекций в массив с ключами. Это происходит потому, что дублирующие ключи сводятся к одному в конечном массиве, в то время как этот метод подсчета учитывает только количество элементов после преобразования в обычный список.

Если вам нужно количество элементов с учетом ключей (количество уникальных ключей), вы можете вызвать countKeys()

Возвращает

Сортирует список по группам и возвращает количество элементов в каждой группе. Аналогично groupBy, но вместо возвращения списка значений возвращает количество значений в каждой группе.

Если $callback является строкой, это должно быть имя свойства для извлечения или путь через свойства, разделенные точкой, для получения последнего свойства в пути.

Пример:

$items = [
 ['id' => 1, 'name' => 'foo', 'parent_id' => 10],
 ['id' => 2, 'name' => 'bar', 'parent_id' => 11],
 ['id' => 3, 'name' => 'baz', 'parent_id' => 10],
];

$group = (new Collection($items))->countBy('parent_id');

// Or
$group = (new Collection($items))->countBy(function ($e) {
 return $e['parent_id'];
});

// Result will look like this when converted to array
[
 10 => 2,
 11 => 1
];

Параметры

Возвращает

Возвращает количество уникальных ключей в этом итераторе. Это равно количеству элементов в коллекции после вызова toArray()

Этот метод имеет ряд ограничений. Подробности см. в CollectionInterface::count()

Возвращает

Применяет коллбек к элементам в этой коллекции.

Пример:

$collection = (new Collection($items))->each(function ($value, $key) {
 echo "Element $key: $value";
});

Параметры

Возвращает

Возвращает true, если все значения в этой коллекции проходят проверку, заданную в коллбеке.

Коллбек получает значение и ключ проверяемого элемента и должен вернуть true, если проверка прошла успешно.

Пример:

$overTwentyOne = (new Collection([24, 45, 60, 15]))->every(function ($value, $key) {
 return $value > 21;
});

Пустые коллекции всегда возвращают true.

Параметры

Возвращает

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

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

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

Пример:

Извлечение имени пользователя для всех комментариев в массиве:

$items = [
 ['comment' => ['body' => 'cool', 'user' => ['name' => 'Mark']],
 ['comment' => ['body' => 'very cool', 'user' => ['name' => 'Renan']]
];
$extracted = (new Collection($items))->extract('comment.user.name');

// Result will look like this when converted to array
['Mark', 'Renan']

Также можно извлечь уплощенную коллекцию из вложенных свойств

$items = [
     ['comment' => ['votes' => [['value' => 1], ['value' => 2], ['value' => 3]]],
     ['comment' => ['votes' => [['value' => 4]]
];
$extracted = (new Collection($items))->extract('comment.votes.{*}.value');

// Result will contain
[1, 2, 3, 4]

Параметры

Возвращает

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

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

Пример:

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

$collection = (new Collection([1, 2, 3]))->filter(function ($value, $key) {
 return $value % 2 === 0;
});

Параметры

Возвращает

Возвращает первый результат в этой коллекции

Возвращает

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

Параметры

Возвращает

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

Если $callback является строкой, это должно быть имя свойства для извлечения или путь через свойства, разделенные точкой, для получения последнего свойства в пути.

Пример:

$items = [
 ['id' => 1, 'name' => 'foo', 'parent_id' => 10],
 ['id' => 2, 'name' => 'bar', 'parent_id' => 11],
 ['id' => 3, 'name' => 'baz', 'parent_id' => 10],
];

$group = (new Collection($items))->groupBy('parent_id');

// Or
$group = (new Collection($items))->groupBy(function ($e) {
 return $e['parent_id'];
});

// Result will look like this when converted to array
[
 10 => [
     ['id' => 1, 'name' => 'foo', 'parent_id' => 10],
     ['id' => 3, 'name' => 'baz', 'parent_id' => 10],
 ],
 11 => [
     ['id' => 2, 'name' => 'bar', 'parent_id' => 11],
 ]
];

Параметры

Возвращает

Принимает список и функцию коллбек, возвращающую ключ для каждого элемента в списке (или имя свойства), возвращает объект с индексом каждого элемента. Похоже на groupBy, но для случаев, когда ключи уникальны.

Если $callback является строкой, это должно быть имя свойства для извлечения или путь через свойства, разделенные точкой, для получения последнего свойства в пути.

Пример:

$items = [
 ['id' => 1, 'name' => 'foo'],
 ['id' => 2, 'name' => 'bar'],
 ['id' => 3, 'name' => 'baz'],
];

$indexed = (new Collection($items))->indexBy('id');

// Or
$indexed = (new Collection($items))->indexBy(function ($e) {
 return $e['id'];
});

// Result will look like this when converted to array
[
 1 => ['id' => 1, 'name' => 'foo'],
 3 => ['id' => 3, 'name' => 'baz'],
 2 => ['id' => 2, 'name' => 'bar'],
];

Параметры

Возвращает

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

Значение $path может быть именем свойства или путем через свойства, разделенными точкой, для получения последнего свойства в пути.

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

Пример:

Вставка возрастов в коллекцию, содержащую пользователей:

$items = [
 ['comment' => ['body' => 'cool', 'user' => ['name' => 'Mark']],
 ['comment' => ['body' => 'awesome', 'user' => ['name' => 'Renan']]
];
$ages = [25, 28];
$inserted = (new Collection($items))->insert('comment.user.age', $ages);

// Result will look like this when converted to array
[
 ['comment' => ['body' => 'cool', 'user' => ['name' => 'Mark', 'age' => 25]],
 ['comment' => ['body' => 'awesome', 'user' => ['name' => 'Renan', 'age' => 28]]
];

Параметры

Возвращает

Возвращает, есть ли элементы в этой коллекции

Пример:

$items [1, 2, 3];
(new Collection($items))->isEmpty(); // false

(new Collection([]))->isEmpty(); // true

Возвращает

Возвращает данные, которые можно преобразовать в JSON. Это возвращает те же данные, что и toArray(), содержащие только уникальные ключи.

Часть интерфейса JsonSerializable.

Возвращает

Возвращает последний результат в этой коллекции

Возвращает

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

Ленивая коллекция может быть итерирована только один раз. Вторая попытка приводит к ошибке.

Возвращает

Возвращает новую коллекцию с каждым из элементов этой коллекции после сплющивания структуры дерева. Структура дерева определяется вложением элементов под ключом с известным именем. Это имя можно указать, используя параметр '$nestingKey'.

По умолчанию будут возвращены все элементы в дереве, следуя поиске в глубину (Depth First Search), то есть элементы от верхнего родителя к листьям для каждой ветви.

Можно вернуть все элементы снизу вверх, используя подход поиска в ширину (Breadth First Search), передав параметр '$dir' со значением 'asc'. То есть, он вернёт все элементы для каждой глубины дерева сначала и снизу вверх.

Наконец, вы можете указать, чтобы получить только коллекцию с узлами-листьями в структуре дерева. Для этого передайте 'leaves' в первом аргументе.

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

• desc: RecursiveIteratorIterator::SELF_FIRST
• asc: RecursiveIteratorIterator::CHILD_FIRST
• leaves: RecursiveIteratorIterator::LEAVES_ONLY

Пример:

$collection = new Collection([
 ['id' => 1, 'children' => [['id' => 2, 'children' => [['id' => 3]]]]],
 ['id' => 4, 'children' => [['id' => 5]]]
]);
$flattenedIds = $collection->listNested()->extract('id'); // Yields [1, 2, 3, 4, 5]

Параметры

Возвращает

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

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

Пример:

Получение коллекции булевых значений, где true указывает, является ли человек женщиной:

$collection = (new Collection($people))->map(function ($person, $key) {
 return $person->gender === 'female';
});

Параметры

Возвращает

Просматривает каждое значение в списке, возвращая коллекцию всех значений, содержащих все пары ключ-значение, перечисленные в $conditions.

Пример:

$items = [
 ['comment' => ['body' => 'cool', 'user' => ['name' => 'Mark']],
 ['comment' => ['body' => 'very cool', 'user' => ['name' => 'Renan']]
];

$extracted = (new Collection($items))->match(['user.name' => 'Renan']);

// Result will look like this when converted to array
[
 ['comment' => ['body' => 'very cool', 'user' => ['name' => 'Renan']]
]

Параметры

Возвращает

Возвращает наибольший элемент в этой коллекции после сортировки по свойству. См. метод sortBy для получения информации об обратном вызове и параметре $sort.

Примеры:

// For a collection of employees
$max = $collection->max('age');
$max = $collection->max('user.salary');
$max = $collection->max(function ($e) {
 return $e->get('user')->get('salary');
});

// Display employee name
echo $max->name;

Параметры

Возвращает

Возвращает медиану всех значений, извлеченных с помощью $path, или этой коллекции.

Пример:

$items = [
 ['invoice' => ['total' => 400]],
 ['invoice' => ['total' => 500]]
 ['invoice' => ['total' => 100]]
 ['invoice' => ['total' => 333]]
 ['invoice' => ['total' => 200]]
];

$total = (new Collection($items))->median('invoice.total');

// Total: 333

$total = (new Collection([1, 2, 3, 4]))->median();
// Total: 2.5

Медиана пустого набора или 0 строк — null. Коллекции с null значениями не считаются пустыми.

Параметры

Возвращает

Возвращает наименьший элемент в этой коллекции после сортировки по свойству. См. метод sortBy для получения информации об обратном вызове и параметре $sort.

Примеры:

// For a collection of employees
$min = $collection->min('age');
$min = $collection->min('user.salary');
$min = $collection->min(function ($e) {
 return $e->get('user')->get('salary');
});

// Display employee name
echo $min->name;

Параметры

Возвращает

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

Параметры

Возвращает

Возвращает новую коллекцию.

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

Параметры

Возвращает

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

Возвращает

Добавляет набор элементов в начало коллекции, создавая новую коллекцию.

Параметры

Возвращает

Добавляет один элемент в начало, создавая новую коллекцию.

Параметры

Возвращает

Складывает значения в этой коллекции в одно значение, как результат применения функции обратного вызова ко всем элементам. $zero — начальное состояние редукции, и каждый последующий шаг должен возвращаться функцией обратного вызова. Если $zero опущен, первое значение коллекции будет использовано вместо него, и редукция начнется со второго элемента.

Параметры

Возвращает

Просматривает каждое значение в коллекции и возвращает другую коллекцию со всеми значениями, которые не проходят проверку истинности. Это противоположно filter.

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

Пример:

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

$collection = (new Collection([1, 2, 3]))->reject(function ($value, $key) {
 return $value % 2 === 0;
});

Параметры

Возвращает

Возвращает новую коллекцию с максимальным $size случайным элементом из этой коллекции.

Параметры

Возвращает

Возвращает строковое представление этого объекта, которое можно использовать для его восстановления.

Возвращает

Возвращает новую коллекцию с элементами в случайном порядке. Эта функция не сохраняет исходные ключи в коллекции.

Возвращает

Возвращает новую коллекцию, которая пропустит указанное количество элементов в начале итерации.

Параметры

Возвращает

Возвращает true, если хотя бы одно из значений в этом наборе данных удовлетворяет условию, заданному в обратном вызове.

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

Пример:

$hasYoungPeople = (new Collection([24, 45, 15]))->some(function ($value, $key) {
 return $value < 21;
});

Параметры

Возвращает

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

Обратный вызов будет получать в качестве первого аргумента каждый элемент в $items, возвращаемое значение обратного вызова будет использовано в качестве значения для сортировки данного элемента. Обратите внимание, что функция обратного вызова может быть вызвана более одного раза для одного элемента.

Пример:

$items = $collection->sortBy(function ($user) {
 return $user->age;
});

// alternatively
$items = $collection->sortBy('age');

// or use a property path
$items = $collection->sortBy('department.name');

// output all user name order by their age in descending order
foreach ($items as $user) {
 echo $user->name;
}

Параметры

Возвращает

Создаёт новый набор данных, который при итерации перестанет возвращать результаты, если предоставленное условие станет истинным.

Это полезно для работы с бесконечными итераторами или любым генератором, который может начать возвращать некорректные элементы в определённый момент. Например, при чтении строк из потока файла вы можете остановить итерацию после достижения определённого значения.

Пример:

Получение массива строк из CSV-файла до тех пор, пока столбец со временем не будет меньше заданной даты

$lines = (new Collection($fileLines))->stopWhen(function ($value, $key) {
 return (new DateTime($value))->format('Y') < 2012;
})
->toArray();

Получение элементов до тех пор, пока не будет найден первый неутверждённый сообщение:

$comments = (new Collection($comments))->stopWhen(['is_approved' => false]);

Параметры

Возвращает

Возвращает сумму всех значений, извлечённых с помощью $matcher, или всего набора данных.

Пример:

$items = [
 ['invoice' => ['total' => 100]],
 ['invoice' => ['total' => 200]]
];

$total = (new Collection($items))->sumOf('invoice.total');

// Total: 300

$total = (new Collection([1, 2, 3]))->sumOf();
// Total: 6

Параметры

Возвращает

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

Параметры

Возвращает

Возвращает последние N элементов набора данных

Пример:

$items = [1, 2, 3, 4, 5];

$last = (new Collection($items))->takeLast(3);

// Result will look like this when converted to array
[3, 4, 5];

Параметры

Возвращает

Пропускает этот набор данных через вызываемый объект в качестве первого аргумента. Это полезно для добавления к всему набору данных другого объекта.

Пример:

$items = [1, 2, 3];
$decorated = (new Collection($items))->through(function ($collection) {
     return new MyCustomCollection($collection);
});

Параметры

Возвращает

Возвращает массив результатов

Параметры

Возвращает

Возвращает массив результатов с числовыми индексами. Это эквивалентно вызову toArray(false)

Возвращает

Транспонирует строки и столбцы в столбцы и строки

Пример:

$items = [
      ['Products', '2012', '2013', '2014'],
      ['Product A', '200', '100', '50'],
      ['Product B', '300', '200', '100'],
      ['Product C', '400', '300', '200'],
]

$transpose = (new Collection($items))->transpose()->toList();

// Returns
// [
//     ['Products', 'Product A', 'Product B', 'Product C'],
//     ['2012', '200', '300', '400'],
//     ['2013', '100', '200', '300'],
//     ['2014', '50', '100', '200'],
// ]

Возвращает

Исключения

Создаёт новый набор данных, где элементы являются конкатенацией списков элементов, сгенерированных функцией преобразования, применённой к каждому элементу исходного набора данных.

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

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

Пример:

$items [[1, 2, 3], [4, 5]];
$unfold = (new Collection($items))->unfold(); // Returns [1, 2, 3, 4, 5]

Использование функции преобразования

$items [1, 2, 3];
$allItems = (new Collection($items))->unfold(function ($page) {
 return $service->fetchPage($page)->toArray();
});

Параметры

Возвращает

Десериализует переданную строку и восстанавливает экземпляр Collection

Параметры

Возвращает

Возвращает ближайший вложенный итератор, который можно безопасно перебрать, не теряя возможных преобразований. Это используется в основном для удаления пустых обёрток IteratorIterator, которые могут только замедлять процесс итерации.

Возвращает

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

Пример:

$collection = new Collection([1, 2]);
$collection->zip([3, 4], [5, 6])->toList(); // returns [[1, 3, 5], [2, 4, 6]]

Параметры

Возвращает

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

Результирующий элемент будет являться возвращаемым значением функции $callable.

Пример:

$collection = new Collection([1, 2]);
$zipped = $collection->zipWith([3, 4], [5, 6], function (...$args) {
  return array_sum($args);
});
$zipped->toList(); // returns [9, 12]; [(1 + 3 + 5), (2 + 4 + 6)]

Параметры

Возвращает