Класс TreeIterator
Рекурсивный итератор, используемый для сплющивания вложенных структур, а также предоставляет все методы Collection.
Краткое описание свойств
- $_mode protected
intРежим итерации
Краткое описание методов
-
__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(). -
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
Добавляет один элемент в начало, создавая новую коллекцию.
-
printer() public
Возвращает другой итератор, который будет возвращать значения, готовые для отображения пользователю. Он делает это, извлекая одно свойство из каждого элемента и добавляя его с префиксом-разделителем, чтобы можно было визуализировать относительное положение в дереве.
-
reduce() public
Сворачивает значения в этой коллекции в одно значение, как результат применения функции обратного вызова ко всем элементам. $zero — начальное состояние сворачивания, и каждый последующий шаг должен возвращаться функцией обратного вызова. Если $zero опущен, используется первое значение коллекции, и сворачивание начнется со второго элемента.
-
reject() public
Просматривает каждое значение в коллекции и возвращает другую коллекцию со всеми значениями, которые не проходят проверку истинности. Это противоположно
filter. -
sample() public
Возвращает новую коллекцию с максимальным количеством $size случайных элементов из этой коллекции
-
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
Создаёт новую коллекцию, элементы которой являются результатом конкатенации списков элементов, сгенерированных функцией преобразования, применённой к каждому элементу исходной коллекции.
-
unwrap() public
Возвращает ближайший вложенный итератор, который можно безопасно проходить, не теряя возможных преобразований. Это используется главным образом для удаления пустых обёрток IteratorIterator, которые могут только замедлить процесс итерации.
-
zip() public
Комбинирует элементы этой коллекции с каждым из элементов переданных итерируемых объектов, используя их позиционный индекс как ссылку.
-
zipWith() public
Комбинирует элементы этой коллекции с каждым из элементов переданных итерируемых объектов, используя их позиционный индекс как ссылку.
Подробное описание методов
__construct() public
__construct(RecursiveIterator $items, int $mode = RecursiveIteratorIterator::SELF_FIRST, int $flags = 0)
Конструктор
Параметры
-
RecursiveIterator$items Итератор для сглаживания.
-
int$mode необязательный Режим итератора.
-
int$flags необязательный Флаги итератора.
_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 Путь для извлечения.
Возвращает
mixedappend() public
append(iterable $items): self
Возвращает новую коллекцию в результате конкатенации списка элементов в этой коллекции со списком переданных элементов.
Параметры
-
iterable$items
Возвращает
selfappendItem() public
appendItem(mixed $item, mixed $key = null): self
Добавляет один элемент, создавая новую коллекцию.
Параметры
-
mixed$item -
mixed$key необязательный
Возвращает
selfavg() 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 необязательный
Возвращает
float|int|nullbuffered() public
buffered(): self
Возвращает новую коллекцию, в которой выполняются операции, заданные этой коллекцией. Независимо от того, сколько раз будет итерироваться новая коллекция, эти операции будут выполняться только один раз.
Это также можно использовать для создания возможности перемотки любого неперемотанного итератора.
Возвращает
selfcartesianProduct() 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 необязательный Вызываемый объект, позволяющий настраивать результат произведения.
-
callable|null$filter необязательный Обработчик фильтрации, который должен возвращать true, чтобы результат был частью конечных результатов.
Возвращает
Cake\Collection\CollectionInterfaceИсключения
LogicExceptionchunk() 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
Возвращает
selfchunkWithKeys() 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 необязательный
Возвращает
selfcombine() 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 необязательный
Возвращает
selfcompile() 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 необязательный
Возвращает
selfcontains() public
contains(mixed $value): bool
Возвращает true, если $value присутствует в этой коллекции. Сравнения выполняются как по значению, так и по типу.
Параметры
-
mixed$value
Возвращает
boolcount() public
count(): int
Возвращает количество элементов в коллекции.
ПРЕДУПРЕЖДЕНИЯ:
Изменит текущую позицию итератора:
Вызов этого метода одновременно с итерацией по этой коллекции, например, в цикле foreach, приведёт к неопределённому поведению. Избегайте этого.
Потребляет все элементы для коллекций NoRewindIterator:
В некоторых типах коллекций вызов этого метода может сделать их непригодными для дальнейшего использования. То есть, вы больше не сможете получить из них элементы или итерировать по ним.
В частности, любая коллекция, оборачивающая генератор (функцию с оператором yield) или небуферизованный курсор базы данных, не будет принимать другие вызовы функций после вызова count().
Создайте новую коллекцию с помощью метода buffered(), чтобы решить эту проблему.
Может сообщить о большем количестве элементов, чем уникальных ключей:
Любая коллекция, созданная путём добавления коллекций друг к другу или имеющая внутренние итераторы, возвращающие дубликаты ключей, будет сообщать о большем количестве элементов с помощью этой функции, чем окончательное количество элементов при преобразовании коллекции в индексированный массив. Это связано с тем, что дубликаты ключей будут объединены в один в итоговом массиве, тогда как этот метод count учитывает только количество элементов после преобразования в простой список.
Если вам нужно количество элементов с учётом ключей (количество уникальных ключей), вы можете вызвать countKeys()
Returns
intcountBy() 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
selfcountKeys() public
countKeys(): int
Возвращает количество уникальных ключей в этом итераторе. Это то же самое, что и количество элементов, которые будет содержать коллекция после вызова toArray()
Этот метод имеет ряд предостережений. Подробнее см. CollectionInterface::count().
Returns
inteach() public
each(callable $callback): $this
Применяет обратный вызов к элементам в этой коллекции.
Example:
$collection = (new Collection($items))->each(function ($value, $key) {
echo "Element $key: $value";
}); Parameters
-
callable$callback
Returns
$thisevery() 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
boolextract() 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
selffilter() 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
selffirst() public
first(): mixed
Возвращает первый результат в этой коллекции
Returns
mixedfirstMatch() public
firstMatch(array $conditions): mixed
Возвращает первый результат, соответствующий всем парам ключ-значение, указанным в условиях.
Parameters
-
array$conditions
Returns
mixedgroupBy() 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
selfindexBy() 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
selfinsert() 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
selfisEmpty() public
isEmpty(): bool
Возвращает, есть ли элементы в этой коллекции
Example:
$items [1, 2, 3]; (new Collection($items))->isEmpty(); // false
(new Collection([]))->isEmpty(); // true
Returns
booljsonSerialize() public
jsonSerialize(): array
Возвращает данные, которые могут быть преобразованы в JSON. Возвращает те же данные, что и toArray(), которые содержат только уникальные ключи.
Часть интерфейса JsonSerializable.
Returns
arraylast() public
last(): mixed
Возвращает последний результат в этой коллекции
Returns
mixedlazy() public
lazy(): self
Возвращает новую коллекцию, в которой любые операции, связанные после неё, гарантированно будут выполняться лениво. То есть, элементы будут выводиться по одному.
По ленивой коллекции можно итерировать только один раз. Вторая попытка приводит к ошибке.
Returns
selflistNested() 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 необязательный
Возвращает
selfmap() public
map(callable $callback): self
Возвращает другую коллекцию после изменения каждого из значений в этой коллекции с помощью предоставленной лямбда-функции.
Каждый раз, когда вызывается коллбэк, он получает значение элемента в текущей итерации, ключ элемента и эту коллекцию в качестве аргументов в этом порядке.
Пример:
Получение коллекции булевых значений, где true указывает, является ли человек женщиной:
$collection = (new Collection($people))->map(function ($person, $key) {
return $person->gender === 'female';
}); Параметры
-
callable$callback
Возвращает
selfmatch() 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
Возвращает
selfmax() public
max(callable|string $path, int $sort = \SORT_NUMERIC): mixed
Возвращает верхний элемент в этой коллекции после сортировки по свойству. Сведения о коллбэке и параметре $sort см. в методе sortBy.
Примеры:
// 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 необязательный
Возвращает
mixedmedian() 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|nullmin() public
min(callable|string $path, int $sort = \SORT_NUMERIC): mixed
Возвращает нижний элемент в этой коллекции после сортировки по свойству. Сведения о коллбэке и параметре $sort см. в методе sortBy.
Примеры:
// 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 необязательный
Возвращает
mixednest() public
nest(callable|string $idPath, callable|string $parentPath, string $nestingKey = 'children'): self
Возвращает новую коллекцию, где значения вложены в структуру дерева на основе пути к свойству id и пути к свойству родительского id.
Параметры
-
callable|string$idPath -
callable|string$parentPath -
string$nestingKey необязательный
Возвращает
selfnewCollection() protected
newCollection(mixed ...$args): Cake\Collection\CollectionInterface
Возвращает новую коллекцию.
Позволяет классам, использующим этот трайт, определять собственный тип возвращаемого интерфейса коллекции.
Параметры
-
mixed...$args Аргументы конструктора.
Возвращает
Cake\Collection\CollectionInterfaceoptimizeUnwrap() protected
optimizeUnwrap(): iterable
Разворачивает этот итератор и возвращает самый простой перебираемый объект, который может быть использован для извлечения данных.
Возвращает
iterableprepend() public
prepend(mixed $items): self
Добавляет набор элементов в начало коллекции, создавая новую коллекцию.
Параметры
-
mixed$items
Возвращает
selfprependItem() public
prependItem(mixed $item, mixed $key = null): self
Добавляет один элемент в начало, создавая новую коллекцию.
Параметры
-
mixed$item -
mixed$key необязательный
Возвращает
selfprinter() public
printer(callable|string $valuePath, callable|string|null $keyPath = null, string $spacer = '__'): Cake\Collection\Iterator\TreePrinter
Возвращает другой итератор, который вернёт значения, готовые к отображению пользователю. Это делается путём извлечения одного свойства из каждого элемента и добавления префикса с разделителем, чтобы можно было визуализировать относительное положение в дереве.
Как $valuePath, так и $keyPath могут быть строкой со значением свойства для извлечения или точкой, отделяющей путь к свойствам, которые необходимо проследить, чтобы получить последнее на пути.
В качестве альтернативы, $valuePath и $keyPath могут быть вызываемыми функциями. Они получат текущий элемент в качестве первого параметра, текущий ключ итерации — во втором, и экземпляр итератора — в третьем.
Пример
$printer = (new Collection($treeStructure))->listNested()->printer('name'); Использование лямбда-функции:
$printer = (new Collection($treeStructure))
->listNested()
->printer(function ($item, $key, $iterator) {
return $item->name;
}); Параметры
-
callable|string$valuePath Свойство для извлечения или вызываемая функция для возврата значения для отображения
-
callable|string|null$keyPath необязательный Свойство для использования в качестве ключа итерации или вызываемая функция, возвращающая значение ключа.
-
string$spacer необязательный Строка, используемая для префикса значений в зависимости от их глубины в дереве
Возвращает
Cake\Collection\Iterator\TreePrinterreduce() public
reduce(callable $callback, mixed $initial = null): mixed
Складывает значения в этой коллекции в одно значение, как результат применения функции обратного вызова ко всем элементам. $zero — начальное состояние сокращения, и каждый последующий шаг должен быть возвращен функцией обратного вызова. Если $zero опущен, будет использовано первое значение коллекции, и сокращение начнется со второго элемента.
Параметры
-
callable$callback -
mixed$initial необязательный
Возвращает
mixedreject() public
reject(callable $callback): self
Просматривает каждое значение в коллекции и возвращает другую коллекцию со всеми значениями, которые не проходят проверку. Это противоположно filter.
Каждый раз, когда вызывается коллбэк, он получает значение элемента в текущей итерации, ключ элемента и эту коллекцию в качестве аргументов в этом порядке.
Пример:
Фильтрация чётных чисел в массиве, в результате в итоговой коллекции будут только значения 1 и 3:
$collection = (new Collection([1, 2, 3]))->reject(function ($value, $key) {
return $value % 2 === 0;
}); Параметры
-
callable$callback
Возвращает
selfsample() public
sample(int $length = 10): self
Возвращает новую коллекцию с максимальным количеством $size случайных элементов из этой коллекции.
Параметры
-
int$length необязательный
Возвращает
selfshuffle() public
shuffle(): self
Возвращает новую коллекцию с элементами в случайном порядке; эта функция не сохраняет исходные ключи в коллекции.
Возвращает
selfskip() public
skip(int $length): self
Возвращает новую коллекцию, которая пропустит указанное количество элементов в начале итерации.
Параметры
-
int$length
Возвращает
selfsome() public
some(callable $callback): bool
Возвращает true, если какие-либо значения в этой коллекции удовлетворяют заданному тесту истинности в обратном вызове.
Обратный вызов получает значение и ключ проверяемого элемента и должен возвращать true, если тест пройден.
Пример:
$hasYoungPeople = (new Collection([24, 45, 15]))->some(function ($value, $key) {
return $value < 21;
}); Параметры
-
callable$callback
Возвращает
boolsortBy() 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 необязательно -
int$sort необязательно
Возвращает
selfstopWhen() 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
Возвращает
selfsumOf() 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 необязательно
Возвращает
float|inttake() public
take(int $length = 1, int $offset = 0): self
Возвращает новую коллекцию с максимальным числом $size элементов в внутреннем порядке, в котором эта коллекция была создана. Если передан второй параметр, он определит, с какой позиции начать выбор элементов.
Параметры
-
int$length необязательно -
int$offset необязательно
Возвращает
selftakeLast() 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
Возвращает
selfthrough() public
through(callable $callback): self
Пропускает эту коллекцию через вызываемую функцию в качестве первого аргумента. Это полезно для декорирования всей коллекции другим объектом.
Пример:
$items = [1, 2, 3];
$decorated = (new Collection($items))->through(function ($collection) {
return new MyCustomCollection($collection);
}); Параметры
-
callable$callback
Возвращает
selftoArray() public
toArray(bool $keepKeys = true): array
Возвращает массивное представление результатов
Параметры
-
bool$keepKeys необязательно
Возвращает
arraytoList() public
toList(): array
Возвращает массивное представление результатов с численно-индексированными данными. Это эквивалентно вызову toArray(false)
Возвращает
arraytranspose() 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Исключение
LogicExceptionunfold() 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 необязательно
Возвращает
selfunwrap() public
unwrap(): Traversable
Возвращает ближайший вложенный итератор, который можно безопасно пройти, не теряя возможных преобразований. Это используется главным образом для удаления пустых обёрток IteratorIterator, которые могут только замедлить процесс итерации.
Возвращает
Traversablezip() 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
Возвращает
selfzipWith() 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Подробное описание свойств
$_mode protected
Режим итерации
Тип
int
© 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.3/class-Cake.Collection.Iterator.TreeIterator.html