Eloquent: Коллекции

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

#Введение

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

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

use App\Models\User;

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

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

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

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

#Преобразование коллекций Eloquent

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

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

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

Кроме того, класс Illuminate\Database\Eloquent\Collection предоставляет расширенный набор методов для удобного управления коллекциями моделей. Большинство методов возвращают экземпляры Illuminate\Database\Eloquent\Collection; однако некоторые методы, например modelKeys, возвращают экземпляр Illuminate\Support\Collection.

#append($attributes) {.collection-method .first-collection-method}

Метод append используется для указания атрибутов, которые должны быть добавлены к каждому объекту модели в коллекции. Метод принимает массив атрибутов или один атрибут:

$users->append('team');

$users->append(['team', 'is_admin']);

#contains($key, $operator = null, $value = null) {.collection-method}

Метод contains проверяет, содержится ли заданный экземпляр модели в коллекции. Метод принимает первичный ключ или экземпляр модели:

$users->contains(1);

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

#diff($items) {.collection-method}

Метод diff возвращает все модели, отсутствующие в переданной коллекции:

use App\Models\User;

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

#except($keys) {.collection-method}

Метод except возвращает все модели, у которых нет указанных первичных ключей:

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

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

Метод find возвращает модель с первичным ключом, совпадающим с заданным ключом. Если $key — экземпляр модели, find попытается вернуть модель с таким же первичным ключом. Если $key — массив ключей, find вернёт все модели с первичными ключами из этого массива:

$users = User::all();

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

#fresh($with = []) {.collection-method}

Метод fresh получает свежий экземпляр каждой модели из коллекции из базы данных. Кроме того, указанные связи будут загружены жадно:

$users = $users->fresh();

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

#intersect($items) {.collection-method}

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

use App\Models\User;

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

#load($relations) {.collection-method}

Метод load жадно загружает указанные связи для всех моделей в коллекции:

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

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

$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

#loadMissing($relations) {.collection-method}

Метод loadMissing жадно загружает указанные связи для всех моделей в коллекции, если они ещё не загружены:

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

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

$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

#modelKeys() {.collection-method}

Метод modelKeys возвращает первичные ключи всех моделей в коллекции:

$users->modelKeys();

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

#makeVisible($attributes) {.collection-method}

Метод makeVisible делает атрибуты видимыми, которые обычно скрыты в каждой модели коллекции:

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

#makeHidden($attributes) {.collection-method}

Метод makeHidden скрывает атрибуты, которые обычно видимы в каждой модели коллекции:

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

#only($keys) {.collection-method}

Метод only возвращает все модели, у которых есть указанные первичные ключи:

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

#setVisible($attributes) {.collection-method}

Метод setVisible временно переопределяет все видимые атрибуты в каждой модели коллекции:

$users = $users->setVisible(['id', 'name']);

#setHidden($attributes) {.collection-method}

Метод setHidden временно переопределяет все скрытые атрибуты в каждой модели коллекции:

$users = $users->setHidden(['email', 'password', 'remember_token']);

#toQuery() {.collection-method}

Метод toQuery возвращает экземпляр конструктора запросов Eloquent с ограничением whereIn по первичным ключам моделей коллекции:

use App\Models\User;

$users = User::where('status', 'VIP')->get();

$users->toQuery()->update([
    'status' => 'Administrator',
]);

#unique($key = null, $strict = false) {.collection-method}

Метод unique возвращает все уникальные модели в коллекции. Все модели одного типа с одинаковым первичным ключом, что и другая модель в коллекции, удаляются:

$users = $users->unique();

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

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

<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;

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

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