7.6. Eloquent: Сериализация

• 1. Введение
• 2. Сериализация моделей и коллекций
  • 2.1. Сериализация в массивы
  • 2.2. Сериализация в JSON
• 3. Скрытие атрибутов в JSON
• 4. Добавление значений в JSON
• Date Serialization

1. Введение

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

2. Сериализация моделей и коллекций

2.1. Сериализация в массивы

Чтобы преобразовать модель и её загруженные отношения в массив, следует использовать метод 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();

2.2. Сериализация в 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();
});

2.2.1. Отношения

Когда модель Eloquent преобразуется в JSON, её загруженные отношения автоматически будут включены в качестве атрибутов в JSON-объект. Кроме того, хотя методы отношений Eloquent определяются с использованием имен методов в "camel case", атрибут отношения в JSON будет в "snake case".

3. Скрытие атрибутов в JSON

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

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array<string>
     */
    protected $hidden = ['password'];
}

Вместо этого вы можете использовать свойство visible для определения "разрешённого списка" атрибутов, которые должны быть включены в массив и JSON-представление вашей модели. Все атрибуты, не присутствующие в массиве $visible, будут скрыты при преобразовании модели в массив или JSON:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The attributes that should be visible in arrays.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

3.0.1. Временное изменение видимости атрибутов

Если вы хотите временно сделать некоторые обычно скрытые атрибуты видимыми для данного экземпляра модели, вы можете использовать метод 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();

4. Добавление значений в 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\Model;
 
class User extends Model
{
    /**
     * The accessors to append to the model's array form.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}