Laravel에서 API를 구축할 때 모델과 그 관계를 배열이나 JSON으로 변환해야 하는 경우가 자주 있습니다.
Eloquent에는 이러한 변환을 수행하기 위한 편리한 메서드와, 시리얼라이즈된 모델 표현에 어떤 속성을 포함할지를 제어하는 기능이 포함되어 있습니다.
모델과 배열
배열로의 시리얼라이제이션
모델과 로드된 관계를 배열로 변환하려면 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);
Route::get('/users', function () {
return User::all();
});
속성 표시 제어
속성 비표시
모델의 배열이나 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',
);
}
}
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',
];
}
