컬렉션

번역일: 2026년 6월 20일

컬렉션

소개
- 컬렉션 생성
- 컬렉션 확장
사용 가능한 메서드
고차 메시지
지연 컬렉션

소개

Illuminate\Support\Collection 클래스는 배열 데이터를 다루기 위한 유연하고 편리한 래퍼를 제공합니다. 아래 예시를 살펴보세요. collect 헬퍼로 배열에서 새 컬렉션 인스턴스를 만들고, 각 요소에 strtoupper 함수를 적용한 뒤, 빈 요소를 제거합니다.

$collection = collect(['taylor', 'abigail', null])->map(function (?string $name) {
    return strtoupper($name);
})->reject(function (string $name) {
    return empty($name);
});

보이는 것처럼 Collection 클래스는 메서드를 체이닝하여 배열을 유연하게 변환하고 가공할 수 있게 해줍니다. 컬렉션은 기본적으로 불변(immutable)으로 동작하며, 대부분의 메서드는 원본을 수정하지 않고 새로운 Collection 인스턴스를 반환합니다.

컬렉션 생성

위에서 설명한 것처럼 collect 헬퍼는 주어진 배열로 새로운 Illuminate\Support\Collection 인스턴스를 반환합니다. 컬렉션 생성은 다음과 같이 간단합니다.

$collection = collect([1, 2, 3]);

NOTE

Eloquent 쿼리의 결과는 항상 Collection 인스턴스로 반환됩니다.

컬렉션 확장

컬렉션은 "매크로(macro)" 기능을 지원하므로, 런타임에 Collection 클래스에 새 메서드를 추가할 수 있습니다. Illuminate\Support\Collection 클래스의 macro 메서드는 매크로가 호출될 때 실행될 클로저를 인자로 받습니다. 매크로 클로저 안에서는 $this를 통해 컬렉션의 다른 메서드에 접근할 수 있습니다. 마치 실제 클래스 메서드처럼 동작합니다. 예를 들어 다음 코드는 Collection 클래스에 toUpper 메서드를 추가합니다.

use Illuminate\Support\Collection;
use Illuminate\Support\Str;

Collection::macro('toUpper', function () {
    return $this->map(function (string $value) {
        return Str::upper($value);
    });
});

$collection = collect(['first', 'second']);

$upper = $collection->toUpper();

// ['FIRST', 'SECOND']

컬렉션 매크로는 보통 서비스 프로바이더의 boot 메서드에서 등록하는 것이 좋습니다.

매크로에 인수 전달

필요하다면 추가 인수를 받는 매크로를 정의할 수도 있습니다.

use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Lang;

Collection::macro('toLocale', function (string $locale) {
    return $this->map(function (string $value) use ($locale) {
        return Lang::get($value, [], $locale);
    });
});

$collection = collect(['first', 'second']);

$translated = $collection->toLocale('es');

사용 가능한 메서드

이어지는 컬렉션 문서에서는 Collection 클래스에서 사용할 수 있는 모든 메서드를 다룹니다. 이 메서드들은 모두 체이닝하여 배열을 유연하게 조작할 수 있으며, 거의 모든 메서드가 새로운 Collection 인스턴스를 반환하므로 필요할 때 원본 컬렉션을 보존할 수 있습니다.

all average avg chunk chunkWhile collapse collect combine concat contains containsOneItem containsStrict count countBy crossJoin dd diff diffAssoc diffAssocUsing diffKeys doesntContain dot dump duplicates duplicatesStrict each eachSpread ensure every except filter first firstOrFail firstWhere flatMap flatten flip forget forPage get groupBy has hasAny implode intersect intersectAssoc intersectByKeys isEmpty isNotEmpty join keyBy keys last lazy macro make map mapInto mapSpread mapToGroups mapWithKeys max median merge mergeRecursive min mode nth only pad partition percentage pipe pipeInto pipeThrough pluck pop prepend pull push put random range reduce reduceSpread reject replace replaceRecursive reverse search select shift shuffle skip skipUntil skipWhile slice sliding sole some sort sortBy sortByDesc sortDesc sortKeys sortKeysDesc sortKeysUsing splice split splitIn sum take takeUntil takeWhile tap times toArray toJson transform undot union unique uniqueStrict unless unlessEmpty unlessNotEmpty unwrap value values when whenEmpty whenNotEmpty where whereStrict whereBetween whereIn whereInStrict whereInstanceOf whereNotBetween whereNotIn whereNotInStrict whereNotNull whereNull wrap zip

