Spec-Zone.ru › CakePHP 4.2

Класс ZipIterator

Создаёт итератор, возвращающий элементы, сгруппированные по парам

Пример

$iterator = new ZipIterator([[1, 2], [3, 4]]);
 $iterator->toList(); // Returns [[1, 3], [2, 4]]

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

Пример

$iterator = new ZipIterator([[1, 2], [3, 4]], function ($a, $b) {
   return $a + $b;
 });
 $iterator->toList(); // Returns [4, 6]
Пространство имён: Cake\Collection\Iterator

Краткое описание свойств

  • $_callback protected
    callable|null

    Функция, используемая для группировки элементов

  • $_iterators protected
    array

    Содержит исходные объекты итераторов, которые были прикреплены

Краткое описание методов

  • __construct() public

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

  • _createMatcherFilter() protected

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

  • _extract() protected

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

  • _propertyExtractor() protected

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

  • _simpleExtract() protected

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

  • append() public

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

  • appendItem() public

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

  • avg() public

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

  • buffered() public

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

  • cartesianProduct() public

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

  • chunk() public

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

  • chunkWithKeys() public

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

  • combine() public

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

  • compile() public

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

  • contains() public

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

  • count() public

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

  • countBy() public

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

  • countKeys() public

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

  • current() public

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

  • each() public

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

  • every() public

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

  • extract() public

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

  • filter() public

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

  • first() public

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

  • firstMatch() public

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

  • groupBy() public

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

  • indexBy() public

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

  • insert() public

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

  • isEmpty() public

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

  • jsonSerialize() public

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

  • last() public

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

  • lazy() public

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

  • listNested() public

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

  • map() public

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

  • match() public

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

  • max() public

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

  • median() public

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

  • min() public

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

  • nest() public

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

  • newCollection() protected

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

  • optimizeUnwrap() protected

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

  • prepend() public

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

  • prependItem() public

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

  • reduce() public

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

  • reject() public

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

  • sample() public

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

  • serialize() public

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

  • shuffle() public

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

  • skip() public

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

  • some() public

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

  • sortBy() public

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

  • stopWhen() public

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

  • sumOf() public

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

  • take() public

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

  • takeLast() public

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

  • through() public

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

  • toArray() public

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

  • toList() public

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

  • transpose() public

    Меняет местами строки и столбцы на столбцы и строки.

  • unfold() public

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

  • unserialize() public

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

  • unwrap() public

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

  • zip() public

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

  • zipWith() public

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

Краткое описание методов

__construct() public

__construct(array $sets, callable|null $callable = null)

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

Параметры

array $sets

Список массивов или итераторов, которые нужно объединить.

callable|null $callable optional

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

_createMatcherFilter() protected

_createMatcherFilter(array $conditions): Closure

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

Параметры

array $conditions

Список условий для соответствия в формате «ключ-значение», где ключ — путь к свойству, получаемому из текущего элемента, а значение — значение, с которым нужно сравнить элемент.

Возвращает

Closure

_extract() protected

_extract(arrayArrayAccess $data, string[] $parts): mixed

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

Параметры

arrayArrayAccess $data

Данные.

string[] $parts

Путь для извлечения.

Возвращает

mixed

_propertyExtractor() protected

_propertyExtractor(string|callable $path): callable

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

Параметры

string|callable $path

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

Возвращает

callable

_simpleExtract() protected

_simpleExtract(arrayArrayAccess $data, string[] $parts): mixed

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

Параметры

arrayArrayAccess $data

Данные.

string[] $parts

Путь для извлечения.

Возвращает

mixed

append() public

append(iterable $items): self

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

Параметры

iterable $items

Возвращает

self

appendItem() public

appendItem(mixed $item, mixed $key = null): self

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

Параметры

mixed $item
mixed $key optional

Возвращает

self

avg() public

avg(string|callable|null $path = null): float|int|null

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

Параметры

string|callable|null $path optional

Возвращает

float|int|null

buffered() public

buffered(): self

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

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

Возвращает

self

