Eloquent: Коллекции

• Введение
• Доступные методы
• Пользовательские коллекции

Введение

Все наборы результатов, возвращаемые Eloquent, являются экземплярами объекта Illuminate\Database\Eloquent\Collection , в том числе результаты, получаемые с помощью метода get или доступные через отношения. Объект коллекции Eloquent наследует базовую коллекцию Laravel, поэтому он наследует десятки методов, используемых для гибкой работы с базовым набором моделей Eloquent.

Конечно же, все коллекции также служат в качестве итераторов, позволяя вам перебирать их в цикле, как будто они простые PHP-массивы:

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

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

Тем не менее, коллекции гораздо мощнее, чем массивы и предоставляют различные варианты операций map/reduce, которые могут быть сцеплены с использованием интуитивно понятного интерфейса. Например, давайте удалим все неактивные модели и возвратим имена для каждого оставшегося пользователя:

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

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

Хотя большинство методов для работы с коллекциями Eloquent возвращают новый экземпляр коллекции Eloquent, методы pluck, keys, zip, collapse, flatten и flip возвращают экземпляр базовой коллекции. Более того, если операция map вернёт коллекцию, в которой нет моделей Eloquent, она будет автоматически приведена к базовой коллекции.

Доступные методы

Базовая коллекция

Все коллекции Eloquent наследуют класс коллекций Laravel; поэтому они наследуют все методы, предоставляемые базовым классом коллекций.

Дополнительно класс Illuminate\Database\Eloquent\Collection содержит несколько методов, специфичных для работы именно с моделями коллекций. В основном они возвращают Illuminate\Database\Eloquent\Collection, но некоторые возвращают и базовые коллекции, Illuminate\Support\Collection.

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

Метод contains позволяет понять, есть ли в коллекции заданная модель. Если аргумент числовой, он рассматривается как id модели.

$users->contains(1);

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

diff($items)

Метод diff возвращает все модели, которых нет в переданной коллекции.

use App\User;

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

except($keys)

Метод except возвращает все модели, кроме тех, чьи id перечислены в аргументе.

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

find($key) {#collection-method .first-collection-method}

Метод find находит модели по переданным id. Если вместо id передаётся экземпляр модели, поиск идёт про его id. Если передаётся массив из id, find вернёт все эти модели, будет искать по моделям при помощи whereIn():

$users = User::all();

$user = $users->find(1);

fresh($with = [])

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

$users = $users->fresh();

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

intersect($items)

Метод intersect возвращает модели которые также присутствуют в коллекции, поданной в аргументе.

use App\User;

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

load($relations)

Метод load загружает заданные отношения во все модели.

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

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

loadMissing($relations)

Метод loadMissing загружает отношения во все модели, если они ещё не загружены.

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

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

modelKeys()

Метод modelKeys возвращает массив с id моделей из коллекции:

$users->modelKeys();

// [1, 2, 3, 4, 5]

makeVisible($attributes)

Метод makeVisible делает поля, обозначенные в моделях как "hidden" видимыми.

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

makeHidden($attributes)

Метод makeHidden добавляет указанные поля моделей в группу "hidden" - эти поля перестанут выводиться в json и т.п.

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

only($keys)

Метод only возвращает модели, которые содержат указанные id:

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

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

Метод unique возвращает уникальные модели из коллекции. Уникальность определяется по названию класса модели и id.

$users = $users->unique();

Пользовательские коллекции

Если вам нужно использовать пользовательский объект Collection со своими собственными методами наследования, вы можете переопределить метод newCollection в своей модели:

<?php

namespace App;

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

class User extends Model
{
    /**
     * Создание экземпляра новой Eloquent коллекции.
     *
     * @param  array  $models
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function newCollection(array $models = [])
    {
        return new CustomCollection($models);
    }
}

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