Серіалізація — Laravel

Створюючи API на Laravel, вам часто потрібно перетворювати моделі та звʼязки на масиви або JSON. Eloquent містить зручні методи для таких перетворень, а також для керування тим, які атрибути потрапляють у серіалізоване представлення ваших моделей.

Примітка Про ще надійніший спосіб серіалізації моделей і колекцій Eloquent у JSON читайте в документації про ресурси API 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\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

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

Примітка Щоб приховати звʼязки, додайте імʼя методу звʼязку до атрибута Hidden вашої моделі Eloquent.

Як альтернативу, ви можете використати атрибут 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

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

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Determine if the user is an administrator.
     */
    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\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. Цей метод не впливає на те, як ваші дати форматуються для зберігання в базі даних:

/**
 * Prepare a date for array / JSON serialization.
 */
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-00',
    ];
}