Eloquent: 컬렉션

업데이트됨

번역일: 2026년 9월 30일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 9월 30일
번역 갱신: 2026년 9월 30일

Eloquent: 컬렉션

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

소개

get 메서드로 조회하거나 관계를 통해 접근하는 등, 둘 이상의 모델 결과를 반환하는 모든 Eloquent 메서드는 Illuminate\Database\Eloquent\Collection 클래스의 인스턴스를 반환합니다. Eloquent 컬렉션 객체는 라라벨의 기본 컬렉션을 확장하기 때문에, 내부의 Eloquent 모델 배열을 유연하게 다룰 수 있는 수십 가지 메서드를 자연스럽게 상속받습니다. 이런 유용한 메서드들을 제대로 활용하려면 라라벨 컬렉션 문서를 꼭 함께 살펴보시기 바랍니다!

모든 컬렉션은 반복자(iterator) 역할도 하기 때문에, 일반 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 모델이 하나도 포함되어 있지 않다면, 그 결과는 기본 컬렉션 인스턴스로 변환됩니다.

NOTE

이 부분을 헷갈려하는 분들이 많습니다. 예를 들어 $users->pluck('name')처럼 컬렉션에서 특정 속성 값만 뽑아내면, 결과에는 더 이상 모델 인스턴스가 없으므로 Eloquent 컬렉션의 특수 메서드(load, fresh 등)를 사용할 수 없는 일반 컬렉션이 반환됩니다.

사용 가능한 메서드

모든 Eloquent 컬렉션은 라라벨 기본 컬렉션 객체를 확장하므로, 기본 컬렉션 클래스가 제공하는 강력한 메서드를 모두 상속받습니다.

여기에 더해 Illuminate\Database\Eloquent\Collection 클래스는 모델 컬렉션을 다루는 데 도움이 되는 추가 메서드들을 제공합니다. 대부분의 메서드는 Illuminate\Database\Eloquent\Collection 인스턴스를 반환하지만, pluck처럼 일부 메서드는 Illuminate\Support\Collection 인스턴스를 반환합니다.

`append($attributes)` {.collection-method .first-collection-method}

append 메서드는 컬렉션 내 모든 모델에 특정 속성을 추가(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가 모델 인스턴스라면 해당 기본 키와 일치하는 모델을 찾으려고 시도합니다. $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 메서드는 컬렉션 내 각 모델을 데이터베이스에서 다시 조회하여 최신 인스턴스로 가져옵니다. 지정한 관계가 있다면 즉시 로딩(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 메서드는 컬렉션 내 각 모델에서 평소 "숨김(hidden)" 처리된 속성을 화면에 보이도록 만듭니다:

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

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

makeHidden 메서드는 컬렉션 내 각 모델에서 평소 "노출(visible)" 상태인 속성을 숨김 처리합니다:

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

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

mergeVisible 메서드는 기존에 노출 중인 속성은 그대로 유지하면서, 추가 속성을 더 노출시킵니다:

$users = $users->mergeVisible(['middle_name']);

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

mergeHidden 메서드는 기존에 숨겨진 속성은 그대로 유지하면서, 추가 속성을 더 숨깁니다:

$users = $users->mergeHidden(['last_login_at']);

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

only 메서드는 주어진 기본 키를 가진 모델들만 반환합니다:

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

`partition` {.collection-method}

partition 메서드는 Illuminate\Database\Eloquent\Collection 컬렉션 인스턴스들을 담은 Illuminate\Support\Collection 인스턴스를 반환합니다:

$partition = $users->partition(fn ($user) => $user->age > 18);

dump($partition::class);    // Illuminate\Support\Collection
dump($partition[0]::class); // Illuminate\Database\Eloquent\Collection
dump($partition[1]::class); // Illuminate\Database\Eloquent\Collection

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

setAppends 메서드는 컬렉션 내 각 모델의 추가(append) 속성을 일시적으로 재정의합니다:

$users = $users->setAppends(['is_admin']);

`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();

`withoutAppends()` {.collection-method}

withoutAppends 메서드는 컬렉션 내 각 모델의 추가(append) 속성을 일시적으로 모두 제거합니다:

$users = $users->withoutAppends();

커스텀 컬렉션

특정 모델을 다룰 때 커스텀 Collection 객체를 사용하고 싶다면, 모델에 CollectedBy 속성(attribute)을 추가하면 됩니다:

<?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
    {
        $collection = new UserCollection($models);

        if (Model::isAutomaticallyEagerLoadingRelationships()) {
            $collection->withRelationshipAutoloading();
        }

        return $collection;
    }
}

newCollection 메서드를 정의하거나 CollectedBy 속성을 모델에 추가하고 나면, 이후 Eloquent가 원래 Illuminate\Database\Eloquent\Collection 인스턴스를 반환하던 모든 상황에서 대신 여러분이 정의한 커스텀 컬렉션의 인스턴스를 받게 됩니다.

NOTE

예를 들어 상품 목록에 재고 합계를 구하는 totalStock() 같은 도메인 특화 메서드를 자주 사용한다면, 매번 별도 헬퍼 함수를 호출하는 대신 커스텀 컬렉션 클래스에 메서드로 정의해두면 $products->totalStock()처럼 훨씬 자연스럽게 사용할 수 있습니다.

애플리케이션의 모든 모델에서 커스텀 컬렉션을 사용하고 싶다면, 모든 모델이 상속하는 기본(base) 모델 클래스에 newCollection 메서드를 정의해두는 것이 좋습니다.