Интерфейс CollectionInterface

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Пример:

$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 значениями не считаются пустыми.

Параметры

Возвращает

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

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

Возвращает

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

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

Пример

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

Параметры

Возвращает

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

Пример:

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

Параметры

Возвращает

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

Пример:

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

Параметры

Возвращает

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

Примеры:

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

Параметры

Возвращает

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

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

Пример:

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

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

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

Параметры

Возвращает

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

Параметры

Возвращает

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

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

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

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

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

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

В частности, любая коллекция, обертывающая генератор (функцию с оператором yield) или небуферизованный курсор базы данных, не примет никаких других вызовов функций после вызова count() на ней.

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

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

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

Если вам нужен счёт элементов с учётом ключей (количество уникальных ключей), вы можете вызвать 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, если все значения в этом наборе проходят проверку истинности, заданную в обратном вызове.

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

Пример:

$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, если любое из значений в этой коллекции проходит проверку истинности, указанную в обратном вызове.

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

Пример:

$hasYoungPeople = (new Collection([24, 45, 15]))->every(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();
});

Параметры

Возвращает

Возвращает ближайший вложенный итератор, который можно безопасно пройти, не теряя никаких возможных преобразований. Это используется в основном для удаления пустых обёрток 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)]

Параметры

Возвращает