Laravel 11.x Eloquent:コレクション

イントロダクションIntroduction

getメソッドで取得した結果や、リレーションによりアクセスした結果など、結果として複数のモデルを返すEloquentメソッドはすべて、Illuminate\Database\Eloquent\Collectionクラスのインスタンスを返します。EloquentコレクションオブジェクトはLaravelの基本的なコレクションを拡張しているため、基になるEloquentモデルの配列をスムーズに操作できるように使用する、数十のメソッドを自然に継承します。これらの便利なメソッドをすべて学ぶために、Laravelコレクションのドキュメントは必ず確認してください！All Eloquent methods that return more than one model result will return instances of the Illuminate\Database\Eloquent\Collection class, including results retrieved via the get method or accessed via a relationship. The Eloquent collection object extends Laravel's base collection[/docs/{{version}}/collections], so it naturally inherits dozens of methods used to fluently work with the underlying array of Eloquent models. Be sure to review the Laravel collection documentation to learn all about these helpful methods!

すべてのコレクションはイテレーターとしても機能し、単純なPHP配列のようにループで使えます。All collections also serve as iterators, allowing you to loop over them as if they were simple PHP arrays:

use App\Models\User;

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

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

ただし、前述のようにコレクションは配列よりもはるかに強力であり、直感的なインターフェイスを使用してチェーンする可能性を持つさまざまなマップ/リデュース操作を用意しています。たとえば、非アクティブなモデルをすべて削除してから、残りのユーザーの名を収集する場面を考えましょう。However, as previously mentioned, collections are much more powerful than arrays and expose a variety of map / reduce operations that may be chained using an intuitive interface. For example, we may remove all inactive models and then gather the first name for each remaining user:

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

Eloquentコレクションの変換Eloquent Collection Conversion

ほとんどのEloquentコレクションメソッドはEloquentコレクションの新しいインスタンスを返しますが、collapse、flatten、flip、keys、pluck、zipメソッドは、基本のコレクションインスタンスを返します。同様に、map操作がEloquentモデルを含まないコレクションを返す場合、それは基本コレクションインスタンスに変換されます。While most Eloquent collection methods return a new instance of an Eloquent collection, the collapse, flatten, flip, keys, pluck, and zip methods return a base collection[/docs/{{version}}/collections] instance. Likewise, if a map operation returns a collection that does not contain any Eloquent models, it will be converted to a base collection instance.

利用可能なメソッドAvailable Methods

