Eloquent: コレクション¶
イントロダクション¶
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;
}
しかし、前述のように、コレクションは配列よりもはるかに強力で、直感的なインターフェースを使用して連鎖させることができる様々なmap/reduce操作を提供しています。例えば、非アクティブなモデルをすべて削除し、残りのユーザーの名前を収集することができます：
$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インスタンスを返します。
append contains diff except find findOrFail fresh intersect load loadMissing modelKeys makeVisible makeHidden only setVisible setHidden toQuery unique
append($attributes)¶
appendメソッドは、コレクション内のすべてのモデルに対して追加する属性を指定するために使用できます。このメソッドは、属性の配列または単一の属性を受け入れます。このメソッドは、属性の配列または単一の属性を受け入れます：
$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は主キーに一致するモデルを返そうとします。$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']);
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
{
/**
* 新しいEloquentコレクションインスタンスを作成します。
*
* @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メソッドを定義する必要があります。