Класс ResultSet

Конструктор

Параметры

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

Возвращает

Сериализует результат набора.

Возвращает

Десериализует результат набора.

Параметры

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

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

Параметры

Возвращает

Возвращает количество строк в наборе результатов.

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

Возвращает

Группирует элементы списка и возвращает счёт элементов в каждой группе. Аналогично 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().

Возвращает

Возвращает текущую запись в итераторе результатов.

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

Возвращает

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

Пример:

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

Параметры

Возвращает

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

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

Если столбец или свойство не могут быть найдены для конкретного элемента в наборе, в эту позицию вставляется 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]]
];

Параметры

Возвращает

Возвращает true, если в этом наборе нет элементов.

Пример:

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

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

Возвращает

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

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

Возвращает

Возвращает ключ текущей записи в итераторе

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

Возвращает

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

Возвращает

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

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

Возвращает

Возвращает новый набор с каждым элементом этого набора после выравнивания древовидной структуры. Древовидная структура определяется вложением элементов под ключом с известным именем. Такое имя можно указать, используя параметр '$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.

Параметры

Возвращает

Возвращает новый набор.

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

Параметры

Возвращает

Перемещает указатель итератора к следующей записи

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

Возвращает

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

Возвращает

Добавляет набор элементов в начало набора, создавая новый набор

Параметры

Возвращает

Добавляет один элемент в начало, создавая новый набор.

Параметры

Возвращает

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

Параметры

Возвращает

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

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

Пример:

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

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

Параметры

Возвращает

Перематывает результат.

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

Возвращает

Исключения

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

Параметры

Возвращает

Сериализует результат набора данных.

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

Возвращает

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

Возвращает

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

Параметры

Возвращает

Возвращает 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();
});

Параметры

Возвращает

Десериализует результат набора данных.

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

Параметры

Возвращает

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

Возвращает

Существуют ли еще результаты, ожидающие извлечения из итератора

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

Возвращает

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

Пример:

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

Параметры

Возвращает