Введение
Читатели и преобразователи позволяют вам форматировать значения атрибутов Eloquent при их чтении или записи в экземпляры моделей. Например, вы хотите использовать Laravel-шифратор, чтобы зашифровать значение, пока оно хранится в базе, и затем автоматически расшифровать атрибут, когда вы обращаетесь к нему в модели Eloquent.
В дополнение к обычным читателям и преобразователям Eloquent также автоматически преобразует поля с датами в экземпляры Carbon или даже преобразует текстовые поля в JSON.
Читатели и преобразователи
Определение читателя
Чтобы определить читателя, создайте метод PHPgetFooAttribute()
в вашей модели, где Foo — отформатированное в соответствии со стилем «studly» название столбца, к которому вы хотите иметь доступ. В данном примере мы определим читателя для атрибута first_name. Читатель будет автоматически вызван Eloquent при попытке получить значение атрибута 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);
}
}
Как видите, первоначальное значение столбца передается читателю, позволяя вам управлять значением и возвращать его. Чтобы получить доступ к значению читателя, вы можете просто обратиться к атрибуту first_name экземпляра модели:
$user = App\User::find(1);
$firstName = $user->first_name;
Определение преобразователя
Чтобы определить преобразователь, определите метод PHPsetFooAttribute()
для своей модели, где PHPFoo
— отформатированное в соответствии со стилем «studly» название столбца, к которому вы хотите иметь доступ. И снова давайте определим преобразователь для атрибута first_name. Этот преобразователь будет автоматически вызван, когда мы попытаемся установить значение атрибута 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);
}
}
Преобразователь получает значение, которое устанавливается в атрибуте, позволяя вам управлять значением и изменять его во внутреннем свойстве PHP$attributes
модели Eloquent. Так, например, если мы пытаемся установить атрибут first_name в значение Sally:
$user = App\User::find(1);
$user->first_name = 'Sally';
В этом примере функция PHPsetFirstNameAttribute()
будет вызвана со значением Sally. Преобразователь применит функцию PHPstrtolower()
к имени и установит его результирующее значение во внутреннем массиве PHP$attributes
.
Преобразователи дат
По умолчанию Eloquent преобразует столбцы created_at и updated_at в экземпляры Carbon, которые наследуют PHP-класс DateTime и предоставляют ряд полезных методов. Вы можете сами настроить, какие поля автоматически будут преобразовываться, и даже полностью отключить их преобразование, изменив свойство PHP$dates
вашей модели:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* Атрибуты, которые должны быть преобразованы к датам.
*
* @var array
*/
protected $dates = [
'created_at',
'updated_at',
'deleted_at'
];
}
Когда столбец является датой, вы можете установить его значение в формат времени UNIX, в строку даты (Y-m-d), в строку даты-времени, и конечно в экземпляр DateTime/Carbon, и значение даты будет автоматически правильно сохранено в вашей базе данных:
$user = App\User::find(1);
$user->deleted_at = Carbon::now();
$user->save();
Как было отмечено выше, полученные атрибуты, которые перечислены в вашем свойстве PHP$dates
, будут автоматически преобразованы к экземпляру Carbon, позволяя вам использовать любой из методов Carbon для ваших атрибутов:
$user = App\User::find(1);
return $user->deleted_at->getTimestamp();
По умолчанию метки времени отформатированы как 'Y-m-d H:i:s'. Если вам нужно настроить формат метки времени, установите значение PHP$dateFormat
в своей модели. Это свойство определяет, как атрибуты даты хранятся в базе данных, а также их формат, когда модель преобразована в массив или JSON:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class Flight extends Model
{
/**
* Формат хранения столбцов с датами модели.
*
* @var string
*/
protected $dateFormat = 'U';
}
Преобразование атрибутов
Свойство PHP$casts
в вашей модели предоставляет удобный метод преобразования атрибутов к общим типам данных. Свойство PHP$casts
должно быть массивом, где ключ — название преобразуемого атрибута, а значение — тип, в который вы хотите преобразовать столбец. Поддерживаемые типы для преобразования: PHPinteger
, PHPreal
, PHPfloat
, PHPdouble
, PHPstring
, PHPboolean
, PHPobject
, PHParray
, PHPcollection
, PHPdate
, PHPdatetime
и с версии 5.2 PHPtimestamp
.
Например, давайте привяжем атрибут is_admin, который сохранен в нашей базе данных как PHPinteger
(PHP0
или PHP1'
к значению PHPboolean
:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* Атрибуты, которые должны быть преобразованы к базовым типам.
*
* @var array
*/
protected $casts = [
'is_admin' => 'boolean',
];
}
Теперь атрибут is_admin будет всегда преобразовываться в boolean, когда вы обращаетесь к нему, даже если само значение хранится в базе данных как PHPinteger
:
$user = App\User::find(1);
if ($user->is_admin) {
//
}
Преобразование в массив и JSON
Тип PHParray
особенно полезен для преобразования при работе со столбцами, которые хранятся в формате JSON. Например, если у вашей базы данных есть тип поля PHPTEXT
или PHPJSON
(начиная с версии 5.3), который содержит JSON данные, добавление преобразования в PHParray
к этому атрибуту автоматически десериализует атрибут в PHP массив, во время доступа к нему из вашей модели Eloquent:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* Атрибуты, которые должны быть преобразованы к базовым типам.
*
* @var array
*/
protected $casts = [
'options' => 'array',
];
}
После определения преобразования вы можете обратиться к атрибуту options, и он будет автоматически десериализован из JSON в PHP массив. Когда вы зададите значение атрибута options, данный массив будет автоматически преобразован обратно в JSON для хранения:
$user = App\User::find(1);
$options = $user->options;
$options['key'] = 'value';
$user->options = $options;
$user->save();