Eloquent: Collections

Introduction

すべての Eloquent メソッドは、複数の model の結果を返すとき、関連性によってアクセスされたりget method を介して retrieved された結果を含めて、Illuminate\Database\Eloquent\Collection class のインスタンスを返します。 Eloquent collection object は Laravel の基本的な collectionを拡張しているので、自然に Eloquent models の array と流暢に作業するために使われる数十のメソッドを継承します。これらの便利なメソッドについて全て学ぶために、 Laravel collection のドキュメンテーションを必ず確認してください!

すべての collections もまたイテレータとして機能し、それらをシンプルな PHP 配列であるかのようにループできます：

use App\Models\User;

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

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

しかし、前述の通り、 collections は配列よりもはるかに強力で、直感的なインターフェースを使用して連鎖させることができるさまざまなマップ/ reduce 操作を公開します。例えば、すべての非アクティブな models を削除し、残った各 user の名前を取得することができます。

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

Eloquent Collection の変換

ほとんどの Eloquent collection メソッドは新しい Eloquent collection のインスタンスを返しますが、collapse、flatten、flip、keys、pluck、zipメソッドはベースの collectionインスタンスを返します。同様に、map操作が Eloquent models を含まない collection を返す場合、それはベースの collection インスタンスに変換されます。

Available Methods

すべての Eloquent collections は基本の Laravel collection オブジェクトを拡張します。したがって、基本の collection class が提供する強力なメソッドをすべて継承します。

また、Illuminate\Database\Eloquent\Collection class は、 model collections の管理を支援するための methods のスーパーセットを提供します。ほとんどの methods はIlluminate\Database\Eloquent\Collectionインスタンスを返しますが、modelKeysのような一部の methods はIlluminate\Support\Collectionインスタンスを返します。

append($attributes)

append method は、collection 内のすべての model に対して属性を追加することを示すために使用できます。この method は、属性の array または単一の属性を受け入れます。

$users->append('team');

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

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

contains method は、特定の model インスタンスが collection に含まれるかどうかを判断するために使用できます。この method は、 primary key または model インスタンスを受け入れます：

$users->contains(1);

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

diff($items)

diff method は、与えられた collection に存在しないすべての models を返します。

use App\Models\User;

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

except($keys)

except method は、指定された primary keys を持たないすべての models を返します：

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

find($key)

findの method は、指定されたキーと一致する primary キーを持つ model を返します。$keyが model のインスタンスの場合、findは primary キーと一致する model を返そうと attempt します。$keyが keys の array である場合、findは指定された array 内にある primary キーを持つすべての models を返します。

$users = User::all();

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

fresh($with = [])

fresh method は、 database から collection 内の各 model の新しいインスタンスを取得します。また、指定されたリレーションシップは、事前に読み込まれます。

$users = $users->fresh();

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

intersect($items)

intersect method は、指定された collection 内にも存在するすべての models を返します。

use App\Models\User;

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

load($relations)

load method は、与えられた関連性をすべての models について、 collection 内で先読みします。

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

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

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

loadMissing($relations)

loadMissing method は、すでにロードされていない場合、与えられた collection 内のすべての models の関係性を事前にロードします。

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

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

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

modelKeys()

modelKeysの method は、 collection 内のすべての models の primary keys を返します。

$users->modelKeys();

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

makeVisible($attributes)

makeVisible method は、通常は collection 中の各 model で「非表示」になっているattributes を表示します：

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

makeHidden($attributes)

makeHidden method は、通常は各 model で"見える" attributes を隠します collection に:

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

only($keys)

onlyの method は、指定された primary keys を持つ全ての models を返します。

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

setVisible($attributes)

setVisiblemethod は、collection 内の各 model のすべての可視属性を一時的に上書きします:

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

setHidden($attributes)

setHidden method は一時的にオーバーライドすべての hidden attributes を各 model に対して collection 中で行います：

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

toQuery()

toQuery method は、collectionmodel の primarykey にwhereIn制約を含む Eloquentquery ビルダーインスタンスを返します。

use App\Models\User;

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

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

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

unique method は、 collection 内のすべての unique models を返します。 collection 内の別の model と同じ primary キーを持つ models は削除されます。

$users = $users->unique();

Custom Collections

ある特定の model と対話する際に、 custom Collection object を使用したい場合は、 model 上にnewCollection method を定義することができます。

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Create a new Eloquent Collection instance.
     *
     * @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 method を定義すると、通常ならば Illuminate\Database\Eloquent\Collection インスタンスを返すはずの Eloquent が、あなたの custom collection のインスタンスを返します。あなたが application 内のすべての models で custom collection を使用したい場合には、 newCollection method をすべての application の models に展開される基本の model class 上で定義するべきです。