Интерфейс CollectionInterface

append()source public

append( array|Traversable $items )

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

Параметры

array|Traversable $items

Список элементов.

Возвращает

Cake\Collection\CollectionInterface

avg()source public

avg( string|callable|null $matcher null )

Возвращает среднее значение всех значений, извлечённых с помощью $matcher или из этой коллекции.

Пример:

$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

Параметры

string|callable|null $matcher optional null

Имя свойства для суммирования или функция, которая возвращает значение свойства для суммирования. Если значение не передано, будет использована функция тождества.

Возвращает

float|integer|null

buffered()source public

buffered( )

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

Это также можно использовать для преобразования любого неперематываемого итератора в перематываемый.

Возвращает

Cake\Collection\CollectionInterface

chunk()source public

chunk( integer $chunkSize )

Разбивает коллекцию на меньшие массивы заданного размера.

Пример:

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

Устарело

4.0.0 Устарело в пользу chunks

Параметры

integer $chunkSize

Максимальный размер каждого куска

Возвращает

Cake\Collection\CollectionInterface

chunkWithKeys()source public

chunkWithKeys( integer $chunkSize , boolean $preserveKeys true )

Разбивает коллекцию на меньшие массивы заданного размера.

Пример:

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

Параметры

integer $chunkSize

Максимальный размер каждого куска

boolean $preserveKeys optional true

Если ключи массива должны быть сохранены

Возвращает

Cake\Collection\CollectionInterface

combine()source public

combine( callable|string $keyPath , callable|string $valuePath , callable|string|null $groupPath null )

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

Примеры:

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

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

Возвращает

Cake\Collection\CollectionInterface

compile()source public

compile( boolean $preserveKeys true )

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

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

Пример:

$collection->map($mapper)->sortBy('age')->extract('name');
$compiled = $collection->compile();
$isJohnHere = $compiled->some($johnMatcher);
$allButJohn = $compiled->filter($johnMatcher);

В приведенном выше примере, если бы коллекция не была скомпилирована предварительно, итерации для map, sortBy и extract были бы выполнены дважды: один раз для получения $isJohnHere и один раз для $allButJohn

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

Параметры

boolean $preserveKeys optional true

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

Возвращает

Cake\Collection\CollectionInterface

contains()source public

contains( mixed $value )

Возвращает true, если $value присутствует в этой коллекции. Сравнения выполняются по значению и типу.

Параметры

mixed $value

Значение для проверки

Возвращает

boolean
true, если $value присутствует в этой коллекции

countBy()source public

countBy( callable|string $callback )

Сортирует список в группы и возвращает количество элементов в каждой группе. Похоже на 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 $callback

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

Возвращает

Cake\Collection\CollectionInterface

each()source public

each( callable $c )

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

Пример:

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

Параметры

callable $c

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

Возвращает

Cake\Collection\CollectionInterface

every()source public

every( callable $c )

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

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

Пример:

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

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

Параметры

callable $c

функция обратного вызова

Возвращает

boolean

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

extract()source public

extract( string $matcher )

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

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

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

Параметры

строка $matcher

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

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

Cake\Collection\CollectionInterface

filter()source public

filter( callable $c null )

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

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

Пример:

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

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

Параметры

вызов $c необязательно null

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

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

Cake\Collection\CollectionInterface

first()source public

first( )

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

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

mixed
Будет возвращено первое значение в коллекции.

firstMatch()source public

firstMatch( array $conditions )

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

Параметры

массив $conditions

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

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

mixed

См. также

\Cake\Collection\CollectionInterface::match()

groupBy()source public

groupBy( callable|string $callback )

Разделяет коллекцию на наборы, сгруппированные по результату применения обратного вызова к каждому значению. Если $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],
 ]
];

Параметры

вызываемый объект|строка $callback

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

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

Cake\Collection\CollectionInterface

indexBy()source public

indexBy( callable|string $callback )

Принимает список и функцию обратного вызова, возвращающую ключ для каждого элемента в списке (или имя свойства), и возвращает объект с индексом каждого элемента. Похоже на 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'],
];

Параметры

вызываемый объект|строка $callback

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

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

Cake\Collection\CollectionInterface

insert()source public

insert( string $path , mixed $values )

Возвращает новую коллекцию, содержащую каждый из элементов, найденных в $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]]
];

Параметры

строка $path

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

смешанное $values

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

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

Cake\Collection\CollectionInterface

isEmpty()source public

isEmpty( )

Возвращает значение, указывает ли коллекция на наличие элементов.

Пример:

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

