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

Eloquent: コレクション (Eloquent: Collections)

導入 (Introduction)​

複数のモデル結果を返すすべての Eloquent メソッドは、get メソッドを介して取得された結果やリレーションシップを介してアクセスされた結果を含む、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 モデルを含まないコレクションを返す場合、それはベース コレクション インスタンスに変換されます。

利用可能な方法 (Available Methods)​

すべての 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 メソッドを使用して、コレクション内のすべてのモデルの属性が 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 メソッド 属性を可視化します:

$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\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 メソッドは、コレクション内の各モデルのすべての 追加された属性 を一時的にオーバーライドします。

$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 メソッドは、コレクション モデルの主キーに対する 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 メソッドは、コレクション内の各モデルのすべての 追加された属性 を一時的に削除します。

$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 メソッドを定義する必要があります。