메서드 목록

`all()` {.collection-method .first-collection-method}

all 메서드는 컬렉션이 가진 배열을 그대로 반환합니다.

collect([1, 2, 3])->all();

// [1, 2, 3]

`average()` {.collection-method}

avg 메서드의 별칭입니다.

`avg()` {.collection-method}

avg 메서드는 주어진 키의 평균값을 반환합니다.

$average = collect([
    ['foo' => 10],
    ['foo' => 10],
    ['foo' => 20],
    ['foo' => 40]
])->avg('foo');

// 20

$average = collect([1, 1, 2, 4])->avg();

// 2

`chunk()` {.collection-method}

chunk 메서드는 컬렉션을 주어진 크기의 작은 컬렉션 여러 개로 나눕니다.

$collection = collect([1, 2, 3, 4, 5, 6, 7]);

$chunks = $collection->chunk(4);

$chunks->all();

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

이 메서드는 뷰에서 Bootstrap 같은 그리드 시스템을 사용할 때 특히 유용합니다. 예를 들어 Eloquent 모델 컬렉션을 그리드로 표시하는 경우를 생각해보세요.

@foreach ($products->chunk(3) as $chunk)
    <div class="row">
        @foreach ($chunk as $product)
            <div class="col-xs-4">{{ $product->name }}</div>
        @endforeach
    </div>
@endforeach

`chunkWhile()` {.collection-method}

chunkWhile 메서드는 주어진 콜백의 평가 결과에 따라 컬렉션을 여러 개의 작은 컬렉션으로 나눕니다. 클로저에 전달되는 $chunk 변수를 이용해 이전 요소를 확인할 수 있습니다.

$collection = collect(str_split('AABBCCCD'));

$chunks = $collection->chunkWhile(function (string $value, int $key, Collection $chunk) {
    return $value === $chunk->last();
});

$chunks->all();

// [['A', 'A'], ['B', 'B'], ['C', 'C', 'C'], ['D']]

`collapse()` {.collection-method}

collapse 메서드는 배열로 이루어진 컬렉션을 하나의 평탄한 컬렉션으로 합칩니다.

$collection = collect([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]);

$collapsed = $collection->collapse();

$collapsed->all();

// [1, 2, 3, 4, 5, 6, 7, 8, 9]

`collect()` {.collection-method}

collect 메서드는 현재 컬렉션의 항목을 담은 새로운 Collection 인스턴스를 반환합니다.

$collectionA = collect([1, 2, 3]);

$collectionB = $collectionA->collect();

$collectionB->all();

// [1, 2, 3]

collect 메서드는 지연 컬렉션을 일반 Collection 인스턴스로 변환할 때 특히 유용합니다.

$lazyCollection = LazyCollection::make(function () {
    yield 1;
    yield 2;
    yield 3;
});

$collection = $lazyCollection->collect();

$collection::class;

// 'Illuminate\Support\Collection'

$collection->all();

// [1, 2, 3]

NOTE

collect 메서드는 Enumerable 인스턴스를 비지연(non-lazy) 컬렉션으로 변환해야 할 때 특히 유용합니다. collect()는 Enumerable 계약의 일부이므로 안전하게 Collection 인스턴스를 얻는 데 사용할 수 있습니다.

`combine()` {.collection-method}

combine 메서드는 컬렉션의 값들을 키로 삼아, 다른 배열 또는 컬렉션의 값들과 결합합니다.

$collection = collect(['name', 'age']);

