Spec-Zone.ru › CakePHP 4.4

Класс StoppableIterator

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

Пространство имён: Cake\Collection\Iterator
См.: \Cake\Collection\Collection::stopWhen()

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

  • $_condition protected
    callable

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

  • $_innerIterator protected
    Traversable

    Ссылка на внутренний итератор, который оборачивает этот объект.

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

  • __construct() public

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

  • __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()

  • 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, или этой коллекции.

END_OF_DOCUMENT_MARKER
  • min() public

    Возвращает нижний элемент в этом наборе после сортировки по свойству. См. метод sortBy для получения информации о параметрах callback и $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

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

  • unwrap() public

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

  • valid() public

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

  • zip() public

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

  • zipWith() public

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

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

__construct() public

__construct(iterable $items, callable $condition)

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

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

Параметры

iterable $items

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

callable $condition

Функция, которая будет вызываться для каждого элемента в коллекции. Если результат оценивается как false, из этого итератора больше не будут возвращаться элементы.

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

Parameters

mixed $value

Returns

bool

count() public

count(): int

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

WARNINGS:

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

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

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

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

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

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

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

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

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

Returns

int

countBy() public

countBy(callable|string $path): self

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

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

Example:

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

Parameters

callable|string $path

Returns

self

countKeys() public

countKeys(): int

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

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

Returns

int

each() public

each(callable $callback): $this

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

Example:

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

Parameters

callable $callback

Returns

$this

every() public

every(callable $callback): bool

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

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

Example:

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

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

Parameters

callable $callback

Returns

bool

extract() public

extract(callable|string $path): self

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

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

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

Example:

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

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

Parameters

callable|string $path

Returns

self

filter() public

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

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

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

Example:

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

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

Parameters

callable|null $callback optional

Returns

self

first() public

first(): mixed

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

Returns

mixed

firstMatch() public

firstMatch(array $conditions): mixed

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

Parameters

array $conditions

Returns

mixed

groupBy() public

groupBy(callable|string $path): self

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

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

Example:

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

Parameters

callable|string $path

Returns

self

indexBy() public

indexBy(callable|string $path): self

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

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

Example:

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

Parameters

callable|string $path

Returns

self

insert() public

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

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

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

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

Example:

Вставить возраст в коллекцию, содержащую пользователей:

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

Parameters

string $path
mixed $values

Returns

self

isEmpty() public

isEmpty(): bool

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

Example:

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

Returns

bool

jsonSerialize() public

jsonSerialize(): array

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

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

Returns

array

last() public

last(): mixed

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

Returns

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

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

Параметры

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

valid() public

valid(): bool

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

Возвращает

bool

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

Детали свойств

$_condition protected

Условие для оценки каждого элемента коллекции

Тип

callable

$_innerIterator protected

Ссылка на внутренний итератор, который оборачивает этот объект.

Тип

Traversable

© 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.StoppableIterator.html

Spec-Zone.ru

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