Eloquent: Collections

• Custom Collections

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

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

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;
});

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

In addition, the Illuminate\Database\Eloquent\Collection class provides a superset of methods to aid with managing your model collections. Most methods return Illuminate\Database\Eloquent\Collection instances; however, some methods return a base Illuminate\Support\Collection instance.

contains($key, $operator = null, $value = null)

$users->contains(1);
$users->contains(User::find(1));

diff($items)

The diff method returns all of the models that are not present in the given collection:

use App\User;
$users = $users->diff(User::whereIn('id', [1, 2, 3])->get());

except($keys)

The except method returns all of the models that do not have the given primary keys:

find($key)

The find method finds a model that has a given primary key. If $key is a model instance, find will attempt to return a model matching the primary key. If $key is an array of keys, find will return all models which match the $keys using whereIn():

fresh($with = [])

The fresh method retrieves a fresh instance of each model in the collection from the database. In addition, any specified relationships will be eager loaded:

$users = $users->fresh();
$users = $users->fresh('comments');

intersect($items)

The intersect method returns all of the models that are also present in the given collection:

use App\User;

load($relations)

The load method eager loads the given relationships for all models in the collection:

$users->load('comments', 'posts');
$users->load('comments.author');

loadMissing($relations)

The loadMissing method eager loads the given relationships for all models in the collection if the relationships are not already loaded:

$users->loadMissing('comments', 'posts');
$users->loadMissing('comments.author');

modelKeys()

makeVisible($attributes)

The makeVisible method makes attributes visible that are typically "hidden" on each model in the collection:

$users = $users->makeVisible(['address', 'phone_number']);

makeHidden($attributes)

The makeHidden method hides attributes that are typically "visible" on each model in the collection:

$users = $users->makeHidden(['address', 'phone_number']);

only($keys)

The only method returns all of the models that have the given primary keys:

$users = $users->only([1, 2, 3]);

unique($key = null, $strict = false)

The unique method returns all of the unique models in the collection. Any models of the same type with the same primary key as another model in the collection are removed.

$users = $users->unique();

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

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 method on a base model class that is extended by all of your models.