Класс StoppableIterator
Создает итератор из другого итератора, который будет проверять условие на каждом шаге. Если условие оценивается как ложь, итератор не будет возвращать больше результатов.
Краткое описание свойств
- $_condition protected
callableУсловие, которое нужно оценить для каждого элемента коллекции
- $_innerIterator protected
TraversableСсылка на внутренний итератор, который оборачивает этот объект.
Краткое описание методов
-
__construct() public
Создаёт итератор, который может быть остановлен на основе условия, заданного обратным вызовом.
-
__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() -
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, которые могут только замедлить процесс итерации.
-
valid() public
Оценивает условие и возвращает его результат; это управляет тем, будут ли выдаваться или нет дополнительные результаты.
-
zip() public
Объединяет элементы этой коллекции с каждым из элементов переданных итерируемых объектов, используя их позиционный индекс в качестве ссылки.
-
zipWith() public
Объединяет элементы этой коллекции с каждым из элементов переданных итерируемых объектов, используя их позиционный индекс в качестве ссылки.
Краткое описание методов
__construct() public
__construct(iterable $items, callable $condition)
Создает итератор, который может быть остановлен на основе условия, заданного обратным вызовом.
Каждый раз при выполнении обратного вызова условия он будет получать значение элемента в текущей итерации, ключ элемента и переданный итератор $items в качестве аргументов, в указанном порядке.
Parameters
-
iterable$items Список значений для итерации
-
callable$condition Функция, которая будет вызываться для каждого элемента в коллекции; если результат вычисляется как false, больше элементов не будут получены из этого итератора.
__debugInfo() public
__debugInfo(): array
Возвращает массив, который можно использовать для описания внутреннего состояния этого объекта.
Returns
array_createMatcherFilter() protected
_createMatcherFilter(array $conditions): Closure
Возвращает вызываемый объект, который получает значение и возвращает, соответствует ли оно определенному условию.
Parameters
-
array$conditions Список условий для соответствия, где ключ — путь к свойству для получения из текущего элемента, а значение — значение, с которым нужно сравнить элемент.
Returns
Closure_extract() protected
_extract(arrayArrayAccess $data, string[] $parts): mixed
Возвращает столбец из $data, который может быть извлечен путем итерации по именам столбцов, содержащимся в $path. Он будет возвращать массивы для элементов, представленных с помощью {*}
Parameters
-
arrayArrayAccess$data Данные.
-
string[]$parts Путь для извлечения из.
Returns
mixed_propertyExtractor() protected
_propertyExtractor(string|callable $path): callable
Возвращает вызываемый объект, который можно использовать для извлечения свойства или столбца из массива или объекта на основе пути, разделенного точками.
Parameters
-
string|callable$path Путь, разделенный точками, столбца, который нужно следовать, чтобы можно было вернуть последний, или вызываемый объект, который позаботится об этом.
Returns
callable_simpleExtract() protected
_simpleExtract(arrayArrayAccess $data, string[] $parts): mixed
Возвращает столбец из $data, который может быть извлечен путем итерации по именам столбцов, содержащимся в $path
Parameters
-
arrayArrayAccess$data Данные.
-
string[]$parts Путь для извлечения из.
Returns
mixedappend() public
append(iterable $items): self
Возвращает новую коллекцию как результат конкатенации списка элементов в этой коллекции с переданным списком элементов
Parameters
-
iterable$items
Returns
selfappendItem() public
appendItem(mixed $item, mixed $key = null): self
Добавить один элемент, создав новую коллекцию.
Parameters
-
mixed$item -
mixed$key optional
Returns
selfavg() public
avg(string|callable|null $path = null): float|int|null
Возвращает среднее значение всех значений, извлеченных с помощью $path или из этой коллекции.
Example:
$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 значениями не считаются пустыми.
Parameters
-
string|callable|null$path optional
Returns
float|int|nullbuffered() public
buffered(): self
Возвращает новую коллекцию, где выполняются операции, выполняемые этой коллекцией. Независимо от того, сколько раз выполняется итерация новой коллекции, эти операции будут выполняться только один раз.
Это также можно использовать для того, чтобы любой неперемотируемый итератор стал перемотируемым.
Returns
selfcartesianProduct() public
cartesianProduct(callable|null $operation = null, callable|null $filter = null): Cake\Collection\CollectionInterface
Создает новую коллекцию, которая является декартовым произведением текущей коллекции
Для создания декартова произведения коллекция должна содержать одно измерение данных.
Example
$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],
]; Parameters
-
callable|null$operation optional Вызываемый объект, позволяющий настраивать результат продукта.
-
callable|null$filter optional Функция фильтрации, которая должна возвращать true, чтобы результат был частью окончательных результатов.
Returns
Cake\Collection\CollectionInterfaceThrows
LogicExceptionchunk() public
chunk(int $chunkSize): self
Разбивает коллекцию на меньшие массивы заданного размера.
Example:
$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]]
Parameters
-
int$chunkSize
Returns
selfchunkWithKeys() public
chunkWithKeys(int $chunkSize, bool $preserveKeys = true): self
Разбивает коллекцию на меньшие массивы заданного размера.
Example:
$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]]
Parameters
-
int$chunkSize -
bool$preserveKeys optional
Returns
selfcombine() public
combine(callable|string $keyPath, callable|string $valuePath, callable|string|null $groupPath = null): self
Возвращает новую коллекцию, где значения извлекаются на основе пути к значению, а затем индексируются по пути к ключу. Дополнительно этот метод может создавать родительские группы на основе пути к свойству группы.
Examples:
$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']
]; Parameters
-
callable|string$keyPath -
callable|string$valuePath -
callable|string|null$groupPath optional
Returns
selfcompile() public
compile(bool $preserveKeys = true): self
Выполняет итерацию по всем элементам в этой коллекции и выполняет все накопленные операции над ними, наконец, возвращает новую коллекцию с результатом. Это полезно для преобразования неперемотируемых внутренних итераторов в коллекцию, которая может быть перемотана и использована несколько раз.
Распространенный сценарий использования — повторное использование одной и той же переменной для вычисления различных данных. В таких случаях может быть полезно и эффективнее сначала скомпилировать коллекцию, а затем применить к ней дополнительные операции.
Example:
$collection->map($mapper)->sortBy('age')->extract('name');
$compiled = $collection->compile();
$isJohnHere = $compiled->some($johnMatcher);
$allButJohn = $compiled->filter($johnMatcher); В приведенном выше примере, если бы коллекция не была скомпилирована ранее, итерации для map, sortBy и extract были бы выполнены дважды: один раз для получения $isJohnHere и один раз для $allButJohn
Можно рассматривать этот метод как способ создания контрольных точек для сложных вычислений в коллекции.
Parameters
-
bool$preserveKeys optional
Returns
selfcontains() public
contains(mixed $value): bool
Возвращает true, если $value присутствует в этой коллекции. Сравнения выполняются как по значению, так и по типу.
Parameters
-
mixed$value
Returns
boolcount() public
count(): int
Возвращает количество элементов в коллекции.
ПРЕДУПРЕЖДЕНИЯ:
Изменит текущую позицию итератора:
Вызов этого метода одновременно с итерацией по этой коллекции, например, в цикле foreach, приведёт к неопределённому поведению. Избегайте этого.
Потребляет все элементы для коллекций NoRewindIterator:
В некоторых типах коллекций вызов этого метода может сделать их непригодными для дальнейшего использования. То есть вы больше не сможете извлекать из них элементы или итерироваться по ним.
В частности, любая коллекция, оборачивающая генератор (функция с оператором 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()
Возвращает
inteach() 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
Возвращает наибольший элемент в этой коллекции после сортировки по свойству. Сведения об обратном вызове и параметре $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(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
Возвращает наименьший элемент в этой коллекции после сортировки по свойству. Сведения об обратном вызове и параметре $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 необязательный
Возвращает
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;
}); Parameters
-
callable$callback
Returns
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;
} Parameters
-
callable|string$path -
int$order optional -
int$sort optional
Returns
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]);
Parameters
-
callable|array$condition
Returns
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 Parameters
-
string|callable|null$path optional
Returns
float|inttake() public
take(int $length = 1, int $offset = 0): self
Возвращает новую коллекцию с максимальным количеством элементов $size во внутреннем порядке, в котором была создана эта коллекция. Если передан второй параметр, он определит, с какой позиции начинать брать элементы.
Parameters
-
int$length optional -
int$offset optional
Returns
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];
Parameters
-
int$length
Returns
selfthrough() public
through(callable $callback): self
Пропускает эту коллекцию через вызываемый объект в качестве своего первого аргумента. Это полезно для декорирования всей коллекции другим объектом.
Пример:
$items = [1, 2, 3];
$decorated = (new Collection($items))->through(function ($collection) {
return new MyCustomCollection($collection);
}); Parameters
-
callable$callback
Returns
selftoArray() public
toArray(bool $preserveKeys = true): array
Возвращает массивное представление результатов
Parameters
-
bool$preserveKeys optional
Returns
arraytoList() public
toList(): array
Возвращает числовое индексированное массивное представление результатов. Это эквивалентно вызову toArray(false)
Returns
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'],
// ] Returns
Cake\Collection\CollectionInterfaceThrows
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();
}); Parameters
-
callable|null$callback optional
Returns
selfunserialize() public
unserialize(string $collection): void
Рассерялизует переданную строку и перестраивает экземпляр коллекции
Parameters
-
string$collection Сериализованная коллекция
Returns
voidunwrap() public
unwrap(): Traversable
Возвращает ближайший вложенный итератор, который можно безопасно пройти без потери каких-либо возможных преобразований. Это используется в основном для удаления пустых оболочек IteratorIterator, которые могут только замедлить процесс итерации.
Returns
Traversablevalid() public
valid(): bool
Оценивает условие и возвращает его результат, это контролирует, будут ли получены дополнительные результаты.
Returns
boolzip() public
zip(iterable $items): self
Объединяет элементы этой коллекции с каждым из элементов переданных итерируемых объектов, используя их позиционный индекс в качестве ссылки.
Пример:
$collection = new Collection([1, 2]); $collection->zip([3, 4], [5, 6])->toList(); // returns [[1, 3, 5], [2, 4, 6]]
Parameters
-
iterable$items
Returns
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)] Parameters
-
iterable$items -
callable$callback
Returns
selfПодробное описание свойств
$_condition protected
Условие для оценки каждого элемента коллекции
Type
callable$_innerIterator protected
Ссылка на внутренний итератор, который оборачивает этот объект.
Type
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.2/class-Cake.Collection.Iterator.StoppableIterator.html