メインコンテンツまでスキップ
バージョン: 13.x

Eloquent: Collections

Introduction​

複数のモデル結果を返すすべての Eloquent メソッドは、get メソッドを介して取得された結果やリレーションシップを介してアクセスされた結果を含む、Illuminate\Database\Eloquent\Collection クラスのインスタンスを返します。 Eloquent コレクション オブジェクトは Laravel の base collection を拡張するため、基礎となる 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 Collection Conversion​

ほとんどの Eloquent コレクション メソッドは Eloquent コレクションの新しいインスタンスを返しますが、collapse、flatten、flip、keys、pluck、および zip メソッドは base collection インスタンスを返します。同様に、map オペレーションが Eloquent モデルを含まないコレクションを返す場合、それはベース コレクション インスタンスに変換されます。

Available Methods​

すべての Eloquent コレクションは、基本 Laravel collection オブジェクトを拡張します。したがって、これらは、基本コレクション クラスによって提供される強力なメソッドをすべて継承します。

さらに、Illuminate\Database\Eloquent\Collection クラスには、モデルのコレクションを管理するための追加のメソッドが用意されています。ほとんどのメソッドは Illuminate\Database\Eloquent\Collection のインスタンスを返しますが、pluck など一部のメソッドは 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 メソッドを使用して、コレクション内のすべてのモデルの属性が appended である必要があることを示すことができます。このメソッドは、属性の配列または単一の属性を受け入れます。

$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 メソッドは、コレクション内の各モデルで通常は非表示になっている属性を表示します（makes attributes visible）。

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

makeHidden($attributes)​

makeHidden メソッドは、コレクション内の各モデルで通常は表示されている属性を非表示にします（hides attributes）。

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

mergeVisible($attributes)​

mergeVisible メソッドは、既存の表示属性を保持したまま追加の属性を表示します（makes additional attributes visible）。

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

mergeHidden($attributes)​

mergeHidden メソッドは、既存の非表示属性を保持したまま追加の属性を非表示にします（hides additional attributes）。

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

only($keys)​

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

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

partition​

partition メソッドは、Illuminate\Database\Eloquent\Collection コレクション インスタンスを含む Illuminate\Support\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 メソッドは、コレクション内の各モデルのすべての appended attributes を一時的にオーバーライドします。

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

setVisible($attributes)​

setVisible メソッドは、コレクション内の各モデルのすべての表示属性を一時的にオーバーライドします（temporarily overrides）。

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

setHidden($attributes)​

setHidden メソッドは、コレクション内の各モデルのすべての非表示属性を一時的にオーバーライドします（temporarily overrides）。

$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();

withoutAppends()​

withoutAppends メソッドは、コレクション内の各モデルのすべての appended attributes を一時的に削除します。

$users = $users->withoutAppends();

Custom Collections​

特定のモデルと対話するときにカスタム 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
{
    /**
     * 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
    {
        $collection = new UserCollection($models);

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

        return $collection;
    }
}

newCollection メソッドを定義するか、モデルに CollectedBy 属性を追加すると、Eloquent が通常 Illuminate\Database\Eloquent\Collection インスタンスを返すときはいつでも、カスタム コレクションのインスタンスを受け取ることができます。

アプリケーション内のすべてのモデルにカスタム コレクションを使用したい場合は、アプリケーションのすべてのモデルによって拡張される基本モデル クラスで newCollection メソッドを定義する必要があります。