$combined = $collection->combine(['George', 29]);

$combined->all();

// ['name' => 'George', 'age' => 29]

`concat()` {.collection-method}

concat 메서드는 주어진 array 또는 컬렉션의 값을 원본 컬렉션 끝에 이어 붙입니다.

$collection = collect(['John Doe']);

$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);

$concatenated->all();

// ['John Doe', 'Jane Doe', 'Johnny Doe']

concat 메서드는 원본 컬렉션에 이어 붙여진 항목들의 키를 숫자로 재색인합니다. 연관 배열(associative array)에서 키를 유지하려면 merge 메서드를 사용하세요.

`contains()` {.collection-method}

contains 메서드는 컬렉션에 주어진 항목이 있는지 확인합니다. 클로저를 전달하면 주어진 조건을 만족하는 요소가 있는지 검사합니다.

$collection = collect([1, 2, 3, 4, 5]);

$collection->contains(function (int $value, int $key) {
    return $value > 5;
});

// false

또는 문자열을 전달해 해당 값이 컬렉션에 존재하는지 확인할 수 있습니다.

$collection = collect(['name' => 'Desk', 'price' => 100]);

$collection->contains('Desk');

// true

$collection->contains('New York');

// false

키/값 쌍을 전달하면 해당 쌍이 컬렉션에 존재하는지 확인합니다.

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
]);

$collection->contains('product', 'Bookcase');

// false

contains 메서드는 항목 값을 확인할 때 "느슨한(loose)" 비교를 사용합니다. 즉, 정수 값을 가진 문자열은 동일한 값의 정수와 같다고 간주합니다. "엄격한(strict)" 비교를 사용하려면 containsStrict 메서드를 사용하세요.

contains의 반대 동작은 doesntContain 메서드를 참고하세요.

`containsOneItem()` {.collection-method}

containsOneItem 메서드는 컬렉션에 항목이 정확히 하나만 있는지 확인합니다.

collect([])->containsOneItem();

// false

collect(['1'])->containsOneItem();

// true

collect(['1', '2'])->containsOneItem();

// false

`containsStrict()` {.collection-method}

contains 메서드와 동일한 시그니처를 가지지만, 모든 값을 "엄격한(strict)" 비교로 검사합니다.

NOTE

Eloquent 컬렉션을 사용할 때는 이 메서드의 동작이 달라집니다.

`count()` {.collection-method}

count 메서드는 컬렉션의 전체 항목 수를 반환합니다.

$collection = collect([1, 2, 3, 4]);

$collection->count();

// 4

`countBy()` {.collection-method}

countBy 메서드는 컬렉션 내 값의 출현 횟수를 셉니다. 기본적으로 모든 요소의 출현 횟수를 세어 특정 "유형"의 요소 수를 파악할 수 있습니다.

$collection = collect([1, 2, 2, 2, 3]);

$counted = $collection->countBy();

$counted->all();

// [1 => 1, 2 => 3, 3 => 1]

클로저를 전달하면 커스텀 값을 기준으로 모든 항목을 셀 수 있습니다.

$collection = collect(['alice@gmail.com', 'bob@naver.com', 'carlos@gmail.com']);

$counted = $collection->countBy(function (string $email) {
    return substr(strrchr($email, "@"), 1);
});

$counted->all();

// ['gmail.com' => 2, 'naver.com' => 1]

`crossJoin()` {.collection-method}

crossJoin 메서드는 컬렉션의 값을 주어진 배열 또는 컬렉션과 교차 결합하여 가능한 모든 조합의 카테시안 곱(Cartesian product)을 반환합니다.

$collection = collect([1, 2]);

$matrix = $collection->crossJoin(['a', 'b']);

$matrix->all();

/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/

$collection = collect([1, 2]);

$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);

$matrix->all();

/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/

`dd()` {.collection-method}

dd 메서드는 컬렉션의 항목을 덤프하고 스크립트 실행을 종료합니다.

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dd();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/

