修改器 · laravel 5.3 中文文檔

# Eloquent: 修改器 - [簡介](#introduction) - [訪問器 & 修改器](#accessors-and-mutators) - [定義一個訪問器](#defining-an-accessor) - [定義一個修改器](#defining-a-mutator) - [日期轉換器](#date-mutators) - [屬性類型轉換](#attribute-casting) - [數組 & JSON 轉換](#array-and-json-casting) <a name="introduction"></a> ## 簡介訪問器和修改器可以讓你修改 Eloquent 模型中的屬性或者設置它們的值，例如，你可能想要使用 [Laravel 加密器](/docs/{{version}}/encryption)) 來加密一個被保存在數據庫中的值，當你從 Eloquent 模型訪問該屬性時該值將被自動解密。除了自定義訪問器和修改器之外，Eloquent 也會自動將日期字段類型轉換成 [Carbon](https://github.com/briannesbitt/Carbon) 實例或將 [文本字段類型轉換成 JSON](#attribute-casting)。 <a name="accessors-and-mutators"></a> ## 訪問器 & 修改器 <a name="defining-an-accessor"></a> ### 定義一個訪問器若要定義一個訪問器，則須在你的模型上創建一個 `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; <a name="defining-a-mutator"></a> ### 定義一個修改器若要定義一個修改器，則須在模型上定義一個 `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` 數組。 <a name="date-mutators"></a> ## 日期轉換器默認情況下，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'; } <a name="attribute-casting"></a> ## 屬性類型轉換 `$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) { // } <a name="array-and-json-casting"></a> ### 數組 & 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();