Eloquent: 컬렉션

업데이트됨

번역일: 2026년 6월 20일

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

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 20일

Eloquent: 컬렉션

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

소개

여러 모델을 반환하는 Eloquent 메서드는 모두 Illuminate\Database\Eloquent\Collection 인스턴스를 반환합니다. get 메서드로 조회한 결과나 관계를 통해 접근한 결과도 마찬가지입니다. Eloquent 컬렉션은 Laravel의 기본 컬렉션을 확장하므로, 기본 컬렉션이 제공하는 수십 가지 메서드를 그대로 사용할 수 있습니다. 컬렉션에서 활용할 수 있는 메서드 전체 목록은 Laravel 컬렉션 문서를 꼭 확인해 보세요.

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

use App\Models\User;

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

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

그러나 컬렉션은 단순 배열보다 훨씬 강력합니다. map, reject 등의 메서드를 체이닝해서 선언적으로 데이터를 가공할 수 있습니다. 예를 들어, 비활성 사용자를 제외하고 나머지 사용자의 이름만 추출하려면 다음과 같이 작성합니다:

$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 메서드는 컬렉션 내 모든 모델에 특정 어트리뷰트를 추가 직렬화 대상으로 지정합니다. 단일 어트리뷰트 또는 배열을 전달할 수 있습니다:

$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 메서드는 주어진 기본 키와 일치하는 모델을 반환합니다. 모델 인스턴스를 전달하면 해당 기본 키와 일치하는 모델을 찾으며, 키 배열을 전달하면 해당하는 모든 모델을 반환합니다:

$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 메서드는 모델에서 기본적으로 "숨김" 처리된 어트리뷰트를 컬렉션 내 모든 모델에서 표시되도록 합니다:

$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\Support\Collection 인스턴스이며, 각 요소는 Illuminate\Database\Eloquent\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 attributes)를 일시적으로 지정한 값으로 덮어씁니다:

$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 attributes)를 일시적으로 모두 제거합니다:

$users = $users->withoutAppends();

커스텀 컬렉션

특정 모델에서 커스텀 컬렉션 클래스를 사용하고 싶다면, 모델에 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 메서드를 정의하세요.