Laravel (5.7) Красноречивая сериализация

Вступление

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

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

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

Если вы хотите преобразовать модель и связи модели в массив, вам нужно будет использовать метод toArray. Это рекурсивный метод, поэтому все атрибуты и отношения (включая отношения отношений) преобразуются в массивы:

$user = App\User::with('roles')->first();
return $user->toArray();

если вы хотите преобразовать только атрибуты модели в массив, вы должны использовать метод attributeToArray:

$user = App\User::first();
return $user->attributesToArray();

Вы также можете конвертировать целые коллекции моделей в массивы:

$users = App\User::all();
return $users->toArray();

Сериализация в JSON

Если вы хотите преобразовать модель в JSON, вы должны использовать метод toJson. Как и toArray, метод toJson также рекурсивный, поэтому все атрибуты и все отношения будут преобразованы в JSON. Вы также можете указать параметры кодировки JSON, поддерживаемые PHP:

$user = App\User::find(1);
return $user->toJson();
return $user->toJson(JSON_PRETTY_PRINT);

Кроме того, вы можете привести модель или коллекцию к строке, это автоматически вызовет метод toJson для модели или коллекции:

$user = App\User::find(1);
return (string) $user;

Поскольку модели и коллекции преобразуются в JSON, когда они преобразуются в строку, вы можете возвращать объекты Eloquent непосредственно из контроллеров или маршрутов вашего приложения:

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

Отношения

Всякий раз, когда модель Eloquent преобразуется в JSON, ее загруженные отношения автоматически включаются в качестве атрибутов в объект JSON. Хотя методы отношений Eloquent определены с использованием «верблюжьего случая», атрибутом JSON отношения будет «случай змеи».

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

Есть моменты, когда вы хотите ограничить атрибуты, например пароли, которые будут включены в массив вашей модели или представление JSON. Чтобы достичь этого, вы должны добавить $ скрытое свойство к вашей модели:

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

Кроме того, вы можете использовать свойство visible для определения белого списка атрибутов, которые должны быть включены в массив вашей модели и представление JSON. Любые другие атрибуты будут скрыты при преобразовании модели в массив или JSON:

<?php
namespace App;
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'];
}

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

Если вы хотите сделать некоторые типично скрытые атрибуты видимыми в данном экземпляре модели, вы можете использовать метод makeViBsible. Метод makeVBisible вернет экземпляр модели для удобного сцепления методов:

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

Аналогично, если вы хотите сделать некоторые типично видимые атрибуты скрытыми в данном экземпляре модели, вы можете использовать метод makeHidden.

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

Добавление значений в JSON

Иногда, когда вы приводите модели к массиву или JSON, вы можете решить добавить атрибуты, у которых нет соответствующего столбца в вашей базе данных. Чтобы сделать это, вы должны сначала определить метод доступа для значения:

<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
    /**
     * Get the user's administrator flag.
     *
     * @return bool
     */
    public function getIsAdminAttribute()
    {
        return $this->attributes['admin'] =='yes';
    }
}

После того, как вы создадите метод доступа, следующая вещь - добавить имя атрибута к свойству добавления в модели. Однако обратите внимание, что на имена атрибутов обычно ссылаются в «случае змеи», даже если вы определяете метод доступа, используя «случай верблюда»:

<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
    /**
     * The accessors to append to the array form of the model.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

После добавления атрибута в список добавлений он включается как в массив модели, так и в представления JSON. Атрибуты в массиве appends также учитывают видимые и скрытые параметры, настроенные в модели.

Добавление во время выполнения

Вы можете указать одному экземпляру модели добавлять атрибуты, используя метод добавления. Или вы можете использовать метод setAppends, чтобы переопределить весь массив добавленных свойств для данного экземпляра модели:

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

Дата сериализации

Настройка формата даты для атрибута

Вы можете настроить формат сериализации отдельных атрибутов даты Eloquent, указав формат даты в объявлении приведения:

protected $casts = [
    'birthday' => 'date:Y-m-d',
    'joined_at' => 'datetime:Y-m-d H:00',
];

Глобальная настройка через Carbon

Laravel расширяет библиотеку дат Carbon, чтобы обеспечить удобную настройку формата сериализации JSON в Carbon. Если вы хотите настроить сериализацию всех дат углерода в вашем приложении, вам следует использовать метод Carbon :: serializeUsing. Метод serializeUsing примет Closure, который возвращает строковое представление даты для сериализации JSON:

<?php
namespace App\Providers;
use Illuminate\Support\Carbon;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
    /**
     * Register the bindings in the container.
     *
     * @return void
     */
    public function register()
    {
        //
    }
    /**
     * Bootstraps any application services.
     *
     * @return void
     */
    public function boot()
    {
        Carbon::serializeUsing(function ($carbon) {
            return $carbon->format('U');
        });
    }
}