Eloquent: 컬렉션

번역일: 2026년 6월 20일

Eloquent: 컬렉션

소개
사용 가능한 메서드
커스텀 컬렉션

소개

Eloquent에서 여러 모델을 반환하는 메서드는 모두 Illuminate\Database\Eloquent\Collection 인스턴스를 반환합니다. get 메서드로 조회한 결과나 관계(relationship)를 통해 접근한 결과 모두 마찬가지입니다. Eloquent 컬렉션은 Laravel의 기본 컬렉션을 확장하므로, 기본 컬렉션이 제공하는 수십 가지 메서드를 그대로 사용할 수 있습니다. 기본 컬렉션의 다양한 메서드도 함께 익혀두면 좋습니다.

컬렉션은 이터러블(iterable)이기도 해서, 일반 PHP 배열처럼 foreach로 순회할 수 있습니다.

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)` {.collection-method .first-collection-method}

append 메서드는 컬렉션 내 모든 모델에 특정 어트리뷰트를 추가로 직렬화하도록 지정합니다. 단일 어트리뷰트 또는 배열로 여러 개를 전달할 수 있습니다.

$users->append('team');

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

`contains($key, $operator = null, $value = null)` {.collection-method}

contains 메서드는 주어진 모델 인스턴스 또는 기본 키(primary key)가 컬렉션에 존재하는지 확인합니다.

$users->contains(1);

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

`diff($items)` {.collection-method}

diff 메서드는 주어진 컬렉션에 포함되지 않은 모델들만 반환합니다.

use App\Models\User;

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

`except($keys)` {.collection-method}

except 메서드는 주어진 기본 키를 가진 모델을 제외한 나머지 모델들을 반환합니다.

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

`find($key)` {.collection-method}

find 메서드는 주어진 기본 키와 일치하는 모델을 반환합니다. $key로 모델 인스턴스를 전달하면 해당 모델의 기본 키와 일치하는 모델을 찾습니다. 키 배열을 전달하면 해당 키들과 일치하는 모든 모델을 반환합니다.

$users = User::all();

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

`findOrFail($key)` {.collection-method}

findOrFail 메서드는 주어진 기본 키와 일치하는 모델을 반환합니다. 컬렉션 내에서 일치하는 모델을 찾지 못하면 Illuminate\Database\Eloquent\ModelNotFoundException 예외를 던집니다.

$users = User::all();

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

`fresh($with = [])` {.collection-method}

fresh 메서드는 컬렉션 내 모든 모델을 데이터베이스에서 새로 조회하여 반환합니다. 관계(relationship)를 함께 이거 로드(eager load)할 수도 있습니다.

$users = $users->fresh();

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

`intersect($items)` {.collection-method}

intersect 메서드는 주어진 컬렉션에도 존재하는 모델들만 반환합니다.

use App\Models\User;

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

`load($relations)` {.collection-method}

load 메서드는 컬렉션 내 모든 모델에 대해 주어진 관계를 이거 로드합니다.

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

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

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

`loadMissing($relations)` {.collection-method}

loadMissing 메서드는 아직 로드되지 않은 관계에 한해서만 이거 로드를 수행합니다. 이미 로드된 관계는 다시 쿼리하지 않으므로 불필요한 쿼리를 방지할 수 있습니다.

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

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

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

`modelKeys()` {.collection-method}

modelKeys 메서드는 컬렉션 내 모든 모델의 기본 키를 배열로 반환합니다.

$users->modelKeys();

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

`makeVisible($attributes)` {.collection-method}

makeVisible 메서드는 평소에 숨겨져 있는 어트리뷰트를 컬렉션 내 모든 모델에서 표시되도록 설정합니다.

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

`makeHidden($attributes)` {.collection-method}

makeHidden 메서드는 평소에 표시되는 어트리뷰트를 컬렉션 내 모든 모델에서 숨기도록 설정합니다.

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

`only($keys)` {.collection-method}

only 메서드는 주어진 기본 키에 해당하는 모델들만 반환합니다.

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

`setVisible($attributes)` {.collection-method}

setVisible 메서드는 컬렉션 내 모든 모델의 표시 어트리뷰트를 일시적으로 덮어씁니다.

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

`setHidden($attributes)` {.collection-method}

setHidden 메서드는 컬렉션 내 모든 모델의 숨김 어트리뷰트를 일시적으로 덮어씁니다.

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

`toQuery()` {.collection-method}

toQuery 메서드는 컬렉션의 기본 키들을 기반으로 whereIn 조건이 포함된 Eloquent 쿼리 빌더 인스턴스를 반환합니다. 컬렉션 전체에 대해 일괄 업데이트 등의 작업을 수행할 때 유용합니다.

use App\Models\User;

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

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

`unique($key = null, $strict = false)` {.collection-method}

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
{
    /**
     * 새로운 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 메서드를 정의하거나 CollectedBy 어트리뷰트를 추가하면, Eloquent가 원래 Illuminate\Database\Eloquent\Collection을 반환하는 모든 상황에서 커스텀 컬렉션 인스턴스가 반환됩니다.

NOTE

애플리케이션 전체 모델에 커스텀 컬렉션을 적용하려면, 모든 모델이 상속하는 베이스 모델 클래스에 newCollection 메서드를 정의하면 됩니다.