Eloquent: Serialization

Giới thiệu (Introduction)

Khi xây dựng API với Laravel, bạn thường cần chuyển model và relationships thành mảng hoặc JSON. Eloquent cung cấp các method tiện lợi cho việc này, cùng khả năng kiểm soát thuộc tính nào được bao gồm trong kết quả serialized.

GỢI Ý

Để kiểm soát JSON serialization mạnh hơn, xem Eloquent API Resources.

Serialize Model và Collections

Serialize thành mảng (Serializing to Arrays)

Sử dụng method toArray để chuyển model và relationships thành mảng. Method này hoạt động đệ quy — tất cả thuộc tính và relation (bao gồm relation lồng nhau) đều được chuyển:

use App\Models\User;

$user = User::with('roles')->first();

return $user->toArray();

Chỉ chuyển thuộc tính (không bao gồm relationship):

$user = User::first();

return $user->attributesToArray();

Chuyển toàn bộ collection:

$users = User::all();

return $users->toArray();

Serialize thành JSON (Serializing to JSON)

Sử dụng toJson. Tương tự toArray nhưng trả về chuỗi JSON:

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

Hoặc cast thành string:

return (string) User::find(1);

Vì model/collection tự động chuyển thành JSON khi cast sang string, bạn có thể return trực tiếp từ route:

Route::get('/users', function () {
    return User::all();
});

Relationships

Khi model chuyển thành JSON, relationship đã load sẽ tự động được bao gồm. Relationship method tên "camelCase" sẽ thành "snake_case" trong JSON.

Ẩn thuộc tính khỏi JSON (Hiding Attributes From JSON)

Sử dụng attribute Hidden để loại bỏ thuộc tính (ví dụ: password):

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

#[Hidden(['password'])]
class User extends Model
{
    // ...
}

Để chỉ hiển thị các thuộc tính cụ thể (allow list), sử dụng attribute Visible:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;

#[Visible(['first_name', 'last_name'])]
class User extends Model
{
    // ...
}

Thay đổi tạm thời Visibility

Hiện thuộc tính bị ẩn:

return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();

Ẩn thuộc tính đang hiện:

return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();

Ghi đè toàn bộ:

return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'phone'])->toArray();

Thêm giá trị vào JSON (Appending Values to JSON)

Đôi khi bạn muốn thêm thuộc tính không có trong database column. Đầu tiên, định nghĩa accessor:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Kiểm tra user có phải admin không.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

Sử dụng attribute Appends để luôn bao gồm trong kết quả serialized (tên ở dạng snake_case):

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}

Append tại Runtime

return $user->append('is_admin')->toArray();

return $user->mergeAppends(['is_admin', 'status'])->toArray();

return $user->setAppends(['is_admin'])->toArray();

Loại bỏ tất cả appended properties:

return $user->withoutAppends()->toArray();

Serialize Date

Mặc định, Eloquent serialize date thành chuỗi UTC ISO-8601 (YYYY-MM-DDTHH:MM:SS.uuuuuuZ).

Tùy chỉnh format cho tất cả date:

protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

Tùy chỉnh format cho từng thuộc tính:

protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}