> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Eloquent 컬렉션

> Illuminate\Database\Eloquent\Collection의 전용 메서드와 커스텀 컬렉션을 만드는 방법을 설명합니다.

## 소개

Eloquent에서 여러 건의 모델을 가져오면 결과는 `Illuminate\Database\Eloquent\Collection`으로 반환됩니다.\
이 클래스는 `Illuminate\Support\Collection`을 상속하고 있으므로 베이스 컬렉션의 메서드를 그대로 사용할 수 있습니다.

```mermaid theme={null}
classDiagram
    class "Illuminate\\Support\\Collection" as SupportCollection
    class "Illuminate\\Database\\Eloquent\\Collection" as EloquentCollection
    SupportCollection <|-- EloquentCollection
```

```php theme={null}
use App\Models\User;

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

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

먼저 기본이 되는 [컬렉션](/ko/collections)과 [Eloquent 입문](/ko/eloquent)을 익혀 두면 Eloquent 컬렉션의 확장 포인트를 이해하기 쉬워집니다.

## 사용 가능한 메서드

`Eloquent\Collection`은 베이스 컬렉션의 모든 메서드를 상속하고, 추가로 모델용 메서드를 제공합니다.

### `append` / `withoutAppends` / `setAppends`

시리얼라이즈 시의 추가 속성(appends)을 컬렉션 전체에 대해 조작할 수 있습니다.

```php theme={null}
$users->append('team');
$users->append(['team', 'is_admin']);

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

### `contains` / `diff` / `except` / `intersect` / `only`

모델 인스턴스나 기본 키를 기준으로 포함 판정·차집합·교집합·제외·추출을 수행합니다.

```php theme={null}
use App\Models\User;

$users->contains(1);
$users->contains(User::find(1));

$subset = User::whereIn('id', [1, 2, 3])->get();

$users->diff($subset);
$users->intersect($subset);

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

### `find` / `findOrFail`

가져온 컬렉션에서 기본 키로 모델을 검색합니다.

```php theme={null}
$users = User::all();

$user = $users->find(1);
$user = $users->findOrFail(1);
```

### `fresh`

컬렉션 내 각 모델을 데이터베이스의 최신 상태로 다시 가져옵니다.

```php theme={null}
$users = $users->fresh();
$users = $users->fresh('comments');
```

### `load` / `loadMissing`

이미 가져온 컬렉션에 대해서 나중에 관계를 Eager Loading할 수 있습니다.

```php theme={null}
$users->load(['comments', 'posts']);
$users->load('comments.author');
$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);

$users->loadMissing(['comments', 'posts']);
$users->loadMissing('comments.author');
$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);
```

### `modelKeys`

컬렉션 내 모델의 기본 키 목록을 가져옵니다.

```php theme={null}
$users->modelKeys();
// [1, 2, 3, ...]
```

### `makeVisible` / `makeHidden` / `mergeVisible` / `mergeHidden` / `setVisible` / `setHidden`

시리얼라이즈 시의 가시 속성·비가시 속성을 컬렉션 단위로 조정할 수 있습니다.

```php theme={null}
$users = $users->makeVisible(['address', 'phone_number']);
$users = $users->makeHidden(['address', 'phone_number']);

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

$users = $users->setVisible(['id', 'name']);
$users = $users->setHidden(['email', 'password', 'remember_token']);
```

### `partition`

조건으로 두 개의 `Eloquent\Collection`으로 분할하고, 외부는 `Illuminate\Support\Collection`으로 반환합니다.

```php theme={null}
$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
```

### `toQuery`

가져온 모델 그룹의 기본 키에 대한 `whereIn` 쿼리를 만들어 일괄 갱신이나 삭제에 사용할 수 있습니다.

```php theme={null}
use App\Models\User;

// 우선 조건에 일치하는 사용자를 가져온다
$vipUsers = User::where('status', 'VIP')->get();

// 컬렉션 대상만 일괄 갱신
$vipUsers->toQuery()->update([
    'status' => 'Administrator',
]);
```

<Tip>
  개별 `save()` 루프보다 `toQuery()`로 일괄 쿼리로 변환하면 실제 운용에서의 성능과 가독성을 양립하기 쉬워집니다.
</Tip>

### `unique`

같은 기본 키를 가진 중복 모델을 제거합니다.

```php theme={null}
$users = $users->unique();
```

## Eloquent 컬렉션에서 베이스 컬렉션으로 변환

`collapse`, `flatten`, `flip`, `keys`, `pluck`, `zip`은 `Illuminate\Support\Collection`을 반환합니다.\
또한 `map` 결과에 Eloquent 모델이 포함되지 않은 경우에도 베이스 컬렉션으로 변환됩니다.

## 커스텀 컬렉션

모델 전용 컬렉션 클래스를 사용하고 싶은 경우, 먼저 `#[CollectedBy]` 애트리뷰트를 사용하는 방법을 선택하면 명료합니다.

### `#[CollectedBy]` 애트리뷰트(권장)

```php theme={null}
<?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 theme={null}
<?php

namespace App\Models;

use App\Support\UserCollection;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public function newCollection(array $models = []): Collection
    {
        $collection = new UserCollection($models);

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

        return $collection;
    }
}
```

`newCollection()` 또는 `#[CollectedBy]`를 정의하면, 일반적으로 `Eloquent\Collection`이 반환되는 상황에서 커스텀 컬렉션이 반환되게 됩니다.\
모든 모델에 적용하고 싶은 경우에는 공통 베이스 모델에서 `newCollection()`을 정의합니다.

## 관련 페이지

<Card title="컬렉션" icon="list" href="/ko/collections">
  `Illuminate\\Support\\Collection`의 기본 조작을 먼저 확인합니다.
</Card>

<Card title="Eloquent 입문" icon="database" href="/ko/eloquent">
  모델과 쿼리의 기초를 정리한 후 Eloquent 컬렉션을 사용해 봅시다.
</Card>


## Related topics

- [컬렉션](/ko/collections.md)
- [컬렉션의 고차 메시지](/ko/advanced/higher-order-messages.md)
- [Eloquent API 리소스](/ko/eloquent-resources.md)
- [Laravel AI SDK](/ko/ai-sdk.md)
- [Laravel Scout](/ko/scout.md)