Колекції Eloquent · Laravel

Вступ

Усі методи 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 contains diff except find findOrFail fresh intersect load loadMissing modelKeys makeVisible makeHidden mergeVisible mergeHidden only partition setAppends setVisible setHidden toQuery unique withoutAppends

append($attributes)

Метод append дозволяє вказати, що атрибут має бути доданий для кожної моделі в колекції. Метод приймає масив атрибутів або один атрибут:

$users->append('team');

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

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

Метод contains дозволяє визначити, чи міститься дана модель у колекції. Метод приймає первинний ключ або екземпляр моделі:

$users->contains(1);

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

diff($items)

Метод diff повертає всі моделі, яких немає в переданій колекції:

use App\Models\User;

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

except($keys)

Метод except повертає всі моделі, які не мають вказаних первинних ключів:

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

find($key)

Метод find повертає модель, первинний ключ якої збігається з переданим ключем. Якщо $key є екземпляром моделі, find спробує повернути модель із відповідним первинним ключем. Якщо $key є масивом ключів, find поверне всі моделі, первинний ключ яких є в цьому масиві:

$users = User::all();

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

findOrFail($key)

Метод findOrFail повертає модель, первинний ключ якої збігається з переданим ключем, або кидає виняток Illuminate\Database\Eloquent\ModelNotFoundException, якщо відповідної моделі в колекції немає:

$users = User::all();

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

fresh($with = [])

Метод fresh отримує з бази даних свіжий екземпляр кожної моделі в колекції. Крім того, будь-які вказані звʼязки буде завантажено жадібно:

$users = $users->fresh();

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

intersect($items)

Метод intersect повертає всі моделі, які також присутні в переданій колекції:

use App\Models\User;

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

load($relations)

Метод load жадібно завантажує вказані звʼязки для всіх моделей у колекції:

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

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

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

loadMissing($relations)

Метод loadMissing жадібно завантажує вказані звʼязки для всіх моделей у колекції, якщо ці звʼязки ще не завантажено:

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

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

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

modelKeys()

Метод modelKeys повертає первинні ключі всіх моделей у колекції:

$users->modelKeys();

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

makeVisible($attributes)

Метод makeVisible робить видимими атрибути, які зазвичай «приховані» в кожній моделі колекції:

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

makeHidden($attributes)

Метод makeHidden приховує атрибути, які зазвичай «видимі» в кожній моделі колекції:

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

mergeVisible($attributes)

Метод mergeVisible робить видимими додаткові атрибути, зберігаючи вже видимі:

$users = $users->mergeVisible(['middle_name']);

mergeHidden($attributes)

Метод mergeHidden приховує додаткові атрибути, зберігаючи вже приховані:

$users = $users->mergeHidden(['last_login_at']);

only($keys)

Метод only повертає всі моделі, які мають вказані первинні ключі:

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

partition

Метод partition повертає екземпляр Illuminate\Support\Collection, що містить екземпляри колекцій Illuminate\Database\Eloquent\Collection:

$partition = $users->partition(fn ($user) => $user->age > 18);

dump($partition::class);    // Illuminate\Support\Collection
dump($partition[0]::class); // Illuminate\Database\Eloquent\Collection
dump($partition[1]::class); // Illuminate\Database\Eloquent\Collection

setAppends($attributes)

Метод setAppends тимчасово перевизначає всі додані атрибути в кожній моделі колекції:

$users = $users->setAppends(['is_admin']);

setVisible($attributes)

Метод setVisible тимчасово перевизначає всі видимі атрибути в кожній моделі колекції:

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

setHidden($attributes)

Метод setHidden тимчасово перевизначає всі приховані атрибути в кожній моделі колекції:

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

toQuery()

Метод toQuery повертає екземпляр конструктора запитів Eloquent з обмеженням whereIn за первинними ключами моделей колекції:

use App\Models\User;

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

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

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

Метод unique повертає всі унікальні моделі колекції. Будь-які моделі з таким самим первинним ключем, як в іншої моделі колекції, вилучаються:

$users = $users->unique();

withoutAppends()

Метод withoutAppends тимчасово прибирає всі додані атрибути в кожній моделі колекції:

$users = $users->withoutAppends();

Власні колекції

Якщо для роботи з певною моделлю ви хочете використовувати власний обʼєкт Collection, додайте до моделі атрибут CollectedBy:

<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Attributes\CollectedBy;
use Illuminate\Database\Eloquent\Model;

#[CollectedBy(UserCollection::class)]
class User extends Model
{
    // ...
}

Або ж визначте в моделі метод 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
    {
        $collection = new UserCollection($models);

        if (Model::isAutomaticallyEagerLoadingRelationships()) {
            $collection->withRelationshipAutoloading();
        }

        return $collection;
    }
}

Щойно ви визначили метод newCollection або додали до моделі атрибут CollectedBy, ви отримуватимете екземпляр своєї колекції щоразу, коли Eloquent зазвичай повертав би екземпляр Illuminate\Database\Eloquent\Collection.

Якщо власну колекцію треба використовувати для кожної моделі в застосунку, визначте метод newCollection у базовому класі моделі, який розширюють усі моделі застосунку.