Represents the results obtained after executing a query for a specific table This object is responsible for correctly nesting result keys reported from the query, casting each field to the correct type and executing the extra queries required for eager loading external associations.
bool|nullTracks value of $_autoFields property of $query passed to constructor.
arrayList of associations that should be eager loaded.
intHolds the count of records in this result set
object|arrayLast record fetched from the statement
stringThe default table alias
Cake\ORM\TableDefault table instance
Cake\Database\DriverInterfaceThe Database driver object.
stringThe fully namespaced name of the class to use for hydrating results
boolWhether to hydrate results into objects or not
intPoints to the next record number that should be fetched
array<string, mixed>Map of fields that are fetched from the statement with their type and the table they belong to
array<string, mixed>List of associations that should be placed under the _matchingData result key.
array<string, mixed>List of matching associations and the column keys to expect from each of them.
SplFixedArray|arrayResults that have been fetched or hydrated into the results.
Cake\Database\StatementInterfaceDatabase statement holding the results
boolWhether to buffer results fetched from the statement
Constructor
Returns an array that can be used to describe the internal state of this object.
Serializes a resultset.
Unserializes a resultset.
Calculates the list of associations that should get eager loaded when fetching each record
Creates a map of row keys out of the query select clause that can be used to hydrate nested result sets more quickly.
Returns a callable that receives a value and will return whether it matches certain condition.
Returns a column from $data that can be extracted by iterating over the column names contained in $path. It will return arrays for elements in represented with {*}
Helper function to fetch the next result from the statement or seeded results.
Correctly nests results keys including those coming from associations
Returns a callable that can be used to extract a property or column from an array or object based on a dot separated path.
Returns a column from $data that can be extracted by iterating over the column names contained in $path
Returns a new collection as the result of concatenating the list of elements in this collection with the passed list of elements
Append a single item creating a new collection.
Returns the average of all the values extracted with $path or of this collection.
Returns a new collection where the operations performed by this collection. No matter how many times the new collection is iterated, those operations will only be performed once.
Create a new collection that is the cartesian product of the current collection
Breaks the collection into smaller arrays of the given size.
Breaks the collection into smaller arrays of the given size.
Returns a new collection where the values extracted based on a value path and then indexed by a key path. Optionally this method can produce parent groups based on a group property path.
Iterates once all elements in this collection and executes all stacked operations of them, finally it returns a new collection with the result. This is useful for converting non-rewindable internal iterators into a collection that can be rewound and used multiple times.
Returns true if $value is present in this collection. Comparisons are made both by value and type.
Gives the number of rows in the result set.
Sorts a list into groups and returns a count for the number of elements in each group. Similar to groupBy, but instead of returning a list of values, returns a count for the number of values in that group.
Returns the number of unique keys in this iterator. This is the same as the number of elements the collection will contain after calling toArray()
Returns the current record in the result iterator
Applies a callback to the elements in this collection.
Returns true if all values in this collection pass the truth test provided in the callback.
Returns a new collection containing the column or property value found in each of the elements.
Looks through each value in the collection, and returns another collection with all the values that pass a truth test. Only the values for which the callback returns true will be present in the resulting collection.
Get the first record from a result set.
Returns the first result matching all the key-value pairs listed in conditions.
Splits a collection into sets, grouped by the result of running each value through the callback. If $callback is a string instead of a callable, groups by the property named by $callback on each of the values.
Given a list and a callback function that returns a key for each element in the list (or a property name), returns an object with an index of each item. Just like groupBy, but for when you know your keys are unique.
Returns a new collection containing each of the elements found in $values as a property inside the corresponding elements in this collection. The property where the values will be inserted is described by the $path parameter.
Returns whether there are elements in this collection
Returns the data that can be converted to JSON. This returns the same data as toArray() which contains only unique keys.
Returns the key of the current record in the iterator
Returns the last result in this collection
Returns a new collection where any operations chained after it are guaranteed to be run lazily. That is, elements will be yieleded one at a time.
Returns a new collection with each of the elements of this collection after flattening the tree structure. The tree structure is defined by nesting elements under a key with a known name. It is possible to specify such name by using the '$nestingKey' parameter.
Returns another collection after modifying each of the values in this one using the provided callable.
Looks through each value in the list, returning a Collection of all the values that contain all of the key-value pairs listed in $conditions.
Returns the top element in this collection after being sorted by a property. Check the sortBy method for information on the callback and $sort parameters
Returns the median of all the values extracted with $path or of this collection.
Returns the bottom element in this collection after being sorted by a property. Check the sortBy method for information on the callback and $sort parameters
Returns a new collection where the values are nested in a tree-like structure based on an id property path and a parent id property path.
Returns a new collection.
Advances the iterator pointer to the next record
Unwraps this iterator and returns the simplest traversable that can be used for getting the data out
Prepend a set of items to a collection creating a new collection
Prepend a single item creating a new collection.
Folds the values in this collection to a single value, as the result of applying the callback function to all elements. $zero is the initial state of the reduction, and each successive step of it should be returned by the callback function. If $zero is omitted the first value of the collection will be used in its place and reduction will start from the second item.
Looks through each value in the collection, and returns another collection with all the values that do not pass a truth test. This is the opposite of filter.
Rewinds a ResultSet.
Returns a new collection with maximum $size random elements from this collection
Serializes a resultset.
Returns a new collection with the elements placed in a random order, this function does not preserve the original keys in the collection.
Returns a new collection that will skip the specified amount of elements at the beginning of the iteration.
Returns true if any of the values in this collection pass the truth test provided in the callback.
Returns a sorted iterator out of the elements in this collection, ranked in ascending order by the results of running each value through a callback. $callback can also be a string representing the column or property name.
Creates a new collection that when iterated will stop yielding results if the provided condition evaluates to true.
Returns the total sum of all the values extracted with $matcher or of this collection.
Returns a new collection with maximum $size elements in the internal order this collection was created. If a second parameter is passed, it will determine from what position to start taking elements.
Returns the last N elements of a collection
Passes this collection through a callable as its first argument. This is useful for decorating the full collection with another object.
Returns an array representation of the results
Returns an numerically-indexed array representation of the results. This is equivalent to calling toArray(false)
Transpose rows and columns into columns and rows
Creates a new collection where the items are the concatenation of the lists of items generated by the transformer function applied to each item in the original collection.
Unserializes a resultset.
Returns the closest nested iterator that can be safely traversed without losing any possible transformations. This is used mainly to remove empty IteratorIterator wrappers that can only slowdown the iteration process.
Whether there are more results to be fetched from the iterator
Combines the elements of this collection with each of the elements of the passed iterables, using their positional index as a reference.
Combines the elements of this collection with each of the elements of the passed iterables, using their positional index as a reference.
__construct(Cake\ORM\Query $query, Cake\Database\StatementInterface $statement)
Constructor
Cake\ORM\Query $query Query from where results come
Cake\Database\StatementInterface $statement The statement to fetch from
__debugInfo(): array<string, mixed>
Returns an array that can be used to describe the internal state of this object.
array<string, mixed>__serialize(): array
Serializes a resultset.
array__unserialize(array $data): void
Unserializes a resultset.
array $data Data array.
void_calculateAssociationMap(Cake\ORM\Query $query): void
Calculates the list of associations that should get eager loaded when fetching each record
Cake\ORM\Query $query The query from where to derive the associations
void_calculateColumnMap(Cake\ORM\Query $query): void
Creates a map of row keys out of the query select clause that can be used to hydrate nested result sets more quickly.
Cake\ORM\Query $query The query from where to derive the column map
void_createMatcherFilter(array $conditions): Closure
Returns a callable that receives a value and will return whether it matches certain condition.
array $conditions A key-value list of conditions to match where the key is the property path to get from the current item and the value is the value to be compared the item with.
Closure_extract(ArrayAccess|array $data, array<string> $parts): mixed
Returns a column from $data that can be extracted by iterating over the column names contained in $path. It will return arrays for elements in represented with {*}
ArrayAccess|array $data Data.
array<string> $parts Path to extract from.
mixed_fetchResult(): mixed
Helper function to fetch the next result from the statement or seeded results.
mixed_groupResult(array $row): Cake\Datasource\EntityInterface|array
Correctly nests results keys including those coming from associations
array $row Array containing columns and values or false if there is no results
Cake\Datasource\EntityInterface|array_propertyExtractor(callable|string $path): callable
Returns a callable that can be used to extract a property or column from an array or object based on a dot separated path.
callable|string $path A dot separated path of column to follow so that the final one can be returned or a callable that will take care of doing that.
callable_simpleExtract(ArrayAccess|array $data, array<string> $parts): mixed
Returns a column from $data that can be extracted by iterating over the column names contained in $path
ArrayAccess|array $data Data.
array<string> $parts Path to extract from.
mixedappend(iterable $items): self
Returns a new collection as the result of concatenating the list of elements in this collection with the passed list of elements
iterable $items selfappendItem(mixed $item, mixed $key = null): self
Append a single item creating a new collection.
mixed $item mixed $key optional selfavg(callable|string|null $path = null): float|int|null
Returns the average of all the values extracted with $path or of this collection.
$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 The average of an empty set or 0 rows is null. Collections with null values are not considered empty.
callable|string|null $path optional float|int|nullbuffered(): self
Returns a new collection where the operations performed by this collection. No matter how many times the new collection is iterated, those operations will only be performed once.
This can also be used to make any non-rewindable iterator rewindable.
selfcartesianProduct(callable|null $operation = null, callable|null $filter = null): Cake\Collection\CollectionInterface
Create a new collection that is the cartesian product of the current collection
In order to create a carteisan product a collection must contain a single dimension of data.
$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 A callable that allows you to customize the product result.
callable|null $filter optional A filtering callback that must return true for a result to be part of the final results.
Cake\Collection\CollectionInterfaceLogicExceptionchunk(int $chunkSize): self
Breaks the collection into smaller arrays of the given size.
$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(int $chunkSize, bool $keepKeys = true): self
Breaks the collection into smaller arrays of the given size.
$items ['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5, 'f' => 6]; $chunked = (new Collection($items))->chunkWithKeys(3)->toList(); // Returns [['a' => 1, 'b' => 2, 'c' => 3], ['d' => 4, 'e' => 5, 'f' => 6]]
int $chunkSize bool $keepKeys optional selfcombine(callable|string $keyPath, callable|string $valuePath, callable|string|null $groupPath = null): self
Returns a new collection where the values extracted based on a value path and then indexed by a key path. Optionally this method can produce parent groups based on a group property path.
$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(bool $keepKeys = true): self
Iterates once all elements in this collection and executes all stacked operations of them, finally it returns a new collection with the result. This is useful for converting non-rewindable internal iterators into a collection that can be rewound and used multiple times.
A common use case is to re-use the same variable for calculating different data. In those cases it may be helpful and more performant to first compile a collection and then apply more operations to it.
$collection->map($mapper)->sortBy('age')->extract('name');
$compiled = $collection->compile();
$isJohnHere = $compiled->some($johnMatcher);
$allButJohn = $compiled->filter($johnMatcher); In the above example, had the collection not been compiled before, the iterations for map, sortBy and extract would've been executed twice: once for getting $isJohnHere and once for $allButJohn
You can think of this method as a way to create save points for complex calculations in a collection.
bool $keepKeys optional selfcontains(mixed $value): bool
Returns true if $value is present in this collection. Comparisons are made both by value and type.
mixed $value boolcount(): int
Gives the number of rows in the result set.
Part of the Countable interface.
intcountBy(callable|string $path): self
Sorts a list into groups and returns a count for the number of elements in each group. Similar to groupBy, but instead of returning a list of values, returns a count for the number of values in that group.
When $callback is a string it should be a property name to extract or a dot separated path of properties that should be followed to get the last one in the path.
$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(): int
Returns the number of unique keys in this iterator. This is the same as the number of elements the collection will contain after calling toArray()
This method comes with a number of caveats. Please refer to CollectionInterface::count() for details.
intcurrent(): object|array
Returns the current record in the result iterator
Part of Iterator interface.
object|arrayeach(callable $callback): $this
Applies a callback to the elements in this collection.
$collection = (new Collection($items))->each(function ($value, $key) {
echo "Element $key: $value";
}); callable $callback $thisevery(callable $callback): bool
Returns true if all values in this collection pass the truth test provided in the callback.
The callback is passed the value and key of the element being tested and should return true if the test passed.
$overTwentyOne = (new Collection([24, 45, 60, 15]))->every(function ($value, $key) {
return $value > 21;
}); Empty collections always return true.
callable $callback boolextract(callable|string $path): self
Returns a new collection containing the column or property value found in each of the elements.
The matcher can be a string with a property name to extract or a dot separated path of properties that should be followed to get the last one in the path.
If a column or property could not be found for a particular element in the collection, that position is filled with null.
Extract the user name for all comments in the array:
$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'] It is also possible to extract a flattened collection out of nested properties
$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] callable|string $path selffilter(callable|null $callback = null): self
Looks through each value in the collection, and returns another collection with all the values that pass a truth test. Only the values for which the callback returns true will be present in the resulting collection.
Each time the callback is executed it will receive the value of the element in the current iteration, the key of the element and this collection as arguments, in that order.
Filtering odd numbers in an array, at the end only the value 2 will be present in the resulting collection:
$collection = (new Collection([1, 2, 3]))->filter(function ($value, $key) {
return $value % 2 === 0;
}); callable|null $callback optional selffirst(): object|array|null
Get the first record from a result set.
This method will also close the underlying statement cursor.
object|array|nullfirstMatch(array $conditions): mixed
Returns the first result matching all the key-value pairs listed in conditions.
array $conditions mixedgroupBy(callable|string $path): self
Splits a collection into sets, grouped by the result of running each value through the callback. If $callback is a string instead of a callable, groups by the property named by $callback on each of the values.
When $callback is a string it should be a property name to extract or a dot separated path of properties that should be followed to get the last one in the path.
$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(callable|string $path): self
Given a list and a callback function that returns a key for each element in the list (or a property name), returns an object with an index of each item. Just like groupBy, but for when you know your keys are unique.
When $callback is a string it should be a property name to extract or a dot separated path of properties that should be followed to get the last one in the path.
$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(string $path, mixed $values): self
Returns a new collection containing each of the elements found in $values as a property inside the corresponding elements in this collection. The property where the values will be inserted is described by the $path parameter.
The $path can be a string with a property name or a dot separated path of properties that should be followed to get the last one in the path.
If a column or property could not be found for a particular element in the collection as part of the path, the element will be kept unchanged.
Insert ages into a collection containing users:
$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(): bool
Returns whether there are elements in this collection
$items [1, 2, 3]; (new Collection($items))->isEmpty(); // false
(new Collection([]))->isEmpty(); // true
booljsonSerialize(): array
Returns the data that can be converted to JSON. This returns the same data as toArray() which contains only unique keys.
Part of JsonSerializable interface.
arraykey(): int
Returns the key of the current record in the iterator
Part of Iterator interface.
intlast(): mixed
Returns the last result in this collection
mixedlazy(): self
Returns a new collection where any operations chained after it are guaranteed to be run lazily. That is, elements will be yieleded one at a time.
A lazy collection can only be iterated once. A second attempt results in an error.
selflistNested(string|int $order = 'desc', callable|string $nestingKey = 'children'): self
Returns a new collection with each of the elements of this collection after flattening the tree structure. The tree structure is defined by nesting elements under a key with a known name. It is possible to specify such name by using the '$nestingKey' parameter.
By default all elements in the tree following a Depth First Search will be returned, that is, elements from the top parent to the leaves for each branch.
It is possible to return all elements from bottom to top using a Breadth First Search approach by passing the '$dir' parameter with 'asc'. That is, it will return all elements for the same tree depth first and from bottom to top.
Finally, you can specify to only get a collection with the leaf nodes in the tree structure. You do so by passing 'leaves' in the first argument.
The possible values for the first argument are aliases for the following constants and it is valid to pass those instead of the alias:
$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 optional callable|string $nestingKey optional selfmap(callable $callback): self
Returns another collection after modifying each of the values in this one using the provided callable.
Each time the callback is executed it will receive the value of the element in the current iteration, the key of the element and this collection as arguments, in that order.
Getting a collection of booleans where true indicates if a person is female:
$collection = (new Collection($people))->map(function ($person, $key) {
return $person->gender === 'female';
}); callable $callback selfmatch(array $conditions): self
Looks through each value in the list, returning a Collection of all the values that contain all of the key-value pairs listed in $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(callable|string $path, int $sort = \SORT_NUMERIC): mixed
Returns the top element in this collection after being sorted by a property. Check the sortBy method for information on the callback and $sort parameters
// 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 optional mixedmedian(callable|string|null $path = null): float|int|null
Returns the median of all the values extracted with $path or of this collection.
$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 The median of an empty set or 0 rows is null. Collections with null values are not considered empty.
callable|string|null $path optional float|int|nullmin(callable|string $path, int $sort = \SORT_NUMERIC): mixed
Returns the bottom element in this collection after being sorted by a property. Check the sortBy method for information on the callback and $sort parameters
// 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 optional mixednest(callable|string $idPath, callable|string $parentPath, string $nestingKey = 'children'): self
Returns a new collection where the values are nested in a tree-like structure based on an id property path and a parent id property path.
callable|string $idPath callable|string $parentPath string $nestingKey optional selfnewCollection(mixed ...$args): Cake\Collection\CollectionInterface
Returns a new collection.
Allows classes which use this trait to determine their own type of returned collection interface
mixed ...$args Constructor arguments.
Cake\Collection\CollectionInterfacenext(): void
Advances the iterator pointer to the next record
Part of Iterator interface.
voidoptimizeUnwrap(): iterable
Unwraps this iterator and returns the simplest traversable that can be used for getting the data out
iterableprepend(mixed $items): self
Prepend a set of items to a collection creating a new collection
mixed $items selfprependItem(mixed $item, mixed $key = null): self
Prepend a single item creating a new collection.
mixed $item mixed $key optional selfreduce(callable $callback, mixed $initial = null): mixed
Folds the values in this collection to a single value, as the result of applying the callback function to all elements. $zero is the initial state of the reduction, and each successive step of it should be returned by the callback function. If $zero is omitted the first value of the collection will be used in its place and reduction will start from the second item.
callable $callback mixed $initial optional mixedreject(callable $callback): self
Looks through each value in the collection, and returns another collection with all the values that do not pass a truth test. This is the opposite of filter.
Each time the callback is executed it will receive the value of the element in the current iteration, the key of the element and this collection as arguments, in that order.
Filtering even numbers in an array, at the end only values 1 and 3 will be present in the resulting collection:
$collection = (new Collection([1, 2, 3]))->reject(function ($value, $key) {
return $value % 2 === 0;
}); callable $callback selfrewind(): void
Rewinds a ResultSet.
Part of Iterator interface.
voidCake\Database\Exception\DatabaseExceptionsample(int $length = 10): self
Returns a new collection with maximum $size random elements from this collection
int $length optional selfserialize(): string
Serializes a resultset.
Part of Serializable interface.
stringshuffle(): self
Returns a new collection with the elements placed in a random order, this function does not preserve the original keys in the collection.
selfskip(int $length): self
Returns a new collection that will skip the specified amount of elements at the beginning of the iteration.
int $length selfsome(callable $callback): bool
Returns true if any of the values in this collection pass the truth test provided in the callback.
The callback is passed the value and key of the element being tested and should return true if the test passed.
$hasYoungPeople = (new Collection([24, 45, 15]))->some(function ($value, $key) {
return $value < 21;
}); callable $callback boolsortBy(callable|string $path, int $order = \SORT_DESC, int $sort = \SORT_NUMERIC): self
Returns a sorted iterator out of the elements in this collection, ranked in ascending order by the results of running each value through a callback. $callback can also be a string representing the column or property name.
The callback will receive as its first argument each of the elements in $items, the value returned by the callback will be used as the value for sorting such element. Please note that the callback function could be called more than once per element.
$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(callable|array $condition): self
Creates a new collection that when iterated will stop yielding results if the provided condition evaluates to true.
This is handy for dealing with infinite iterators or any generator that could start returning invalid elements at a certain point. For example, when reading lines from a file stream you may want to stop the iteration after a certain value is reached.
Get an array of lines in a CSV file until the timestamp column is less than a date
$lines = (new Collection($fileLines))->stopWhen(function ($value, $key) {
return (new DateTime($value))->format('Y') < 2012;
})
->toArray(); Get elements until the first unapproved message is found:
$comments = (new Collection($comments))->stopWhen(['is_approved' => false]);
callable|array $condition selfsumOf(callable|string|null $path = null): float|int
Returns the total sum of all the values extracted with $matcher or of this collection.
$items = [
['invoice' => ['total' => 100]],
['invoice' => ['total' => 200]]
];
$total = (new Collection($items))->sumOf('invoice.total');
// Total: 300
$total = (new Collection([1, 2, 3]))->sumOf();
// Total: 6 callable|string|null $path optional float|inttake(int $length = 1, int $offset = 0): self
Returns a new collection with maximum $size elements in the internal order this collection was created. If a second parameter is passed, it will determine from what position to start taking elements.
int $length optional int $offset optional selftakeLast(int $length): self
Returns the last N elements of a collection
$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(callable $callback): self
Passes this collection through a callable as its first argument. This is useful for decorating the full collection with another object.
$items = [1, 2, 3];
$decorated = (new Collection($items))->through(function ($collection) {
return new MyCustomCollection($collection);
}); callable $callback selftoArray(bool $keepKeys = true): array
Returns an array representation of the results
bool $keepKeys optional arraytoList(): array
Returns an numerically-indexed array representation of the results. This is equivalent to calling toArray(false)
arraytranspose(): Cake\Collection\CollectionInterface
Transpose rows and columns into columns and rows
$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\CollectionInterfaceLogicExceptionunfold(callable|null $callback = null): self
Creates a new collection where the items are the concatenation of the lists of items generated by the transformer function applied to each item in the original collection.
The transformer function will receive the value and the key for each of the items in the collection, in that order, and it must return an array or a Traversable object that can be concatenated to the final result.
If no transformer function is passed, an "identity" function will be used. This is useful when each of the elements in the source collection are lists of items to be appended one after another.
$items [[1, 2, 3], [4, 5]]; $unfold = (new Collection($items))->unfold(); // Returns [1, 2, 3, 4, 5]
Using a transformer
$items [1, 2, 3];
$allItems = (new Collection($items))->unfold(function ($page) {
return $service->fetchPage($page)->toArray();
}); callable|null $callback optional selfunserialize(string $serialized): void
Unserializes a resultset.
Part of Serializable interface.
string $serialized Serialized object
voidunwrap(): Traversable
Returns the closest nested iterator that can be safely traversed without losing any possible transformations. This is used mainly to remove empty IteratorIterator wrappers that can only slowdown the iteration process.
Traversablevalid(): bool
Whether there are more results to be fetched from the iterator
Part of Iterator interface.
boolzip(iterable $items): self
Combines the elements of this collection with each of the elements of the passed iterables, using their positional index as a reference.
$collection = new Collection([1, 2]); $collection->zip([3, 4], [5, 6])->toList(); // returns [[1, 3, 5], [2, 4, 6]]
iterable $items selfzipWith(iterable $items, callable $callback): self
Combines the elements of this collection with each of the elements of the passed iterables, using their positional index as a reference.
The resulting element will be the return value of the $callable function.
$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 selfTracks value of $_autoFields property of $query passed to constructor.
bool|nullList of associations that should be eager loaded.
arrayHolds the count of records in this result set
intLast record fetched from the statement
object|arrayThe default table alias
stringDefault table instance
Cake\ORM\TableThe Database driver object.
Cached in a property to avoid multiple calls to the same function.
Cake\Database\DriverInterfaceThe fully namespaced name of the class to use for hydrating results
stringWhether to hydrate results into objects or not
boolPoints to the next record number that should be fetched
intMap of fields that are fetched from the statement with their type and the table they belong to
array<string, mixed>List of associations that should be placed under the _matchingData result key.
array<string, mixed>List of matching associations and the column keys to expect from each of them.
array<string, mixed>Results that have been fetched or hydrated into the results.
SplFixedArray|arrayDatabase statement holding the results
Cake\Database\StatementInterfaceWhether to buffer results fetched from the statement
bool
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.4/class-Cake.ORM.ResultSet.html