Версія фреймворка: 8.x

Eloquent: Колекції

Вступ

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

Усі колекції також слугують ітераторами, дозволяючи вам циклічно перебирати їх, ніби це прості масиви PHP:

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

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

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

$users = App\Models\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повернення методів abase collectionінстанції. Так само, якщо amapоперація повертає колекцію, яка не містить жодної Eloquentї моделі, вона буде автоматично передана до базової колекції.

Доступні методи

Всі колекції Eloquent розширюють базуКолекція Laravelоб'єкт; отже, вони успадковують усі потужні методи, що надаються базовим класом колекцій.

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

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){# collection-method .first-collection-method}

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

$users = User::all();

$user = $users->find(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');

loadMissing($relations)

loadMissingметод прагне завантажувати дані зв'язки для всіх моделей у колекції, якщо зв'язки ще не завантажені:

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

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

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']);

only($keys)

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

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

toQuery()

toQueryметод повертає екземпляр Eloquent query builder, що міститьwhereInобмеження на первинні ключі моделі колекції:

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

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

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

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

$users = $users->unique();

Спеціальні колекції

Якщо вам потрібно використовувати спеціальнийCollectionоб'єкт із власними методами розширення, ви можете замінитиnewCollectionметод на вашій моделі:

<?php

namespace App\Models;

use App\Support\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);
    }
}

Після того, як ви визначили anewCollectionметод, ви отримаєте примірник власної колекції щоразу, коли Eloquent повертає aCollectionекземпляр цієї моделі. Якщо ви хочете використовувати власну колекцію для кожної моделі у вашій програмі, вам слід замінитиnewCollectionметод на базовому класі моделі, який розширений усіма вашими моделями.