eloquent-collections.md

Eloquent: Collections

• Introduction
• Available Methods
• Custom Collections

Introduction

All multi-result sets returned by Eloquent are instances of the Illuminate\Database\Eloquent\Collection object, including results retrieved via the get method or accessed via a relationship. The Eloquent collection object extends the Laravel base collection, so it naturally inherits dozens of methods used to fluently work with the underlying array of Eloquent models.

Of course, all collections also serve as iterators, allowing you to loop over them as if they were simple PHP arrays:

$users = App\User::where('active', 1)->get();

foreach ($users as $user) {
    echo $user->name;
}

However, collections are much more powerful than arrays and expose a variety of map / reduce operations that may be chained using an intuitive interface. For example, let's remove all inactive models and gather the first name for each remaining user:

$users = App\User::all();

$names = $users->reject(function ($user) {
    return $user->active === false;
})
->map(function ($user) {
    return $user->name;
});

{note} While most Eloquent collection methods return a new instance of an Eloquent collection, the pluck, keys, zip, collapse, flatten and flip methods return a base collection instance. Likewise, if a map operation returns a collection that does not contain any Eloquent models, it will be automatically cast to a base collection.

Available Methods

The Base Collection

All Eloquent collections extend the base Laravel collection object; therefore, they inherit all of the powerful methods provided by the base collection class:

<style> #collection-method-list > p { column-count: 3; -moz-column-count: 3; -webkit-column-count: 3; column-gap: 2em; -moz-column-gap: 2em; -webkit-column-gap: 2em; } #collection-method-list a { display: block; } </style>

all average avg chunk collapse combine concat contains containsStrict count crossJoin dd diff diffKeys dump each eachSpread every except filter first flatMap flatten flip forget forPage get groupBy has implode intersect isEmpty isNotEmpty keyBy keys last map mapInto mapSpread mapToGroups mapWithKeys max median merge min mode nth only pad partition pipe pluck pop prepend pull push put random reduce reject reverse search shift shuffle slice some sort sortBy sortByDesc splice split sum take tap toArray toJson transform union unique uniqueStrict unless values when where whereStrict whereIn whereInStrict whereNotIn whereNotInStrict zip

Custom Collections

If you need to use a custom Collection object with your own extension methods, you may override the newCollection method on your model:

<?php

namespace App;

use App\CustomCollection;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Create a new Eloquent Collection instance.
     *
     * @param  array  $models
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function newCollection(array $models = [])
    {
        return new CustomCollection($models);
    }
}

Once you have defined a newCollection method, you will receive an instance of your custom collection anytime Eloquent returns a Collection instance of that model. If you would like to use a custom collection for every model in your application, you should override the newCollection method on a base model class that is extended by all of your models.