修改器 · Laravel 5.4 完全開發手冊

* * * * * [TOC] ## 簡介訪問器和修改器可以讓你修改 Eloquent 模型中的屬性或者設置它們的值，例如，你可能想要使用?[Laravel 加密器](https://laravel-china.org/docs/laravel/5.4/encryption)?來加密一個被保存在數據庫中的值，當你從 Eloquent 模型訪問該屬性時該值將被自動解密。除了自定義訪問器和修改器之外，Eloquent 也會自動將日期字段類型轉換成?[Carbon](https://github.com/briannesbitt/Carbon)?實例或將?[文本字段類型轉換成 JSON](https://laravel-china.org/docs/laravel/5.4/eloquent-mutators/1267#attribute-casting)。 ## 訪問器 & 修改器 ### 定義一個訪問器若要定義一個訪問器，則須在你的模型上創建一個?`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; ~~~ ### 定義一個修改器若要定義一個修改器，則須在模型上定義一個?`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 = Carbon::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 例如，`is_admin`?屬性以整數（`0`?或?`1`）被保存在我們的數據庫中，讓我們來把它轉換為布爾值： ~~~ <?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`?或?`TEXT`?字段類型，其包含了被序列化的 JSON，且對該屬性添加了?`array`?類型轉換。當你在 Eloquent 模型上訪問該屬性時，它將會被自動反序列化成一個 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(); ~~~