Преобразователи

Статистика: Символов — 7 978/6 741 без пробелов (4 065/3 491 без кода):, слов — 575
Разметка: 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}}

== Введение ==
Читатели и преобразователи позволяют вам форматировать значения атрибутов Eloquent при их чтении или записи в экземпляры моделей. Например, вы хотите использовать ((/docs/v5/encryption Laravel-шифратор)), чтобы зашифровать значение, пока оно хранится в базе, и затем автоматически расшифровать атрибут, когда вы обращаетесь к нему в модели Eloquent.

В дополнение к обычным читателям и преобразователям Eloquent также автоматически преобразует поля с датами в экземпляры ((https://github.com/briannesbitt/Carbon Carbon)) или даже ((#преобразование_атрибутов преобразует текстовые поля в JSON)).

== Читатели и преобразователи ==
=== Определение читателя ===
Чтобы определить читателя, создайте метод %%getFooAttribute()%% в вашей модели, где %%(t)Foo%% - отформатированное в соответствии со стилем "studly" название столбца, к которому вы хотите иметь доступ. В данном примере мы определим читателя для атрибута %%(t)first_name%%. Читатель будет автоматически вызван Eloquent при попытке получить значение атрибута %%(t)first_name%%:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
    * Получить имя пользователя.
    *
    * @param  string  $value
    * @return string
    */
  public function getFirstNameAttribute($value)
  {
    return ucfirst($value);
  }
}
%%

Как видите, первоначальное значение столбца передается читателю, позволяя вам управлять значением и возвращать его. Чтобы получить доступ к значению читателя, вы можете просто обратиться к атрибуту %%(t)first_name%% экземпляра модели:
%%
$user = App\User::find(1);

$firstName = $user->first_name;
%%

=== Определение преобразователя ===
Чтобы определить преобразователь, определите метод %%setFooAttribute()%% для своей модели, где %%Foo%% - отформатированное в соответствии со стилем "studly" название столбца, к которому вы хотите иметь доступ. И снова давайте определим преобразователь для атрибута %%(t)first_name%%. Этот преобразователь будет автоматически вызван, когда мы попытаемся установить значение атрибута %%(t)first_name%% в модели:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
    * Установить имя пользователя.
    *
    * @param  string  $value
    * @return void
    * //для версии 5.2 и ранее:
    * //@return string
    */
  public function setFirstNameAttribute($value)
  {
    $this->attributes['first_name'] = strtolower($value);
  }
}
%%

Преобразователь получает значение, которое устанавливается в атрибуте, позволяя вам управлять значением и изменять его во внутреннем свойстве %%$attributes%% модели Eloquent. Так, например, если мы пытаемся установить атрибут %%(t)first_name%% в значение %%(t)Sally%%:
%%
$user = App\User::find(1);

$user->first_name = 'Sally';
%%

В этом примере функция %%setFirstNameAttribute()%% будет вызвана со значением %%(t)Sally%%. Преобразователь применит функцию %%strtolower()%% к имени и установит его результирующее значение во внутреннем массиве %%$attributes%%.

== Преобразователи дат ==

По умолчанию Eloquent преобразует столбцы %%(t)created_at%% и %%(t)updated_at%% в экземпляры ((https://github.com/briannesbitt/Carbon Carbon)), которые наследуют PHP-класс %%(t)DateTime%% и предоставляют ряд полезных методов. Вы можете сами настроить, какие поля автоматически будут преобразовываться, и даже полностью отключить их преобразование, изменив свойство %%$dates%% вашей модели:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
    * Атрибуты, которые должны быть преобразованы к датам.
    *
    * @var array
    */
   protected $dates = [
     'created_at',
     'updated_at',
     'deleted_at'
   ];
}
%%

Когда столбец является датой, вы можете установить его значение в формат времени UNIX, в строку даты (%%(t)Y-m-d%%), в строку даты-времени, и конечно в экземпляр %%(t)DateTime%%/%%(t)Carbon%%, и значение даты будет автоматически правильно сохранено в вашей базе данных:
%%
$user = App\User::find(1);

$user->deleted_at = Carbon::now();

$user->save();
%%

Как было отмечено выше, полученные атрибуты, которые перечислены в вашем свойстве %%$dates%%, будут автоматически преобразованы к экземпляру ((https://github.com/briannesbitt/Carbon Carbon)), позволяя вам использовать любой из методов Carbon для ваших атрибутов:
%%
$user = App\User::find(1);

return $user->deleted_at->getTimestamp();
%%

**Форматы дат**

По умолчанию метки времени отформатированы как %%(t)'Y-m-d H:i:s'%%. Если вам нужно настроить формат метки времени, установите значение %%$dateFormat%% в своей модели. Это свойство определяет, как атрибуты даты хранятся в базе данных, а также их формат, когда модель преобразована в массив или JSON:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
  /**
    * Формат хранения столбцов с датами модели.
    *
    * @var string
    */
  protected $dateFormat = 'U';
}
%%

== ((#преобразование_атрибутов)) Преобразование атрибутов ==
Свойство %%$casts%% в вашей модели предоставляет удобный метод преобразования атрибутов к общим типам данных. Свойство %%$casts%% должно быть массивом, где ключ - название преобразуемого атрибута, а значение - тип, в который вы хотите преобразовать столбец. Поддерживаемые типы для преобразования: %%integer%%, %%real%%, %%float%%, %%double%%, %%string%%, %%boolean%%, %%object%%, %%array%%, %%collection%%, %%date%%, %%datetime%% и с версии 5.2 %%timestamp%%.

Например, давайте привяжем атрибут %%(t)is_admin%%, который сохранен в нашей базе данных как %%integer%% (%%0%% или %%1'%% к значению %%boolean%%:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  /**
    * Атрибуты, которые должны быть преобразованы к базовым типам.
    *
    * @var array
    */
  protected $casts = [
    'is_admin' => 'boolean',
  ];
}
%%

Теперь атрибут %%(t)is_admin%% будет всегда преобразовываться в boolean, когда вы обращаетесь к нему, даже если само значение хранится в базе данных как %%integer%%:
%%
$user = App\User::find(1);

if ($user->is_admin) {
  //
}
%%

=== Преобразование в массив и JSON ===
Тип %%array%% особенно полезен для преобразования при работе со столбцами, которые хранятся в формате JSON. Например, если у вашей базы данных есть тип поля %%TEXT%% или %%JSON%% (начиная с версии 5.3), который содержит JSON данные, добавление преобразования в %%array%% к этому атрибуту автоматически десериализует атрибут в PHP массив, во время доступа к нему из вашей модели Eloquent:
%%
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

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

После определения преобразования вы можете обратиться к атрибуту %%(t)options%%, и он будет автоматически десериализован из JSON в PHP массив. Когда вы зададите значение атрибута %%(t)options%%, данный массив будет автоматически преобразован обратно в JSON для хранения:
%%
$user = App\User::find(1);

$options = $user->options;

$options['key'] = 'value';

$user->options = $options;

$user->save();
%%