> ## 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;
}
```

建議先熟悉基底的[集合](/zh-TW/collections)與 [Eloquent 入門](/zh-TW/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`

依條件將集合切成 2 個 `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="/zh-TW/collections">
  先熟悉 `Illuminate\\Support\\Collection` 的基本操作。
</Card>

<Card title="Eloquent 入門" icon="database" href="/zh-TW/eloquent">
  在使用 Eloquent 集合前，先整理模型與查詢的基礎。
</Card>


## Related topics

- [Eloquent API 資源](/zh-TW/eloquent-resources.md)
- [集合](/zh-TW/collections.md)
- [Eloquent 序列化](/zh-TW/eloquent-serialization.md)
- [Eloquent 關聯入門](/zh-TW/eloquent-relationships.md)
- [Laravel Scout](/zh-TW/scout.md)