簡介 (Introduction)
所有回傳多個模型結果的 Eloquent 方法，包括透過 get 方法檢索或透過關聯存取的結果，都會回傳 Illuminate\Database\Eloquent\Collection 類別的實例。Eloquent 集合物件擴展了 Laravel 的 基底集合，因此它自然繼承了數十種方法，供你以流暢的方式處理底層 Eloquent 模型陣列。請務必查看 Laravel 集合文件，以了解所有這些有用的方法！
所有集合也是可迭代的，允許你像遍歷簡單 PHP 陣列一樣遍歷它們：
use App\Models\User;
$users = User::where('active', 1)->get();
foreach ($users as $user) {
echo $user->name;
}如前所述，集合比陣列更強大，並公開了各種直觀的 map / reduce 操作，這些操作可以使用直觀的介面進行串接。例如，我們可以刪除所有非活躍模型，然後收集其餘每個使用者的名字：
$names = User::all()->reject(function (User $user) {
return $user->active === false;
})->map(function (User $user) {
return $user->name;
});Eloquent 集合轉換 (Eloquent Collection Conversion)
雖然大多數 Eloquent 集合方法回傳一個新的 Eloquent 集合實例，但 collapse、flatten、flip、keys、pluck 和 zip 方法則回傳 基底集合 實例。同樣，如果 map 操作回傳一個不包含任何 Eloquent 模型的集合，它將被轉換為基底集合實例。
可用方法 (Available Methods)
所有 Eloquent 集合都擴展了基底 Laravel 集合 物件；因此，它們繼承了基底集合類別提供的所有強大方法。
此外，Illuminate\Database\Eloquent\Collection 類別提供了一套超集方法來幫助管理你的模型集合。大多數方法回傳 Illuminate\Database\Eloquent\Collection 實例；然而，某些方法（如 modelKeys）則回傳 Illuminate\Support\Collection 實例。
append($attributes)
append 方法可用於指示應為集合中的每個模型 附加 一個屬性。此方法接受屬性陣列或單個屬性：
$users->append('team');
$users->append(['team', 'is_admin']);contains($key, $operator = null, $value = null)
contains 方法可用於確定給定模型實例是否包含在集合中。此方法接受主鍵或模型實例：
$users->contains(1);
$users->contains(User::find(1));diff($items)
diff 方法回傳所有不存在於給定集合中的模型：
use App\Models\User;
$users = $users->diff(User::whereIn('id', [1, 2, 3])->get());except($keys)
except 方法回傳所有不具有給定主鍵的模型：
$users = $users->except([1, 2, 3]);find($key)
find 方法回傳主鍵與給定鍵匹配的模型。如果 $key 是模型實例，find 將嘗試回傳與主鍵匹配的模型。如果 $key 是鍵陣列，find 將回傳所有主鍵在給定陣列中的模型：
$users = User::all();
$user = $users->find(1);findOrFail($key)
findOrFail 方法回傳主鍵與給定鍵匹配的模型，如果在集合中找不到匹配的模型，則拋出 Illuminate\Database\Eloquent\ModelNotFoundException 異常：
$users = User::all();
$user = $users->findOrFail(1);fresh($with = [])
fresh 方法從資料庫中檢索集合中每個模型的新實例。此外，任何指定的關聯都將被預先載入：
$users = $users->fresh();
$users = $users->fresh('comments');intersect($items)
intersect 方法回傳所有也存在於給定集合中的模型：
use App\Models\User;
$users = $users->intersect(User::whereIn('id', [1, 2, 3])->get());load($relations)
load 方法為集合中的所有模型預先載入給定的關聯：
$users->load(['comments', 'posts']);
$users->load('comments.author');
$users->load(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);loadMissing($relations)
如果關聯尚未載入，loadMissing 方法將為集合中的所有模型預先載入給定的關聯：
$users->loadMissing(['comments', 'posts']);
$users->loadMissing('comments.author');
$users->loadMissing(['comments', 'posts' => fn ($query) => $query->where('active', 1)]);modelKeys()
modelKeys 方法回傳集合中所有模型的主鍵：
$users->modelKeys();
// [1, 2, 3, 4, 5]makeVisible($attributes)
makeVisible 方法 使屬性可見，這些屬性通常在集合中的每個模型上都是「隱藏」的：
$users = $users->makeVisible(['address', 'phone_number']);makeHidden($attributes)
makeHidden 方法 隱藏屬性，這些屬性通常在集合中的每個模型上都是「可見」的：
$users = $users->makeHidden(['address', 'phone_number']);only($keys)
only 方法回傳所有具有給定主鍵的模型：
$users = $users->only([1, 2, 3]);partition
partition 方法回傳一個包含 Illuminate\Database\Eloquent\Collection 集合實例的 Illuminate\Support\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\CollectionsetAppends($attributes)
setAppends 方法暫時覆蓋集合中每個模型上的所有 附加屬性：
$users = $users->setAppends(['is_admin']);setVisible($attributes)
setVisible 方法 暫時覆蓋 集合中每個模型上的所有可見屬性：
$users = $users->setVisible(['id', 'name']);setHidden($attributes)
setHidden 方法 暫時覆蓋 集合中每個模型上的所有隱藏屬性：
$users = $users->setHidden(['email', 'password', 'remember_token']);toQuery()
toQuery 方法回傳一個 Eloquent 查詢建構器實例，其中包含對集合模型主鍵的 whereIn 約束：
use App\Models\User;
$users = User::where('status', 'VIP')->get();
$users->toQuery()->update([
'status' => 'Administrator',
]);unique($key = null, $strict = false)
unique 方法回傳集合中所有唯一的模型。任何與集合中另一個模型具有相同主鍵的模型都將被刪除：
$users = $users->unique();withoutAppends($attributes)
withoutAppends 方法暫時移除集合中每個模型上的所有 附加屬性：
$users = $users->withoutAppends();自訂集合 (Custom Collections)
若你想對給定模型使用一個自訂 Collection 物件，你可以在你的模型上加上 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
{
/**
* Create a new Eloquent Collection instance.
*
* @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 實例時，你將收到自訂集合的實例。
如果你想為應用程式中的每個模型使用自訂集合，你應該在應用程式的所有模型擴展的基底模型類別上定義 newCollection 方法。