Eloquent: Collections

Giới thiệu (Introduction)

Tất cả các phương thức Eloquent trả về nhiều model sẽ trả về instance của class Illuminate\Database\Eloquent\Collection, bao gồm kết quả từ method get hoặc truy cập qua relationship. Eloquent collection kế thừa base collection của Laravel, cung cấp hàng chục phương thức hữu ích.

Tất cả collection cũng là iterator, cho phép lặp qua như mảng PHP:

use App\Models\User;

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

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

Collection mạnh hơn mảng nhiều — hỗ trợ các thao tác map/reduce:

$names = User::all()->reject(function (User $user) {
    return $user->active === false;
})->map(function (User $user) {
    return $user->name;
});

Chuyển đổi Eloquent Collection

Hầu hết các method trả về Eloquent collection mới, ngoại trừ collapse, flatten, flip, keys, pluck, và zip — trả về instance base collection. Tương tự, nếu map trả về collection không chứa Eloquent model, nó sẽ được chuyển thành base collection.

Các phương thức có sẵn (Available Methods)

Eloquent collection kế thừa tất cả method từ base collection. Ngoài ra, class Illuminate\Database\Eloquent\Collection cung cấp thêm các method:

append($attributes)

Chỉ định thuộc tính cần append cho mỗi model:

$users->append('team');

$users->append(['team', 'is_admin']);

contains($key, $operator = null, $value = null)

Kiểm tra model instance có trong collection hay không. Nhận khóa chính hoặc model instance:

$users->contains(1);

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

diff($items)

Trả về tất cả model không có trong collection cho trước:

use App\Models\User;

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

except($keys)

Trả về tất cả model không có khóa chính trong mảng cho trước:

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

find($key)

Tìm model theo khóa chính:

$users = User::all();

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

findOrFail($key)

Tìm model theo khóa chính hoặc throw ModelNotFoundException:

$users = User::all();

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

fresh($with = [])

Truy vấn lại dữ liệu mới từ database. Có thể eager load relationship:

$users = $users->fresh();

$users = $users->fresh('comments');

intersect($items)

Trả về model có mặt trong cả hai collection:

use App\Models\User;

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

load($relations)

Eager load relationship cho tất cả model:

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

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

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

loadMissing($relations)

Eager load relationship nếu chưa được load:

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

modelKeys()

Trả về mảng khóa chính của tất cả model:

$ids = $users->modelKeys();

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

makeVisible($attributes)

Hiện thuộc tính "hidden" trên mỗi model:

$users = $users->makeVisible(['address', 'phone_number']);

makeHidden($attributes)

Ẩn thuộc tính "visible" trên mỗi model:

$users = $users->makeHidden(['address', 'phone_number']);

only($keys)

Trả về model có khóa chính trong mảng cho trước:

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

partition($callback)

Chia collection thành 2 phần dựa trên callback:

[$activeUsers, $inactiveUsers] = $users->partition(function (User $user) {
    return $user->active;
});

setVisible($attributes)

Tạm thời ghi đè danh sách thuộc tính "visible":

$users = $users->setVisible(['id', 'name']);

setHidden($attributes)

Tạm thời ghi đè danh sách thuộc tính "hidden":

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

toQuery()

Trả về Eloquent query builder chứa điều kiện whereIn trên khóa chính:

use App\Models\User;

$users = User::where('status', 'VIP')->get();

$users->toQuery()->update([
    'status' => 'Inactive',
]);

unique($key = null, $strict = false)

Trả về model duy nhất trong collection. Loại bỏ model trùng lặp theo khóa chính:

$users = $users->unique();

Custom Collections

Nếu muốn sử dụng Collection class tùy chỉnh, thêm attribute 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
{
    // ...
}

Hoặc định nghĩa method newCollection:

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Tạo Eloquent Collection instance mới.
     *
     * @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;
    }
}

Sau khi định nghĩa, bạn sẽ nhận được instance custom collection mỗi khi Eloquent trả về Illuminate\Database\Eloquent\Collection.