(new Collection([]))->isEmpty(); // true

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

boolean

jsonSerialize()source public

jsonSerialize( )

Преобразование набора результатов в JSON.

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

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

массив
Данные для преобразования в JSON

Реализация

JsonSerializable::jsonSerialize()

last()source public

last( )

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

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

mixed
Будет возвращено последнее значение в коллекции.

listNested()source public

listNested( string|integer $dir 'desc' , string|callable $nestingKey 'children' )

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

По умолчанию возвращаются все элементы дерева, следуя поиску в глубину (Depth First Search), то есть элементы от родительского элемента к листьям каждого ветвления.

Возможна обработка элементов снизу вверх (Breadth First Search), передав параметр $dir со значением 'asc'. То есть будут возвращены все элементы для каждого уровня дерева, сначала, и от нижних элементов к верхним.

Наконец, вы можете получить только листья в структуре дерева, передав 'leaves' в первый аргумент.

Возможные значения для первого аргумента являются псевдонимами следующих констант, и вы можете передать вместо псевдонима и эти константы:

• desc: TreeIterator::SELF_FIRST
• asc: TreeIterator::CHILD_FIRST
• leaves: TreeIterator::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]

Параметры

строка|целое число $dir необязательно 'desc'

Направление возврата элементов

строка|вызываемый объект $nestingKey необязательно 'children'

Имя ключа, под которым вложены дочерние элементы, или функция обратного вызова, которая вернёт список дочерних элементов.

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

Cake\Collection\CollectionInterface

map()source public

map( callable $c )

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

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

Пример:

Получение коллекции булевых значений, где true указывает, является ли человек женщиной:

$collection = (new Collection($people))->map(function ($person, $key) {
 return $person->gender === 'female';
});

Параметры

вызываемый объект $c

метод, который примет каждый из элементов и вернёт новое значение для ключа, по которому происходит итерация

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

Cake\Collection\CollectionInterface

match()source public

match( array $conditions )

Просматривает каждое значение в списке, возвращая коллекцию всех значений, содержащих все пары «ключ-значение», перечисленные в $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']]
]

Параметры

массив $conditions

список «ключ-значение» условий, где ключ — путь к свойству, принятому `Collection::extract`, а значение — условие, с которым будет сравниваться каждый элемент.

Возвращает

Cake\Collection\CollectionInterface

max()source public

max( callable|string $callback , integer $type SORT_NUMERIC )

Возвращает верхний элемент в этой коллекции после сортировки по свойству. См. метод sortBy для информации о параметрах callback и $type.

Примеры:

// 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;

Параметры

функция/строка $callback

функция обратного вызова или имя столбца для сортировки

целое число $type необязательно SORT_NUMERIC

тип сравнения: SORT_STRING, SORT_NUMERIC или SORT_NATURAL

Возвращает

mixed
Значение верхнего элемента в коллекции

См. также

\Cake\Collection\CollectionIterface::sortBy()

median()source public

median( string|callable|null $matcher null )

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

Пример:

$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

Параметры

строка/функция/null $matcher необязательно null

Имя свойства для суммирования или функция. Если значение не передано, будет использована функция тождества, возвращающая значение свойства для суммирования.

Возвращает

float|integer|null

min()source public

min( callable|string $callback , integer $type SORT_NUMERIC )

Возвращает нижний элемент в этой коллекции после сортировки по свойству. См. метод sortBy для информации о параметрах callback и $type.

Примеры:

// 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;

Параметры

функция/строка $callback

функция обратного вызова или имя столбца для сортировки

целое число $type необязательно SORT_NUMERIC

тип сравнения: SORT_STRING, SORT_NUMERIC или SORT_NATURAL

Возвращает

mixed
Значение нижнего элемента в коллекции

См. также

\Cake\Collection\CollectionInterface::sortBy()

nest()source public

nest( callable|string $idPath , callable|string $parentPath , string $nestingKey 'children' )

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

Параметры

функция/строка $idPath

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

функция/строка $parentPath

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

строка $nestingKey необязательно 'children'

Имя ключа, под которым вложены дети

Возвращает

Cake\Collection\CollectionInterface

reduce()source public

reduce( callable $c , mixed $zero null )

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

Параметры

функция обратного вызова $c

функция обратного вызова

смешанное значение $zero необязательно null

состояние редукции

Возвращает

mixed

reject()source public

reject( callable $c )

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

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

Пример:

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

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

Параметры

функция обратного вызова $c

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

Возвращает

Cake\Collection\CollectionInterface

sample()source public