cartesianProduct() public

cartesianProduct(callable|null $operation = null, callable|null $filter = null): Cake\Collection\CollectionInterface

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

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

Пример

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

Параметры

callable|null $operation optional

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

callable|null $filter optional

Функция фильтрации, которая должна возвращать true, чтобы результат был частью конечных результатов.

Возвращает

Cake\Collection\CollectionInterface

Выбрасывает

LogicException

chunk() public

chunk(int $chunkSize): self

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

Пример:

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

Параметры

int $chunkSize

Возвращает

self

chunkWithKeys() public

chunkWithKeys(int $chunkSize, bool $preserveKeys = true): self

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

Пример:

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

Параметры

int $chunkSize
bool $preserveKeys optional

Возвращает

self

combine() public

combine(callable|string $keyPath, callable|string $valuePath, callable|string|null $groupPath = null): self

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

Примеры:

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

Параметры

callable|string $keyPath
callable|string $valuePath
callable|string|null $groupPath optional

Возвращает

self

compile() public

compile(bool $preserveKeys = true): self

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

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

Пример:

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

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

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

Параметры

bool $preserveKeys optional

Возвращает

self

contains() public

contains(mixed $value): bool

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

Параметры

mixed $value

Возвращает

bool

count() public

count(): int

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

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

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

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

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

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

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

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

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

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

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

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

Возвращает

int

countBy() public

countBy(callable|string $path): self

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

Параметры

callable|string $path

Возвращает

self

countKeys() public

countKeys(): int

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

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

Возвращает

int

current() public

current(): array

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

Возвращает

array

each() public

each(callable $callback): $this

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

Пример:

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

Параметры

callable $callback

Возвращает

$this

every() public

every(callable $callback): bool

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

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

Пример:

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

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

Параметры

callable $callback

Возвращает

bool

extract() public

extract(string|callable $path): self

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

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

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

Параметры

string|callable $path

Возвращает

self

filter() public

filter(callable|null $callback = null): self

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

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

Пример:

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

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

Параметры

callable|null $callback optional

Возвращает

self

first() public

first(): mixed

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

Возвращает

mixed

firstMatch() public

firstMatch(array $conditions): mixed

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

Параметры

array $conditions

Возвращает

mixed

groupBy() public

groupBy(callable|string $path): self

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

Параметры

callable|string $path

Возвращает

self

indexBy() public

indexBy(callable|string $path): self

Принимая список и функцию обратного вызова, возвращающую ключ для каждого элемента в списке (или имя свойства), возвращает объект с индексом каждого элемента. Подобно 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'],
];

Параметры

callable|string $path

Возвращает

self

insert() public

insert(string $path, mixed $values): self

Возвращает новую коллекцию, содержащую каждый из элементов, найденных в $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]]
];

Параметры

string $path
mixed $values

Возвращает

self

isEmpty() public

isEmpty(): bool

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

Пример:

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

Возвращает

bool

jsonSerialize() public

jsonSerialize(): array

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

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

Возвращает

array

last() public

last(): mixed

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

Возвращает

mixed

lazy() public

lazy(): self

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

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

Возвращает

self

listNested() public

listNested(string|int $order = 'desc', string|callable $nestingKey = 'children'): self

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

Параметры

string|int $order необязательный
string|callable $nestingKey необязательный

Возвращает

self

map() public

map(callable $callback): self

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

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

Пример:

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

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

Параметры

callable $callback

Возвращает

self

match() public

match(array $conditions): self

Просматривает каждое значение в списке, возвращая коллекцию всех значений, которые содержат все пары ключ-значение, указанные в $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']]
]

Параметры

array $conditions

Возвращает

self

max() public

max(callable|string $path, int $sort = \SORT_NUMERIC): mixed

Возвращает верхний элемент в этой коллекции после сортировки по свойству. См. метод 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;

Параметры

callable|string $path
int $sort необязательный

Возвращает

mixed

median() public

median(string|callable|null $path = null): float|int|null

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

Параметры

string|callable|null $path необязательный