스크립트 실행을 종료하지 않으려면 dump 메서드를 사용하세요.

`diff()` {.collection-method}

diff 메서드는 값을 기준으로 컬렉션과 다른 컬렉션 또는 PHP 배열을 비교하여, 원본 컬렉션에는 있지만 주어진 컬렉션에는 없는 값을 반환합니다.

$collection = collect([1, 2, 3, 4, 5]);

$diff = $collection->diff([2, 4, 6, 8]);

$diff->all();

// [1, 3, 5]

NOTE

Eloquent 컬렉션을 사용할 때는 이 메서드의 동작이 달라집니다.

`diffAssoc()` {.collection-method}

diffAssoc 메서드는 키와 값을 모두 기준으로 컬렉션과 다른 컬렉션 또는 PHP 배열을 비교하여, 원본 컬렉션에는 있지만 주어진 컬렉션에는 없는 키/값 쌍을 반환합니다.

$collection = collect([
    'color' => 'orange',
    'type' => 'fruit',
    'remain' => 6,
]);

$diff = $collection->diffAssoc([
    'color' => 'yellow',
    'type' => 'fruit',
    'remain' => 3,
    'used' => 6,
]);

$diff->all();

// ['color' => 'orange', 'remain' => 6]

`diffAssocUsing()` {.collection-method}

diffAssoc와 달리, diffAssocUsing은 인덱스 비교에 사용자 정의 콜백 함수를 사용합니다.

$collection = collect([
    'color' => 'orange',
    'type' => 'fruit',
    'remain' => 6,
]);

$diff = $collection->diffAssocUsing([
    'Color' => 'yellow',
    'Type' => 'fruit',
    'Remain' => 3,
], 'strnatcasecmp');

$diff->all();

// ['color' => 'orange', 'remain' => 6]

콜백은 0보다 작거나, 같거나, 크거나 한 정수를 반환하는 비교 함수여야 합니다. 내부적으로는 PHP의 array_diff_uassoc 함수를 사용합니다.

`diffKeys()` {.collection-method}

diffKeys 메서드는 키를 기준으로 컬렉션과 다른 컬렉션 또는 PHP 배열을 비교하여, 원본 컬렉션에는 있지만 주어진 컬렉션에는 없는 키/값 쌍을 반환합니다.

$collection = collect([
    'one' => 10,
    'two' => 20,
    'three' => 30,
    'four' => 40,
    'five' => 50,
]);

$diff = $collection->diffKeys([
    'two' => 2,
    'four' => 4,
    'six' => 6,
    'eight' => 8,
]);

$diff->all();

// ['one' => 10, 'three' => 30, 'five' => 50]

`doesntContain()` {.collection-method}

doesntContain 메서드는 컬렉션에 주어진 항목이 없는지 확인합니다. 클로저를 전달해 주어진 조건을 만족하는 요소가 없는지 검사할 수 있습니다.

$collection = collect([1, 2, 3, 4, 5]);

$collection->doesntContain(function (int $value, int $key) {
    return $value < 5;
});

// false

문자열을 전달하면 해당 값이 컬렉션에 없는지 확인합니다.

$collection = collect(['name' => 'Desk', 'price' => 100]);

$collection->doesntContain('Table');

// true

$collection->doesntContain('Desk');

// false

키/값 쌍을 전달하면 해당 쌍이 컬렉션에 없는지 확인합니다.

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
]);

$collection->doesntContain('product', 'Bookcase');

// true

doesntContain 메서드도 항목 값을 확인할 때 "느슨한" 비교를 사용합니다.

`dot()` {.collection-method}

dot 메서드는 다차원 컬렉션을 깊이를 나타내는 "점(dot) 표기법"을 사용한 단일 레벨 컬렉션으로 평탄화합니다.

$collection = collect(['products' => ['desk' => ['price' => 100]]]);

$flattened = $collection->dot();

$flattened->all();

// ['products.desk.price' => 100]

`dump()` {.collection-method}

dump 메서드는 컬렉션의