Eloquent 시리얼라이제이션

Eloquent 모델을 JSON·배열로 변환하는 방법, 속성의 표시·비표시 제어, 추가 속성 설정, 날짜 포맷 커스터마이징을 설명합니다.

​

소개

Laravel에서 API를 구축할 때 모델과 그 관계를 배열이나 JSON으로 변환해야 하는 경우가 자주 있습니다. Eloquent에는 이러한 변환을 수행하기 위한 편리한 메서드와, 시리얼라이즈된 모델 표현에 어떤 속성을 포함할지를 제어하는 기능이 포함되어 있습니다.

Eloquent 모델과 컬렉션의 보다 견고한 JSON 시리얼라이제이션 방법에 대해서는 Eloquent API 리소스 문서를 참조해 주세요.

​

모델과 배열

​

배열로의 시리얼라이제이션

모델과 로드된 관계를 배열로 변환하려면 toArray 메서드를 사용합니다. 이 메서드는 재귀적으로 동작하며 모든 속성과 모든 관계(관계의 관계까지 포함)가 배열로 변환됩니다.

use App\Models\User;

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

return $user->toArray();

attributesToArray 메서드를 사용하면 관계를 제외한 모델의 속성만 배열로 변환할 수 있습니다.

$user = User::first();

return $user->attributesToArray();

모델의 컬렉션 전체를 배열로 변환하려면 컬렉션 인스턴스의 toArray 메서드를 호출합니다.

$users = User::all();

return $users->toArray();

​

JSON으로의 시리얼라이제이션

모델을 JSON으로 변환하려면 toJson 메서드를 사용합니다. toArray와 마찬가지로 toJson 메서드도 재귀적이므로 모든 속성과 관계가 JSON으로 변환됩니다. PHP가 지원하는 JSON 인코딩 옵션을 지정할 수도 있습니다.

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

모델이나 컬렉션을 문자열로 캐스팅할 수도 있으며, 그 경우 모델이나 컬렉션의 toJson 메서드가 자동으로 호출됩니다.

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

모델과 컬렉션은 문자열로 캐스팅되면 JSON으로 변환되므로, 애플리케이션의 라우트나 컨트롤러에서 Eloquent 객체를 직접 반환할 수 있습니다. Laravel은 라우트나 컨트롤러에서 반환되는 Eloquent 모델과 컬렉션을 자동으로 JSON으로 시리얼라이즈합니다.

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

​

관계

Eloquent 모델이 JSON으로 변환될 때, 로드된 관계는 JSON 객체의 속성으로 자동으로 포함됩니다. 또한 Eloquent의 관계 메서드는 “카멜케이스” 메서드명으로 정의되지만, 관계의 JSON 속성은 “스네이크케이스”가 됩니다.

​

속성 표시 제어

​

속성 비표시

모델의 배열이나 JSON 표현에 포함되는 비밀번호 같은 속성을 제한하고 싶은 경우가 있습니다. 이를 위해서는 모델에 Hidden 애트리뷰트를 사용합니다. Hidden 애트리뷰트에 나열된 속성은 모델의 시리얼라이즈된 표현에 포함되지 않습니다.

<?php

namespace App\Models;

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

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

관계를 비표시로 하려면 Eloquent 모델의 Hidden 애트리뷰트에 관계의 메서드명을 추가합니다.

​

속성 공개

Visible 애트리뷰트를 사용해 모델의 배열 및 JSON 표현에 포함되어야 할 속성의 “허용 목록”을 정의할 수도 있습니다. Visible 애트리뷰트에 존재하지 않는 모든 속성은 모델이 배열이나 JSON으로 변환될 때 비표시가 됩니다.

<?php

namespace App\Models;

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

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

​

속성의 일시적 표시·비표시

일반적으로 비표시로 되어 있는 속성을 특정 모델 인스턴스에서 표시하려면 makeVisible 또는 mergeVisible 메서드를 사용합니다. makeVisible 메서드는 모델 인스턴스를 반환합니다.

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

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

반대로 일반적으로 표시되는 속성을 비표시로 하려면 makeHidden 또는 mergeHidden 메서드를 사용합니다.

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

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

표시나 비표시 속성을 모두 일시적으로 오버라이드하려면 setVisible 및 setHidden 메서드를 각각 사용합니다.

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

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

​

추가 속성

모델을 배열이나 JSON으로 변환할 때, 데이터베이스에 대응하는 컬럼을 가지지 않는 속성을 추가하고 싶은 경우가 있습니다. 이를 위해서는 먼저 값의 액세서를 정의합니다.

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * 사용자가 관리자인지 판정한다.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

액세서를 모델의 배열 및 JSON 표현에 항상 추가하려면 모델에 Appends 애트리뷰트를 사용합니다. 액세서의 PHP 메서드는 “카멜케이스”로 정의되지만, 속성명은 일반적으로 “스네이크케이스”로 시리얼라이즈 표현을 사용합니다.

<?php

namespace App\Models;

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

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

속성이 appends 리스트에 추가되면 모델의 배열과 JSON 표현 양쪽에 포함됩니다. appends 배열의 속성도 모델에 설정된 visible과 hidden 설정을 존중합니다.

​

실행 시 추가

실행 시 append 또는 mergeAppends 메서드를 사용해 모델 인스턴스에 추가 속성을 추가하도록 지시할 수 있습니다. 또한 setAppends 메서드를 사용해 특정 모델 인스턴스의 추가 프로퍼티 배열 전체를 오버라이드할 수 있습니다.

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

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

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

추가된 모든 프로퍼티를 모델에서 제거하려면 withoutAppends 메서드를 사용합니다.

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

​

날짜 시리얼라이제이션

​

기본 날짜 포맷 커스터마이징

serializeDate 메서드를 오버라이드함으로써 기본 시리얼라이제이션 포맷을 커스터마이징할 수 있습니다. 이 메서드는 데이터베이스로의 저장을 위한 날짜 포맷에는 영향을 주지 않습니다.

/**
 * 배열·JSON 시리얼라이제이션을 위해 날짜를 준비한다.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

​

속성별 날짜 포맷 커스터마이징

모델의 캐스트 선언에서 날짜 포맷을 지정함으로써 개별 Eloquent 날짜 속성의 시리얼라이제이션 포맷을 커스터마이징할 수 있습니다.

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