Eloquent: 컬렉션

번역일: 2026년 6월 20일

Eloquent: 컬렉션

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

소개

여러 개의 모델을 반환하는 Eloquent 메서드는 모두 Illuminate\Database\Eloquent\Collection 인스턴스를 반환합니다. get 메서드로 조회하거나 관계를 통해 접근할 때도 마찬가지입니다. Eloquent 컬렉션은 Laravel의 기본 컬렉션을 상속하므로, Eloquent 모델 배열을 유창하게 다룰 수 있는 수십 가지 메서드를 그대로 사용할 수 있습니다. 유용한 메서드 목록은 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 contains diff except find 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);

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

fresh 메서드는 컬렉션 내 각 모델의 최신 데이터를 데이터베이스에서 다시 조회합니다. 관계를 지정하면 이를 함께 Eager 로드할 수 있습니다.

$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 메서드는 컬렉션 내 모든 모델에 대해 주어진 관계를 Eager 로드합니다.

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

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

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

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

loadMissing 메서드는 아직 로드되지 않은 관계만 선택적으로 Eager 로드합니다. 이미 로드된 관계는 다시 쿼리하지 않습니다.

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

커스텀 컬렉션

특정 모델을 다룰 때 직접 만든 컬렉션 클래스를 사용하고 싶다면, 모델에 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 메서드를 정의하면, Eloquent가 기본적으로 Illuminate\Database\Eloquent\Collection을 반환하는 모든 경우에 커스텀 컬렉션 인스턴스가 대신 반환됩니다.

NOTE

애플리케이션의 모든 모델에 커스텀 컬렉션을 적용하려면, 공통 베이스 모델 클래스에 newCollection 메서드를 정의하고 나머지 모델이 이를 상속받도록 구성하세요.