Возвращает

float|int|null

min() public

min(callable|string $path, int $sort = \SORT_NUMERIC): mixed

Возвращает нижний элемент в этой коллекции после сортировки по свойству. См. метод 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;

Параметры

callable|string $path
int $sort необязательный

Возвращает

mixed

nest() public

nest(callable|string $idPath, callable|string $parentPath, string $nestingKey = 'children'): self

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

Параметры

callable|string $idPath
callable|string $parentPath
string $nestingKey необязательный

Возвращает

self

newCollection() protected

newCollection(mixed ...$args): Cake\Collection\CollectionInterface

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

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

Параметры

mixed ...$args

Аргументы конструктора.

Возвращает

Cake\Collection\CollectionInterface

optimizeUnwrap() protected

optimizeUnwrap(): iterable

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

Возвращает

iterable

prepend() public

prepend(mixed $items): self

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

Параметры

mixed $items

Возвращает

self

prependItem() public

prependItem(mixed $item, mixed $key = null): self

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

Параметры

mixed $item
mixed $key необязательный

Возвращает

self

reduce() public

reduce(callable $callback, mixed $initial = null): mixed

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

Параметры

callable $callback
mixed $initial необязательный

Возвращает

mixed

reject() public

reject(callable $callback): self

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

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

Пример:

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

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

Параметры

callable $callback

Возвращает

self

sample() public

sample(int $length = 10): self

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

Параметры

int $length необязательный

Возвращает

self

serialize() public

serialize(): string

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

Возвращает

string

shuffle() public

shuffle(): self

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

Возвращает

self

skip() public

skip(int $length): self

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

Параметры

int $length

Возвращает

self

some() public

some(callable $callback): bool

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

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

Пример:

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

Параметры

callable $callback

Возвращает

bool

sortBy() public

sortBy(callable|string $path, int $order = \SORT_DESC, int $sort = \SORT_NUMERIC): self

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

Параметры

callable|string $path
int $order optional
int $sort optional

Возвращает

self

stopWhen() public

stopWhen(callable|array $condition): self

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

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

Пример:

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

Параметры

callable|array $condition

Возвращает

self

sumOf() public

sumOf(string|callable|null $path = null): float|int

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

Параметры

string|callable|null $path optional

Возвращает

float|int

take() public

take(int $length = 1, int $offset = 0): self

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

Параметры

int $length optional
int $offset optional

Возвращает

self

takeLast() public

takeLast(int $length): self

Возвращает последние 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];

Параметры

int $length

Возвращает

self

through() public

through(callable $callback): self

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

Пример:

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

Параметры

callable $callback

Возвращает

self

toArray() public

toArray(bool $preserveKeys = true): array

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

Параметры

bool $preserveKeys optional

Возвращает

array

toList() public

toList(): array

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

Возвращает

array

transpose() public

transpose(): Cake\Collection\CollectionInterface

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

Пример:

$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'],
// ]

Возвращает

Cake\Collection\CollectionInterface

Исключения

LogicException

unfold() public

unfold(callable|null $callback = null): self

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

Функция преобразования получит значение и ключ для каждого элемента коллекции в указанном порядке, и она должна вернуть массив или объект 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();
});

Параметры

callable|null $callback optional

Возвращает

self

unserialize() public

unserialize(string $iterators): void

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

Параметры

string $iterators

Десериализованные итераторы

Возвращает

void

unwrap() public

unwrap(): Traversable

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

Возвращает

Traversable

zip() public

zip(iterable $items): self

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

Пример:

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

Параметры

iterable $items

Возвращает

self

zipWith() public

zipWith(iterable $items, callable $callback): self

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

Результат будет значением возвращаемым функцией $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)]

Параметры

iterable $items
callable $callback

Возвращает

self

Подробное описание свойств

$_callback protected

Функция для объединения элементов

Тип

callable|null

$_iterators protected

Содержит исходные объекты итераторов, которые были добавлены

Тип

array

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.2/class-Cake.Collection.Iterator.ZipIterator.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API