Chunking Laravel Collections with Chunk and ChunkWhile

When PHP code has loaded items into a Laravel collection, chunk() and chunkWhile() divide them into smaller collections. chunk() sets a maximum size for each group. chunkWhile() uses a callback, a function that checks each item and decides whether it belongs in the current group.

These methods format or process data that is already in memory. They do not limit how many database rows Laravel loads. For large query results, use a method that fetches rows in batches, such as Eloquent’s chunk().

Use chunk() for fixed-size groups

Call chunk($size) on a collection to divide its items, in order, into groups no larger than the size you provide. The last group holds any items left over, so it is smaller when the total is not a multiple of the size. Laravel’s collection documentation shows how chunk(4) splits seven items into groups of four and three.

$collection = collect([1, 2, 3, 4, 5, 6, 7]);

$groups = $collection->chunk(4);

$groups is a collection whose items are smaller collections. This structure works for a view that displays products in rows or for code that passes loaded items to another operation in batches.

The argument sets the maximum number of items in each group, not how many groups to make. If the collection has fewer items than the size, chunk() returns one smaller group. The method divides items already in memory; it does not fetch database records in batches.

Use chunkWhile() for consecutive runs

Call chunkWhile($callback) when the items determine where each group ends. Laravel passes the current value and its key to the callback, along with the chunk being built. If the callback returns true, the current value stays in that chunk. If it returns false, the value starts a new chunk.

Laravel’s example groups adjacent matching characters:

$chunks = collect(str_split('AABBCCCD'))
    ->chunkWhile(fn ($value, $key, $chunk) => $value === $chunk->last());

The result contains consecutive groups of AA, BB, CCC, and D. The callback compares each value with the last value in the current chunk, so the groups stay in the original order. Use this method to group consecutive events with the same attribute or to keep adjacent readings together while they meet a condition. Matching values separated by other items stay in separate chunks. Laravel explains the callback and example in its collection reference.

Choose based on how the boundary is set

Use chunk() to set a maximum size for each group, such as the number of items in a display row. Use chunkWhile() when items belong together only while a condition holds, such as when consecutive records share an attribute.

Both methods work on an existing collection. If code calls get() to load query results before calling $results->chunk(...), Laravel loads all those results first. The collection method divides them afterward.

Use query chunking for large database results

Eloquent and the query builder also provide a chunk() method for database queries. It runs a database query for each subset and passes each subset to a callback. For example, Flight::chunk(200, ...) processes results in batches of 200, as shown in Laravel’s Eloquent documentation. The size is an example, not a recommendation for every case.

If code updates a column that the query also uses to filter results, ordinary query chunking can produce inconsistent results. Laravel recommends chunkById() in this case. It moves through records by comparing their IDs. Laravel also documents lazy(), which retrieves results in chunks and presents them as a flattened LazyCollection. Code can then consume one record at a time.

Collection chunk() and chunkWhile() divide items after Laravel has created the collection. Query methods fetch database results in subsets. Use collection methods to format or group loaded data, and query methods to avoid loading the full result set at once.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com