sample( integer $size 10 )

Возвращает новую коллекцию с максимальным $size случайных элементов из этой коллекции

Параметры

целое число $size необязательно 10

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

Возвращает

Cake\Collection\CollectionInterface

shuffle()source public

shuffle( )

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

Возвращает

Cake\Collection\CollectionInterface

skip()source public

skip( integer $howMany )

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

Параметры

целое число $howMany

Количество элементов для пропуска.

Возвращает

Cake\Collection\CollectionInterface

some()source public

some( callable $c )

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

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

Пример:

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

Параметры

функция обратного вызова $c

функция обратного вызова

Возвращает

boolean

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

sortBy()source public

sortBy( callable|string $callback , integer $dir SORT_DESC , integer $type SORT_NUMERIC )

Возвращает итератор, отсортированный по элементам этой коллекции в порядке возрастания, основываясь на результатах применения функции обратного вызова к каждому значению. $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;
}

Параметры

функция/строка $callback

функция обратного вызова или имя столбца для сортировки

целое число $dir необязательно SORT_DESC

SORT_DESC или SORT_ASC

целое число $type необязательно SORT_NUMERIC

тип сравнения: SORT_STRING, SORT_NUMERIC или SORT_NATURAL

Возвращает

Cake\Collection\CollectionInterface

stopWhen()source public

stopWhen( callable $condition )

Создаёт новую коллекцию, которая при итерации прекратит выдавать результаты, если предоставленное условие примет значение false.

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

Пример:

Получение массива строк в файле 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 $condition

метод, который получит каждый из элементов и вернёт false, когда итерация должна быть остановлена. Если это массив, он будет интерпретирован как список ключевых значений условий, где ключ — это путь к свойству, принятый Collection::extract, а значение — условие, которое будет сопоставлено с каждым элементом.

Возвращает

Cake\Collection\CollectionInterface

sumOf()source public

sumOf( string|callable|null $matcher null )

Возвращает общую сумму всех значений, извлечённых с помощью $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 $matcher необязательно null

Имя свойства для суммирования или функция. Если значение не передано, будет использована функция идентичности. Функция, которая вернёт значение свойства для суммирования.

Возвращает

float|integer

take()source public

take( integer $size 1 , integer $from 0 )

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

Параметры

integer $size необязательно 1

максимальное количество элементов для извлечения из этой коллекции

integer $from необязательно 0

Позиционное смещение, с которого начинать извлечение элементов

Возвращает

Cake\Collection\CollectionInterface

through()source public

through( callable $handler )

Передаёт эту коллекцию в качестве первого аргумента вызываемой функции. Это полезно для декорирования всей коллекции другим объектом.

Пример:

$items = [1, 2, 3];
$decorated = (new Collection($items))->through(function ($collection) {
     return new MyCustomCollection($collection);
});

Параметры

callable $handler

Вызываемая функция, которая получит эту коллекцию в качестве первого аргумента.

Возвращает

Cake\Collection\CollectionInterface

toArray()source public

toArray( boolean $preserveKeys true )

Возвращает массив, представляющий результаты.

Параметры

boolean $preserveKeys необязательно true

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

Возвращает

array

toList()source public

toList( )

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

Возвращает

array

transpose()source public

transpose( )

Транспонирует строки и столбцы в столбцы и строки

Пример:

$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

unfold()source public

unfold( callable $transformer null )

Создаёт новую коллекцию, где элементы являются конкатенацией списков элементов, сгенерированных функцией преобразования, применённой к каждому элементу исходной коллекции.

Функция преобразования получит значение и ключ для каждого элемента в коллекции в указанном порядке, и она должна вернуть массив или объект 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 $transformer необязательно null

Вызываемая функция, которая получит каждый из элементов коллекции и должна вернуть массив или объект Traversable

Возвращает

Cake\Collection\CollectionInterface

unwrap()source public

unwrap( )

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

Возвращает

Traversable

zip()source public

zip( array|Traversable $items )

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

Пример:

$collection = new Collection([1, 2]);
$collection->zip([3, 4], [5, 6])->toList(); // returns [[1, 3, 5], [2, 4, 6]]

Параметры

array|Traversable $items

$items Коллекции для объединения.

Возвращает

Cake\Collection\CollectionInterface

zipWith()source public

zipWith( array|Traversable $items , callable $callable )

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

Результат будет значением возвращаемым функцией $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)]

Параметры

array|Traversable $items

$items Коллекции для объединения.

callable $callable

Функция для объединения элементов.

Возвращает

Cake\Collection\CollectionInterface