Eloquent: 컬렉션

번역일: 2026년 6월 20일

Eloquent: 컬렉션

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

소개

여러 모델을 반환하는 Eloquent 메서드는 모두 Illuminate\Database\Eloquent\Collection 인스턴스를 반환합니다. get 메서드로 조회한 결과나 연관관계를 통해 접근한 결과 모두 마찬가지입니다. Eloquent 컬렉션은 Laravel의 기본 컬렉션을 상속하므로, Eloquent 모델 배열을 유연하게 다룰 수 있는 수십 가지 메서드를 그대로 사용할 수 있습니다. 유용한 메서드 목록은 Laravel 컬렉션 문서를 꼭 참고하세요.

컬렉션은 이터레이터(iterator)이기도 하므로, 일반 PHP 배열처럼 반복(loop) 처리할 수 있습니다.

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

append 메서드는 컬렉션 내 모든 모델에 특정 어트리뷰트를 JSON에 추가(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 loading)합니다.

$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 메서드는 컬렉션 내 각 모델에서 평소에 표시되는 어트리뷰트를 숨김 처리합니다.

$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 메서드는 컬렉션 내 각 모델의 appended 어트리뷰트 목록을 임시로 덮어씁니다.

$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 메서드는 컬렉션 내 각 모델에서 appended 어트리뷰트를 임시로 모두 제거합니다.

$users = $users->withoutAppends();

커스텀 컬렉션

특정 모델에서 커스텀 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
    {
        $collection = new UserCollection($models);

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

        return $collection;
    }
}

newCollection 메서드를 정의하거나 CollectedBy 어트리뷰트를 추가하면, Eloquent가 기존에 Illuminate\Database\Eloquent\Collection을 반환하던 모든 상황에서 커스텀 컬렉션 인스턴스를 받을 수 있습니다.

NOTE

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