Spec-Zone.ru › CakePHP 4.4

Класс ExtractIterator

Создаёт итератор из другого итератора, извлекая запрошенную колонку или свойство на основе пути

Пространство имён: Cake\Collection\Iterator

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

  • $_extractor protected
    callable

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

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

  • __construct() public

    Создаёт итератор, который будет возвращать запрошенное свойство для каждого значения в коллекции, выраженное в $path

  • __debugInfo() public

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

  • __serialize() public

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

  • __unserialize() public

    Пересоздаёт экземпляр Collection.

  • _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

    Возвращает значение столбца, определённого в $path, или null, если путь не был пройден.

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

END_OF_DOCUMENT_MARKER
  • 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

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

  • unwrap() public

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

  • zip() public

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

  • zipWith() public

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

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

__construct() public

__construct(iterable $items, callable|string $path)

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

Пример:

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

$items = [
 ['comment' => ['body' => 'cool', 'user' => ['name' => 'Mark']],
 ['comment' => ['body' => 'very cool', 'user' => ['name' => 'Renan']]
];
$extractor = new ExtractIterator($items, 'comment.user.name'');

Параметры

iterable $items

Список значений для итерации

callable|string $path

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

__debugInfo() public

__debugInfo(): array<string, mixed>

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

Возвращаемое значение

array<string, mixed>

__serialize() public

__serialize(): array

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

Возвращаемое значение

array

__unserialize() public

__unserialize(array $data): void

Пересоздаёт экземпляр Collection.

Параметры

array $data

Массив данных.

Возвращаемое значение

void

_createMatcherFilter() protected

_createMatcherFilter(array $conditions): Closure

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

Параметры

array $conditions

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

Возвращаемое значение

Closure

_extract() protected

_extract(ArrayAccess|array $data, array<string> $parts): mixed

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

Параметры

ArrayAccess|array $data

Данные.

array<string> $parts

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

Возвращаемое значение

mixed

_propertyExtractor() protected

_propertyExtractor(callable|string $path): callable

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

Параметры

callable|string $path

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

Возвращаемое значение

callable

_simpleExtract() protected

_simpleExtract(ArrayAccess|array $data, array<string> $parts): mixed

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

Параметры

ArrayAccess|array $data

Данные.

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

Параметры

callable|string|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 $keepKeys = 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 $keepKeys 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 $keepKeys = 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 $keepKeys 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(): mixed

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

Возвращает

mixed

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

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

Пример:

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

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

Параметры

callable $callback

Возвращает

bool

extract() public

extract(callable|string $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]

Параметры

callable|string $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

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

Пример:

$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', callable|string $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 необязательно
callable|string $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(callable|string|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 значениями не считаются пустыми.

Параметры

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

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

Пример:

$hasYoungPeople = (new Collection([24, 45, 15]))->some(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(callable|string|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

Параметры

callable|string|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 $keepKeys = true): array

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

Параметры

bool $keepKeys 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 $collection): void

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

Параметры

string $collection

Сериализованная коллекция

Возвращает

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

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

$_extractor protected

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

Тип

callable

© 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.4/class-Cake.Collection.Iterator.ExtractIterator.html

Spec-Zone.ru

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