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;
}

しかし、前述のように、コレクションは配列よりもはるかに強力であり、直感的なインターフェースを使用してチェーンできるさまざまなマップ/リダクション操作を提供します。たとえば、すべての非アクティブなモデルを削除し、残りのユーザーごとにファーストネームを収集できます。

$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($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`は指定された配列に主キーを持つすべてのモデルを返します。

$users = User::all();
 
$user = $users->find(1);

findOrFail($key)

`findOrFail`メソッドは、指定されたキーと一致する主キーを持つモデルを返します。コレクションに一致するモデルが見つからない場合は、`Illuminate\Database\Eloquent\ModelNotFoundException`例外をスローします。

$users = User::all();
 
$user = $users->findOrFail(1);

fresh($with = [])

`fresh`メソッドは、データベースからコレクション内の各モデルの新しいインスタンスを取得します。さらに、指定されたリレーションシップはすべて eager loading されます。

$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`メソッドは、コレクション内のすべてのモデルに対して指定されたリレーションシップを eager loading します。

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

loadMissing($relations)

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

$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`オブジェクトを使用したい場合は、モデルに`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
    {
        return new UserCollection($models);
    }
}

`newCollection`メソッドを定義するか、モデルに`CollectedBy`属性を追加すると、Eloquentが通常`Illuminate\Database\Eloquent\Collection`インスタンスを返すときに、カスタムコレクションのインスタンスが返されます。

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