Eloquent：コレクション 7.x Laravel

イントロダクション

getメソッドであれリレーションによるものであれ、Eloquentが複数のレコードをリターンする場合Illuminate\Database\Eloquent\Collectionオブジェクトが返されます。EloquentコレクションオブジェクトはLaravelのベースコレクションを継承しているので、Eloquentモデルの裏にある配列をスムーズに操作するために継承した多くのメソッドがもちろん使用できます。

全コレクションはイテレーターとしても動作し、シンプルなPHP配列のようにループで取り扱うことができます。

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

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

しかし、コレクションは配列よりもパワフルで直感的なインターフェイスを使ったメソッドチェーンにより、マッピングや要素の省略操作を行うことができます。例としてアクティブでないモデルを削除し、残ったユーザーのファーストネームを集めてみましょう。

$users = App\User::all();

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

Note: ほとんどのEloquentコレクションは新しいEloquentコレクションのインスタンスを返しますが、pluck、keys、zip、collapse、flatten、flipメソッドはベースのコレクションインスタンスを返します。Eloquentモデルをまったく含まないコレクションを返すmap操作のような場合、自動的にベースコレクションへキャストされます。

使用できるメソッド

全EloquentコレクションはベースのLaravelコレクションオブジェクトを拡張しており、そのためにベースコレクションクラスが提供しているパワフルなメソッドを全部継承しています。

さらに、Illuminate\Database\Eloquent\Collectionクラスは、モデルコレクションを管理するのに役立つメソッドのスーパーセットを提供しています。ほとんどのメソッドはIlluminate\Database\Eloquent\Collectionインスタンスを返しますが、いくつかのメソッドはIlluminate\Support\Collectionインスタンスを返します。

contains diff except find fresh intersect load loadMissing modelKeys makeVisible makeHidden only toQuery unique

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

containsメソッドは、指定したモデルインスタンスがコレクションに含まれるかを判定します。このメソッドは主キーかモデルインスタンスを引数に取ります。

$users->contains(1);

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

`diff($items)`

diffメソッドは、指定したコレクション中に存在しないモデルをすべて返します。

use App\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がキーの配列の場合はwhereIn()を使用して、$keyと一致するモデルをすべて返します。

$users = User::all();

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

`fresh($with = [])`

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

$users = $users->fresh();

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

`intersect($items)`

intersectメソッドは指定したコレクション中にも存在する、すべてのモデルを返します。

use App\User;

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

`load($relations)`

loadメソッドは指定したリレーションをコレクションの全モデルに対してEagerロードします。

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

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

`loadMissing($relations)`

loadMissingメソッドは、リレーションがまだロードされていない場合、指定したリレーションをコレクションのすべてのモデルに対してEagerロードします。

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

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

`modelKeys()`

modelKeysメソッドは、コレクションの全モデルの主キーを返します。

$users->modelKeys();

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

`makeVisible($attributes)`

makeVisibleメソッドはコレクション中の各モデルの、通常「隠されている(hidden)」属性を可視化(Visible)にします。

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

`makeHidden($attributes)`

makeHiddenメソッドはコレクション中の各モデルの、通常「可視化(Visible)されている」属性を可視化隠し(hidden)ます。

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

`only($keys)`

onlyメソッドは、指定した主キーを持つモデルを全部返します。

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

`toQuery()`

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

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

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

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

uniqueメソッドは、コレクション中のユニークなモデルをすべて返します。コレクション中の同じタイプで同じ主キーを持つモデルは削除されます。

$users = $users->unique();

カスタムコレクション

自分で拡張したメソッドを含むカスタム「コレクション」オブジェクトを使いたい場合は、モデルのnewCollectionメソッドをオーバーライドしてください。

<?php

namespace App;

use App\CustomCollection;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 新しいEloqunetコレクションインスタンスの生成
     *
     * @param  array  $models
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function newCollection(array $models = [])
    {
        return new CustomCollection($models);
    }
}

newCollectionメソッドを定義すれば、Eloquentがそのモデルの「コレクション」インスタンスを返す場合にいつでもカスタムコレクションのインスタンスを受け取れます。アプリケーションの全モデルでカスタムコレクションを使いたい場合は、全モデルが拡張しているモデルのベースクラスでnewCollectionメソッドをオーバーライドしてください。

Laravel 7.x Eloquent：コレクション