Интерфейс 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(), чтобы обойти эту проблему.

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

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

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

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

Можно вернуть все элементы снизу вверх с помощью алгоритма обхода в ширину, передав параметр '$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;
}

Параметры

Возвращает

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

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

Пример:

Получение массива строк в файле 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)]

Параметры

Возвращает