修改器 · Laravel 5.6 中文文檔

* * * * * [TOC] ## 簡介當你在 Eloquent 模型實例中獲取或設置某些屬性值的時候，訪問器和修改器允許你對 Eloquent 屬性值進行格式化。例如，你可能想要使用?[Laravel 加密器](http://www.hmoore.net/tonyyu/laravel_5_6/786219)?來加密一個即將被保存在數據庫中的值，而從 Eloquent 模型訪問該屬性時自動解密其值。除了自定義訪問器和修改器之外，Eloquent 也會自動將日期字段類型轉換成?[Carbon](https://github.com/briannesbitt/Carbon)?實例或將?[文本字段類型轉換成JSON](http://www.hmoore.net/tonyyu/laravel_5_6/786275#_160)。 ## 訪問器 & 修改器 ### 定義一個訪問器若要定義一個訪問器，則須在你的模型上創建一個?`getFooAttribute`?方法。要訪問的?`Foo`?字段需使用「駝峰式」來命名。在這個例子中，我們將為?`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; ~~~ 當然，你也可以通過已有的屬性，使用訪問器返回新的計算值： ~~~ /** * 獲取用戶姓名。 * * @return string */ public function getFullNameAttribute() { return "{$this->first_name} {$this->last_name}"; } ~~~ ### 定義一個修改器若要定義一個修改器，則須在模型上定義一個?`setFooAttribute`?方法。要訪問的?`Foo`?字段需使用「駝峰式」命名。讓我們再來定義一個?`first_name`?屬性的修改器。當我們嘗試在模型上設置?`first_name`?的值時，該修改器將被自動調用： ~~~ <?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 設定用戶的名字。 * * @param string $value * @return void */ public function setFirstNameAttribute($value) { $this->attributes['first_name'] = strtolower($value); } } ~~~ 修改器會獲取屬性已經被設置的值，允許你操作該值并將其設置到 Eloquent 模型內部的?`$attributes`?屬性上。舉個例子，如果我們嘗試將?`first_name`?屬性的值設置成?`Sally`： ~~~ $user = App\User::find(1); $user->first_name = 'Sally'; ~~~ 在這個例子中，?`setFirstNameAttribute`?方法在調用的時候會接收?`Sally`?這個值作為參數。接著修改器會應用`strtolower`?函數并將處理結果的值設置到內部的?`$attributes`?數組。 ## 日期轉換器默認情況下，Eloquent 會把?`created_at`?和?`updated_at`?字段轉換成?[Carbon](https://github.com/briannesbitt/Carbon)?實例，它繼承了 PHP 原生的?`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 時間戳、日期字符串（`Y-m-d`）、日期時間（?`date-time`?）字符串，當然還有?`DateTime`?或?`Carbon`?實例，并且讓日期值自動正確地保存到你的數據庫中： ~~~ $user = App\User::find(1); $user->deleted_at = now(); $user->save(); ~~~ 就如上面所說的，當獲取到的屬性包含在?`$dates`?屬性中時，都將會自動轉換成?[Carbon](https://github.com/briannesbitt/Carbon)?實例，允許你在屬性上使用任意的?`Carbon`?方法： ~~~ $user = App\User::find(1); return $user->deleted_at->getTimestamp(); ~~~ #### 日期格式默認情況下，時間戳將會以?`'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`?和?`timestamp`。例如，讓我們把以整數 (?`0`?或?`1`?) 形式存儲在數據庫中的?`is_admin`?屬性轉換成布爾值： ~~~ <?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 應該被轉換成原生類型的屬性。 * * @var array */ protected $casts = [ 'is_admin' => 'boolean', ]; } ~~~ 現在當你訪問?`is_admin`?屬性時，雖然保存在數據庫里的的值是一個整數類型，但返回值總是會被轉換成布爾值類型： ~~~ $user = App\User::find(1); if ($user->is_admin) { // } ~~~ ### 數組 & JSON 轉換如果一個字段是以被序列化的 JSON 來存儲在數據庫中，`array`?類型轉換將會非常有用。例如，當你訪問的字段在數據庫里是一個包含了被序列化的 JSON 的?`JSON`?或?`TEXT`?字段類型，而且在 Eloquent 模型上你對該字段添加了?`array`?類型轉換，那么它將會自動反序列化成一個 PHP 數組： ~~~ <?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(); ~~~