すべてのEloquentコレクションはベースのLaravelコレクションオブジェクトを拡張します。したがって、これらは基本コレクションクラスによって提供されるすべての強力なメソッドを継承します。All Eloquent collections extend the base Laravel collection[/docs/{{version}}/collections#available-methods] object; therefore, they inherit all of the powerful methods provided by the base collection class.

さらに、Illuminate\Database\Eloquent\Collectionクラスは、モデルコレクションの管理を支援するメソッドのスーパーセットを提供します。ほとんどのメソッドはIlluminate\Database\Eloquent\Collectionインスタンスを返します。ただし、modelKeysなどの一部のメソッドは、Illuminate\Support\Collectionインスタンスを返します。In addition, the Illuminate\Database\Eloquent\Collection class provides a superset of methods to aid with managing your model collections. Most methods return Illuminate\Database\Eloquent\Collection instances; however, some methods, like modelKeys, return an Illuminate\Support\Collection instance.

append($attributes) append($attributes)

appendメソッドは、コレクション内の全モデルへ属性を追加するように指示するために使用します。このメソッドには、属性の配列か、単一の属性を指定します。The append method may be used to indicate that an attribute should be appended[/docs/{{version}}/eloquent-serialization#appending-values-to-json] for every model in the collection. This method accepts an array of attributes or a single attribute:

$users->append('team');

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

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

containsメソッドを使い、指定モデルインスタンスがコレクションに含まれているかどうかを判定できます。このメソッドは、主キーまたはモデルインスタンスを引数に取ります。The contains method may be used to determine if a given model instance is contained by the collection. This method accepts a primary key or a model instance:

$users->contains(1);

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

diff($items) diff($items)

diffメソッドは、指定コレクションに存在しないすべてのモデルを返します。The diff method returns all of the models that are not present in the given collection:

use App\Models\User;

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

except($keys) except($keys)

exceptメソッドは、指定する主キーを持たないすべてのモデルを返します。The except method returns all of the models that do not have the given primary keys:

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

find($key) find($key)

findメソッドは、指定キーと一致する主キーを持つモデルを返します。$keyがモデルインスタンスの場合、findは主キーに一致するモデルを返そうとします。$keyがキーの配列である場合、findは指定配列の中の主キーを持つすべてのモデルを返します。The find method returns the model that has a primary key matching the given key. If $key is a model instance, find will attempt to return a model matching the primary key. If $key is an array of keys, find will return all models which have a primary key in the given array:

$users = User::all();

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

findOrFail($key) findOrFail($key)

findOrFailメソッドは、指定キーと一致する主キーを持つモデルを返すか、もしくは一致するモデルがコレクション内に見つからない場合にIlluminate\Database\Eloquent\ModelNotFoundException例外を投げます。The findOrFail method returns the model that has a primary key matching the given key or throws an Illuminate\Database\Eloquent\ModelNotFoundException exception if no matching model can be found in the collection:

$users = User::all();

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

fresh($with = []) fresh($with = [])

freshメソッドは、データベースからコレクション内の各モデルの新しいインスタンスを取得します。さらに、指定したリレーションはすべてEagerロードされます。The fresh method retrieves a fresh instance of each model in the collection from the database. In addition, any specified relationships will be eager loaded:

$users = $users->fresh();

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

intersect($items) intersect($items)

intersectメソッドは、指定コレクションにも存在するすべてのモデルを返します。The intersect method returns all of the models that are also present in the given collection:

use App\Models\User;

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

load($relations) load($relations)

loadメソッドは、コレクション内のすべてのモデルに対して指定するリレーションをEagerロードします。The load method eager loads the given relationships for all models in the collection:

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

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

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

loadMissing($relations) loadMissing($relations)

loadMissingメソッドは、関係がまだロードされていない場合、コレクション内のすべてのモデルに対して指定するリレーションをEagerロードします。The loadMissing method eager loads the given relationships for all models in the collection if the relationships are not already loaded:

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

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

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

modelKeys() modelKeys()

modelKeysメソッドは、コレクション内のすべてのモデルの主キーを返します。The modelKeys method returns the primary keys for all models in the collection:

$users->modelKeys();

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

makeVisible($attributes) makeVisible($attributes)

makeVisibleメソッドは、通常コレクション内の各モデルで"hidden"になっている属性をvisibleにします。The makeVisible method makes attributes visible[/docs/{{version}}/eloquent-serialization#hiding-attributes-from-json] that are typically "hidden" on each model in the collection:

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

makeHidden($attributes) makeHidden($attributes)

makeHiddenメソッドは、通常コレクション内の各モデルで"visible"になっている属性をhiddenにします。The makeHidden method hides attributes[/docs/{{version}}/eloquent-serialization#hiding-attributes-from-json] that are typically "visible" on each model in the collection:

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

only($keys) only($keys)

onlyメソッドは、指定主キーを持つすべてのモデルを返します。The only method returns all of the models that have the given primary keys:

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

setVisible($attributes) setVisible($attributes)

setVisibleメソッドは、コレクション内の各モデルの全てのvisible属性を一時的に上書きします。The setVisible method temporarily overrides[/docs/{{version}}/eloquent-serialization#temporarily-modifying-attribute-visibility] all of the visible attributes on each model in the collection:

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

setHidden($attributes) setHidden($attributes)

setHiddenメソッドは、コレクション内の各モデルの全てのhidden属性を一時的に上書きします。The setHidden method temporarily overrides[/docs/{{version}}/eloquent-serialization#temporarily-modifying-attribute-visibility] all of the hidden attributes on each model in the collection:

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

toQuery() toQuery()

toQueryメソッドは、コレクションモデルの主キーに対するwhereIn制約を含むEloquentクエリビルダインスタンスを返します。The toQuery method returns an Eloquent query builder instance containing a whereIn constraint on the collection model's primary keys:

use App\Models\User;

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

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

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

uniqueメソッドは、コレクション内のすべての一意のモデルを返します。コレクション内の同じ主キーを持つモデルは、すべて削除します。The unique method returns all of the unique models in the collection. Any models with the same primary key as another model in the collection are removed:

$users = $users->unique();

カスタムコレクションCustom Collections

指定したモデルを操作する際に、カスタムCollectionオブジェクトを使用したい場合は、モデルへCollectedBy属性を追加してください。If you would like to use a custom Collection object when interacting with a given model, you may add the CollectedBy attribute to your model:

<?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メソッドを定義することもできます。Alternatively, you may define a newCollection method on your model:

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * 新しいEloquentCollectionインスタンスの作成
     *
     * @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メソッドを定義するか、モデルへCollectedBy属性を追加すると、Eloquentは通常、Illuminate\Database\Eloquent\Collectionインスタンスを返します。Once you have defined a newCollection method or added the CollectedBy attribute to your model, you will receive an instance of your custom collection anytime Eloquent would normally return an Illuminate\Database\Eloquent\Collection instance.

アプリケーションのすべてのモデルでカスタムコレクションを使用したい場合は、アプリケーションのすべてのモデルで拡張する基底モデルクラスで、newCollectionメソッドを定義する必要があります。If you would like to use a custom collection for every model in your application, you should define the newCollection method on a base model class that is extended by all of your application's models.