Класс ExtractIterator
Создаёт итератор из другого итератора, извлекая запрошенную колонку или свойство на основе пути
Краткое описание свойств
- $_extractor protected
callableВызываемый объект, ответственный за извлечение одного значения для каждого элемента в коллекции.
Краткое описание методов
-
__construct() public
Создаёт итератор, который вернёт запрошенное свойство для каждого значения в коллекции, выраженного в $path
-
__debugInfo() public
Возвращает массив, который можно использовать для описания внутреннего состояния этого объекта.
-
_createMatcherFilter() protected
Возвращает вызываемый объект, который получает значение и возвращает, соответствует ли оно определённому условию.
-
_extract() protected
Возвращает столбец из $data, который можно извлечь, итерируясь по именам столбцов, содержащимся в $path. Он вернёт массивы для элементов, представленных в
{*}. -
_propertyExtractor() protected
Возвращает вызываемый объект, который может использоваться для извлечения свойства или столбца из массива или объекта на основе пути, разделённого точкой.
-
_simpleExtract() protected
Возвращает столбец из $data, который можно извлечь, итерируясь по именам столбцов, содержащимся в $path.
-
append() public
Возвращает новую коллекцию в результате конкатенации списка элементов в этой коллекции со списком переданных элементов.
-
appendItem() public
Добавляет один элемент, создавая новую коллекцию.
-
avg() public
Возвращает среднее арифметическое всех значений, извлечённых с помощью $path, или всей коллекции.
-
buffered() public
Возвращает новую коллекцию, где операции, выполненные этой коллекцией, не будут выполняться повторно. Независимо от того, сколько раз новая коллекция будет итерирована, эти операции будут выполнены только один раз.
-
cartesianProduct() public
Создаёт новую коллекцию, которая является декартовым произведением текущей коллекции.
-
chunk() public
Разбивает коллекцию на меньшие массивы заданного размера.
-
chunkWithKeys() public
Разбивает коллекцию на меньшие массивы заданного размера.
-
combine() public
Возвращает новую коллекцию, где значения извлекаются на основе пути к значению и затем индексируются по пути к ключу. Этот метод может создавать родительские группы на основе пути к свойству группы.
-
compile() public
Проходит по всем элементам этой коллекции один раз, выполняет все скопированные операции над ними, а затем возвращает новую коллекцию с результатом. Это полезно для преобразования неперематываемых внутренних итераторов в коллекцию, которую можно перематывать и использовать несколько раз.
-
contains() public
Возвращает true, если $value присутствует в этой коллекции. Сравнения выполняются по значению и типу.
-
count() public
Возвращает количество элементов в коллекции.
-
countBy() public
Сортирует список по группам и возвращает количество элементов в каждой группе. Аналогично groupBy, но вместо возвращения списка значений возвращает количество значений в группе.
-
countKeys() public
Возвращает количество уникальных ключей в этом итераторе. Это то же самое, что и количество элементов, которые будет содержать коллекция после вызова
toArray(). -
current() public
Возвращает значение столбца, определённого в $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.
-
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
Создаёт новый набор, который при итерации прекратит выдавать результаты, если предоставленное условие истинно.
-
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, string|callable $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 Список значений для итерации
-
string|callable$path Путь к столбцу, разделенный точками, для извлечения конечного значения, или вызываемый объект, который выполнит эту операцию.
__debugInfo() public
__debugInfo(): array
Возвращает массив, который можно использовать для описания внутреннего состояния этого объекта.
Возвращает
array_createMatcherFilter() protected
_createMatcherFilter(array $conditions): Closure
Возвращает вызываемый объект, который получает значение и возвращает true, если оно соответствует определённому условию.
Параметры
-
array$conditions Список условий сопоставления, где ключ — путь к свойству для текущего элемента, а значение — значение, с которым сравнивается элемент.
Возвращает
Closure_extract() protected
_extract(arrayArrayAccess $data, string[] $parts): mixed
Возвращает столбец из $data, который можно извлечь, итерируясь по именам столбцов, содержащимся в $path. Вернёт массивы для элементов, представленных {*}
Параметры
-
arrayArrayAccess$data Данные.
-
string[]$parts Путь для извлечения.
Возвращает
mixed_propertyExtractor() protected
_propertyExtractor(string|callable $path): callable
Возвращает вызываемый объект, который может использоваться для извлечения свойства или столбца из массива или объекта на основе пути, разделённого точками.
Параметры
-
string|callable$path Путь к столбцу, разделённый точками, для извлечения конечного значения, или вызываемый объект, который выполнит эту операцию.
Возвращает
callable_simpleExtract() protected
_simpleExtract(arrayArrayAccess $data, string[] $parts): mixed
Возвращает столбец из $data, который можно извлечь, итерируясь по именам столбцов, содержащимся в $path
Параметры
-
arrayArrayAccess$data Данные.
-
string[]$parts Путь для извлечения.
Возвращает
mixedappend() public
append(iterable $items): self
Возвращает новую коллекцию в результате конкатенации списка элементов в этой коллекции со списком переданных элементов
Параметры
-
iterable$items
Возвращает
selfappendItem() public
appendItem(mixed $item, mixed $key = null): self
Добавляет один элемент, создавая новую коллекцию.
Параметры
-
mixed$item -
mixed$key optional
Возвращает
selfavg() public
avg(string|callable|null $path = null): float|int|null
Возвращает среднее значение всех значений, извлечённых с помощью $path, или этой коллекции.
Пример:
$items = [
['invoice' => ['total' => 100]],
['invoice' => ['total' => 200]]
];
$total = (new Collection($items))->avg('invoice.total');
// Total: 150
$total = (new Collection([1, 2, 3]))->avg();
// Total: 2 Среднее пустого набора или 0 строк — null. Коллекции с null значениями не считаются пустыми.
Параметры
-
string|callable|null$path optional
Возвращает
float|int|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 optional Вызываемый объект, позволяющий настроить результат произведения.
-
callable|null$filter optional Функция фильтрации, которая должна возвращать 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 $preserveKeys = true): self
Разбивает коллекцию на меньшие массивы заданного размера.
Пример:
$items ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5, 'f' => 6]; $chunked = (new Collection($items))->chunkWithKeys(3)->toList(); // Returns [['a' => 1, 'b' => 2, 'c' => 3], ['d' => 4, 'e' => 5, 'f' => 6]]
Параметры
-
int$chunkSize -
bool$preserveKeys optional
Возвращает
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 optional
Возвращает
selfcompile() public
compile(bool $preserveKeys = true): self
Итерирует все элементы в этой коллекции один раз, выполняет все накопленные операции над ними и возвращает новую коллекцию с результатом. Это полезно для преобразования необратимых внутренних итераторов в коллекцию, которую можно прокрутить и использовать несколько раз.
Типичный случай использования — повторное использование одной и той же переменной для расчёта различных данных. В таких случаях может быть полезно и эффективнее сначала скомпилировать коллекцию, а затем применить к ней дополнительные операции.
Пример:
$collection->map($mapper)->sortBy('age')->extract('name');
$compiled = $collection->compile();
$isJohnHere = $compiled->some($johnMatcher);
$allButJohn = $compiled->filter($johnMatcher); В приведенном выше примере, если бы коллекция не была скомпилирована предварительно, итерации для map, sortBy и extract выполнялись бы дважды: один раз для получения $isJohnHere и один раз для $allButJohn
Вы можете рассматривать этот метод как способ создания контрольных точек для сложных вычислений в коллекции.
Параметры
-
bool$preserveKeys optional
Возвращает
selfcontains() public
contains(mixed $value): bool
Возвращает true, если $value присутствует в этой коллекции. Сравнения проводятся как по значению, так и по типу.
Параметры
-
mixed$value
Возвращает
boolcount() public
count(): int
Возвращает количество элементов в коллекции.
ПРЕДУПРЕЖДЕНИЯ:
Изменяет текущую позицию итератора:
Вызов этого метода во время итерации по этой коллекции, например, в цикле foreach, приведёт к неопределённому поведению. Избегайте этого.
Потребляет все элементы для коллекций NoRewindIterator:
Для некоторых типов коллекций вызов этого метода может сделать их непригодными для дальнейшего использования. То есть, вы, возможно, не сможете получить элементы или итерироваться по ним больше.
Чтобы обойти эту проблему, создайте новую коллекцию с помощью метода buffered().
В частности, любая коллекция, обертывающая генератор (функцию с оператором yield) или небуферизованный курсор базы данных, не примет других вызовов функций после вызова count() на ней.
Создайте новую коллекцию с помощью метода buffered() для преодоления этой проблемы.
Может сообщить о большем количестве элементов, чем уникальных ключей:
Любая коллекция, созданная путем добавления коллекций друг к другу или с внутренними итераторами, возвращающими дублирующиеся ключи, сообщит о большем количестве элементов, используя эту функцию, чем фактическое количество элементов при преобразовании коллекций в массив с ключами. Это происходит потому, что дублирующиеся ключи объединяются в один в конечном массиве, в то время как этот метод count учитывает только количество элементов после преобразования в обычный список.
Если вам нужно количество элементов с учетом ключей (количество уникальных ключей), вы можете вызвать countKeys().
Возвращает
intcountBy() 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
Возвращает
selfcountKeys() public
countKeys(): int
Возвращает количество уникальных ключей в этом итераторе. Это то же самое, что и количество элементов в коллекции после вызова toArray().
Этот метод имеет ряд ограничений. Подробности см. в CollectionInterface::count().
Возвращает
intcurrent() public
current(): mixed
Возвращает значение столбца, определенного в $path, или null, если путь не был пройден.
Возвращает
mixedeach() public
each(callable $callback): $this
Применяет обратный вызов к элементам в этой коллекции.
Пример:
$collection = (new Collection($items))->each(function ($value, $key) {
echo "Element $key: $value";
}); Параметры
-
callable$callback
Возвращает
$thisevery() public
every(callable $callback): bool
Возвращает true, если все значения в этой коллекции проходят проверку, заданную в обратном вызове.
Каждый раз при выполнении обратного вызова он получает значение элемента в текущей итерации и ключ элемента в качестве аргументов в указанном порядке.
Пример:
$overTwentyOne = (new Collection([24, 45, 60, 15]))->every(function ($value, $key) {
return $value > 21;
}); Пустые коллекции всегда возвращают true, потому что это пустая истина.
Параметры
-
callable$callback
Возвращает
boolextract() public
extract(string|callable $path): self
Возвращает новую коллекцию, содержащую значение столбца или свойства, найденное в каждом из элементов.
Матчер может быть строкой с именем свойства или путём свойств, разделённым точками, для получения последнего свойства в пути.
Если столбец или свойство не были найдены для конкретного элемента в коллекции, эта позиция заполняется null.
Пример:
Извлечь имя пользователя для всех комментариев в массиве:
$items = [
['comment' => ['body' => 'cool', 'user' => ['name' => 'Mark']],
['comment' => ['body' => 'very cool', 'user' => ['name' => 'Renan']]
];
$extracted = (new Collection($items))->extract('comment.user.name');
// Result will look like this when converted to array
['Mark', 'Renan'] Также возможно извлечь сплюснутую коллекцию из вложенных свойств
$items = [
['comment' => ['votes' => [['value' => 1], ['value' => 2], ['value' => 3]]],
['comment' => ['votes' => [['value' => 4]]
];
$extracted = (new Collection($items))->extract('comment.votes.{*}.value');
// Result will contain
[1, 2, 3, 4] Параметры
-
string|callable$path
Возвращает
selffilter() 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
Возвращает
selffirst() public
first(): mixed
Возвращает первый результат в этой коллекции
Возвращает
mixedfirstMatch() public
firstMatch(array $conditions): mixed
Возвращает первый результат, соответствующий всем парам ключ-значение, перечисленным в условиях.
Параметры
-
array$conditions
Возвращает
mixedgroupBy() 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
Возвращает
selfindexBy() 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
Возвращает
selfinsert() 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
Возвращает
selfisEmpty() public
isEmpty(): bool
Возвращает значение, указывающее, есть ли элементы в этой коллекции.
Пример:
$items [1, 2, 3]; (new Collection($items))->isEmpty(); // false
(new Collection([]))->isEmpty(); // true
Возвращает
booljsonSerialize() public
jsonSerialize(): array
Возвращает данные, которые можно преобразовать в JSON. Это возвращает те же данные, что и toArray(), которые содержат только уникальные ключи.
Часть интерфейса JsonSerializable.
Возвращает
arraylast() public
last(): mixed
Возвращает последний результат в этой коллекции
Возвращает
mixedlazy() public
lazy(): self
Возвращает новую коллекцию, где все последующие цепочки операций гарантированно будут выполнены лениво. То есть, элементы будут возвращаться по одному.
Ленивая коллекция может быть итерирована только один раз. Повторная попытка приводит к ошибке.
Возвращает
selflistNested() public
listNested(string|int $order = 'desc', string|callable $nestingKey = 'children'): self
Возвращает новую коллекцию, содержащую каждый элемент этой коллекции после сплющивания структуры дерева. Структура дерева определяется вложенностью элементов под ключом с известным именем. Такое имя можно указать, используя параметр '$nestingKey'.
По умолчанию возвращаются все элементы в дереве, следуя алгоритму обхода в глубину (Depth First Search), то есть от родительского элемента к листьям для каждой ветви.
Возвращение элементов снизу вверх (Breadth First Search) возможно при передаче параметра '$dir' со значением 'asc'. То есть, будут возвращены все элементы для каждого уровня дерева, сначала снизу вверх.
Наконец, можно указать, чтобы получить только коллекцию с листьями в структуре дерева. Для этого передайте 'leaves' в первый аргумент.
Возможные значения для первого аргумента являются алиасами следующих констант, и вместо алиаса можно использовать сами константы:
- desc: RecursiveIteratorIterator::SELF_FIRST
- asc: RecursiveIteratorIterator::CHILD_FIRST
- leaves: RecursiveIteratorIterator::LEAVES_ONLY
Пример:
$collection = new Collection([
['id' => 1, 'children' => [['id' => 2, 'children' => [['id' => 3]]]]],
['id' => 4, 'children' => [['id' => 5]]]
]);
$flattenedIds = $collection->listNested()->extract('id'); // Yields [1, 2, 3, 4, 5] Параметры
-
string|int$order необязательный -
string|callable$nestingKey необязательный
Возвращает
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
Возвращает верхний элемент в этой коллекции после сортировки по свойству. См. метод 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 необязательный
Возвращает
mixedmedian() public
median(string|callable|null $path = null): float|int|null
Возвращает медиану всех значений, извлеченных с помощью $path, или из этой коллекции.
Пример:
$items = [
['invoice' => ['total' => 400]],
['invoice' => ['total' => 500]]
['invoice' => ['total' => 100]]
['invoice' => ['total' => 333]]
['invoice' => ['total' => 200]]
];
$total = (new Collection($items))->median('invoice.total');
// Total: 333
$total = (new Collection([1, 2, 3, 4]))->median();
// Total: 2.5 Медиана пустого набора или 0 строк равна null. Коллекции с null значениями не считаются пустыми.
Параметры
-
string|callable|null$path необязательный
Возвращает
float|int|nullmin() 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 необязательный
Возвращает
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 необязательный
Возвращает
selfreduce() 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 необязательный
Возвращает
selfserialize() public
serialize(): string
Возвращает строковое представление этого объекта, которое можно использовать для его восстановления.
Возвращает
stringshuffle() public
shuffle(): self
Возвращает новую коллекцию с элементами в случайном порядке. Эта функция не сохраняет исходные ключи в коллекции.
Возвращает
selfskip() public
skip(int $length): self
Возвращает новую коллекцию, которая пропустит указанное количество элементов в начале итерации.
Параметры
-
int$length
Возвращает
selfsome() public
some(callable $callback): bool
Возвращает true, если хотя бы одно из значений в этой коллекции проходит проверку, заданную в обратном вызове.
Каждый раз при выполнении обратного вызова он получает значение элемента в текущей итерации и ключ элемента в качестве аргументов в указанном порядке.
Пример:
$hasYoungPeople = (new Collection([24, 45, 15]))->every(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 optional -
int$sort optional
Возвращает
selfstopWhen() 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
Возвращает
selfsumOf() public
sumOf(string|callable|null $path = null): float|int
Возвращает общую сумму всех значений, извлеченных с помощью $matcher или из этой коллекции.
Пример:
$items = [
['invoice' => ['total' => 100]],
['invoice' => ['total' => 200]]
];
$total = (new Collection($items))->sumOf('invoice.total');
// Total: 300
$total = (new Collection([1, 2, 3]))->sumOf();
// Total: 6 Параметры
-
string|callable|null$path optional
Возвращает
float|inttake() public
take(int $length = 1, int $offset = 0): self
Возвращает новую коллекцию с максимальным количеством $size элементов в порядке, в котором эта коллекция была создана. Если передать второй параметр, он определит, с какой позиции начинать извлечение элементов.
Параметры
-
int$length optional -
int$offset optional
Возвращает
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 $preserveKeys = true): array
Возвращает массив, представляющий результаты
Параметры
-
bool$preserveKeys optional
Возвращает
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 optional
Возвращает
selfunserialize() public
unserialize(string $collection): void
Десериализует переданную строку и восстанавливает экземпляр коллекции
Параметры
-
string$collection Сериализованная коллекция
Возвращает
voidunwrap() 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Подробности свойств
$_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.2/class-Cake.Collection.Iterator.ExtractIterator.html