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

Статистика: Символов — 4 700/3 976 без пробелов (2 551/2 182 без кода):, слов — 370
Разметка: Wiki
{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01}}

== Введение ==

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

== Сериализация моделей и коллекций ==
=== Сериализация в массивы ===
Для преобразования модели и её загруженных ((/docs/v5/eloquent-relationships отношений)) в массив надо использовать метод %%toArray()%%. Этот метод рекурсивный, поэтому все атрибуты и все отношения (включая отношения отношений) будут конвертированы в массивы:
%%
$user = App\User::with('roles')->first();

return $user->toArray();
%%

Вы можете также преобразовывать целые ((/docs/v5/eloquent-collections коллекции)) моделей в массивы:
%%
$users = App\User::all();

return $users->toArray();
%%

=== Сериализация в JSON ===
Для преобразования модели в JSON вам надо использовать метод %%toJson()%%. Метод %%toJson()%% рекурсивный, поэтому все атрибуты и отношения будут преобразованы в JSON:
%%
$user = App\User::find(1);

return $user->toJson();
%%

В качестве альтернативы, вы можете преобразовать модель или коллекцию в строку, что автоматически вызовет метод %%toJson()%% на модели или коллекции:
%%
$user = App\User::find(1);

return (string) $user;
%%

Поскольку модели и коллекции конвертируются в JSON при их преобразовании в строку, вы можете возвращать объекты Eloquent напрямую из ваших маршрутов или контроллеров:
%%
Route::get('users', function () {
  return App\User::all();
});
%%

== Скрытие атрибутов от JSON ==
Иногда вам может быть нужно ограничить список атрибутов, включённых в преобразованный массив или JSON-строку — например, скрыть пароли. Для этого добавьте в модель свойство %%$hidden%%:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
    * Атрибуты, которые должны быть невидимы для массива.
    *
    * @var array
    */
  protected $hidden = ['password'];
}
%%

.(alert)
При скрытии отношений используйте имя метода отношения, а не имя его динамического свойства.

Вы также можете использовать свойство %%(t)visible%%, чтобы определить белый список атрибутов, которые должны быть включены в ваш массив модели и преобразованный JSON. Все остальные атрибуты будут скрыты при конвертировании модели в массив или JSON:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
   * Атрибуты, которые должны быть видны в массиве.
   *
   * @var array
   */
  protected $visible = ['first_name', 'last_name'];
}
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
**Временное изменение видимости атрибута**

Используйте метод %%makeVisible()%%, чтобы сделать обычно скрытые атрибуты видимыми в данном экземпляре модели. Метод %%makeVisible()%% возвращает экземпляр модели для удобной сцепки методов:
 ~%%
return $user->makeVisible('attribute')->toArray();
~%%

А также, используйте метод %%makeHidden()%%, чтобы сделать обычно видимые атрибуты скрытыми в данном экземпляре модели.
~%%
return $user->makeHidden('attribute')->toArray();
~%%
%%

== Добавление значений в JSON ==
Иногда, при конвертировании моделей в массив или JSON, вам может понадобиться добавить атрибуты, для которых нет соответствующих столбцов в вашей БД. Для этого просто определите для него ((/docs/v5/eloquent-mutators читателя)):
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
   * Получить флаг администратора для пользователя.
   *
   * @return bool
   */
  public function getIsAdminAttribute()
  {
    return $this->attributes['admin'] == 'yes';
  }
}
%%

После создания читателя, добавьте имя атрибута в свойство модели %%(t)appends%%. Обратите внимание на то, что имена атрибутов обычно указываются в стиле "snake case", хотя читатель определяется в стиле "camel case":
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
   * Читатель, добавленный к форме массива модели.
   *
   * @var array
   */
  protected $appends = ['is_admin'];
}
%%

Когда атрибут добавлен в список %%(t)appends%%, он будет включён в оба представления - и в массив модели, и в JSON. Атрибуты в массиве %%(t)appends%% соответствуют настройкам модели %%(t)visible%% и %%(t)hidden%%.