メインコンテンツまでスキップ

Eloquent: Collections

導入​

get メソッドを介して取得された結果やリレーションを介してアクセスされた結果を含む、1つ以上のモデル結果を返すすべての Eloquent メソッドは、Illuminate\Database\Eloquent\Collection クラスのインスタンスを返します。Eloquent コレクションオブジェクトは Laravel のベースコレクションを拡張しており、Eloquent モデルの基になる配列をスムーズに操作するために使用される数十のメソッドを自然に継承しています。これらの便利なメソッドについてすべてを学ぶために Laravel コレクションのドキュメントを確認してください！

すべてのコレクションはイテレータとしても機能し、それらを単純な PHP 配列のようにループ処理できます：

    use App\Models\User;

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

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

ただし、前述のように、コレクションは配列よりもはるかに強力であり、直感的なインターフェースを使用してチェーン可能なマップ / リデュース操作を公開します。たとえば、すべての非アクティブなモデルを削除し、残りのユーザーの名前を取得することができます：

    $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 インスタンスを返します。

<div class="collection-method-list" markdown="1">

[append](#method-append)
[contains](#method-contains)
[diff](#method-diff)
[except](#method-except)
[find](#method-find)
[fresh](#method-fresh)
[intersect](#method-intersect)
[load](#method-load)
[loadMissing](#method-loadMissing)
[modelKeys](#method-modelKeys)
[makeVisible](#method-makeVisible)
[makeHidden](#method-makeHidden)
[only](#method-only)
[setVisible](#method-setVisible)
[setHidden](#method-setHidden)
[toQuery](#method-toquery)
[unique](#method-unique)

</div>

<a name="method-append"></a>
#### `append($attributes)`

`append` メソッドは、コレクション内のすべてのモデルに属性を[追加](/docs/eloquent-serialization#appending-values-to-json)する必要があることを示すために使用できます。このメソッドは、属性の配列または単一の属性を受け入れます：

```php
    $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);

fresh($with = [])​

fresh メソッドは、データベースからコレクション内の各モデルの新しいインスタンスを取得します。さらに、指定されたリレーションシップがイーガーロードされます：


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

only($keys)​

only メソッドは、指定された主キーを持つすべてのモデルを返します：

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

setVisible($attributes)​

setVisible メソッドは、コレクション内の各モデルのすべての表示可能な属性を一時的に上書きします：

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

setHidden($attributes)​

setHidden メソッドは、コレクション内の各モデルのすべての非表示属性を一時的に上書きします:

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

toQuery()​

toQueryメソッドは、コレクションモデルの主キーにwhereIn制約を含むEloquentクエリビルダーインスタンスを返します：

    use App\Models\User;

    $users = 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\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メソッドを定義すると、通常EloquentがIlluminate\Database\Eloquent\Collectionインスタンスを返す場合に、カスタムコレクションのインスタンスを受け取ることができます。アプリケーション内のすべてのモデルにカスタムコレクションを使用したい場合は、アプリケーション内のすべてのモデルに拡張される基本モデルクラスにnewCollectionメソッドを定義する必要があります。