Eloquent: Серіалізація

• Вступ
• Серіалізація моделей та колекцій
  • Серіалізація в масиви
  • Серіалізація в JSON
• Приховування атрибутів від JSON
• Додавання значень до JSON
• Серіалізація Дати

Вступ

Коли ви створюєте API за допомогою Laravel, вам часто потрібно буде конвертувати ваші моделі та відносини в масиви або 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. Ви також можете вказати будь-які параметри кодування JSON, які підтримуються PHP:

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 визначаються з використанням назв методів у "camel case", атрибут відносин у JSON буде у "snake case".

Приховування атрибутів від JSON

Іноді ви можете захотіти обмежити атрибути, такі як паролі, які включені в масив або JSON-представлення вашої моделі. Для цього додайте властивість $hidden до вашої моделі. Атрибути, які вказані в масиві властивості $hidden, не будуть включені в серіалізоване представлення вашої моделі:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * Атрибути, які слід приховати для серіалізації.
     *
     * @var array<string>
     */
    protected $hidden = ['password'];
}

Альтернативно, ви можете використовувати властивість visible для визначення "дозволеного списку" атрибутів, які повинні бути включені в масив і JSON-представлення вашої моделі. Усі атрибути, які не присутні в масиві $visible, будуть приховані, коли модель буде перетворена в масив або JSON:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * Атрибути, які повинні бути видимі в масивах.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

Тимчасова зміна видимості атрибутів

Якщо ви хочете зробити деякі зазвичай приховані атрибути видимими на даному екземплярі моделі, ви можете використовувати метод makeVisible. Метод makeVisible повертає екземпляр моделі:

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

Так само, якщо ви хочете приховати деякі атрибути, які зазвичай видимі, ви можете використовувати метод makeHidden.

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

Якщо ви бажаєте тимчасово перевизначити всі видимі або приховані атрибути, ви можете використовувати методи setVisible та setHidden відповідно:

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

Додавання значень до JSON

Іноді, при перетворенні моделей у масиви або 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 вашої моделі. Зверніть увагу, що імена атрибутів зазвичай посилаються, використовуючи їх серіалізоване представлення у "snake case", навіть якщо PHP-метод аксесора визначено у "camel case":

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * Аксесори для додавання до масиву моделі.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

Після того як атрибут було додано до списку appends, він буде включений як у масив моделі, так і в JSON-представлення. Атрибути в масиві appends також будуть враховувати налаштування visible та hidden, налаштовані на моделі.

Додавання під час виконання

Під час виконання ви можете вказати екземпляру моделі додати додаткові атрибути, використовуючи метод append. Або ви можете використовувати метод setAppends, щоб перевизначити весь масив доданих властивостей для даного екземпляра моделі:

return $user->append('is_admin')->toArray();
 
return $user->setAppends(['is_admin'])->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',
    ];
}