修改器 · laravel 5.4

<article><h1>Eloquent: 修改器</h1><ul><li><a href="#introduction">簡介</a></li><li><a href="#accessors-and-mutators">訪問器 & 修改器</a><ul><li><a href="#defining-an-accessor">定義一個訪問器</a></li><li><a href="#defining-a-mutator">定義一個修改器</a></li></ul></li><li><a href="#date-mutators">日期轉換器</a></li><li><a href="#attribute-casting">屬性類型轉換</a><ul><li><a href="#array-and-json-casting">數組 & JSON 轉換</a></li></ul></li></ul><a name="introduction"></a><h2><a href="#introduction">簡介</a></h2>訪問器和修改器可以讓你修改 Eloquent 模型中的屬性或者設置它們的值，例如，你可能想要使用 <a href="/docs/5.4/encryption">Laravel 加密器</a> 來加密一個被保存在數據庫中的值，當你從 Eloquent 模型訪問該屬性時該值將被自動解密。除了自定義訪問器和修改器之外，Eloquent 也會自動將日期字段類型轉換成 <a href="https://github.com/briannesbitt/Carbon">Carbon</a> 實例或將 <a href="#attribute-casting">文本字段類型轉換成 JSON</a>。<a name="accessors-and-mutators"></a><h2><a href="#accessors-and-mutators">訪問器 & 修改器</a></h2><a name="defining-an-accessor"></a><h3>定義一個訪問器</h3>若要定義一個訪問器，則須在你的模型上創建一個 <code class=" language-php">getFooAttribute</code> 方法。要訪問的 <code class=" language-php">Foo</code> 字段需使用「駝峰式」來命名。在這個例子中，我們將為 <code class=" language-php">first_name</code> 屬性定義一個訪問器。當 Eloquent 嘗試獲取 <code class=" language-php">first_name</code> 的值時，將會自動調用此訪問器：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 獲取用戶的名字。 * * @param string $value * @return string */ public function getFirstNameAttribute($value) { return ucfirst($value); } }</code></pre>如你所見，字段的原始值被傳遞到訪問器中，讓你可以編輯修改并返回結果。如果要訪問被修改的值，則可以像這樣來訪問 <code class=" language-php">first_name</code> 屬性：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); $firstName = $user->first_name;</code></pre><a name="defining-a-mutator"></a><h3>定義一個修改器</h3>若要定義一個修改器，則須在模型上定義一個 <code class=" language-php">setFooAttribute</code> 方法。要訪問的 <code class=" language-php">Foo</code> 字段需使用「駝峰式」來命名。讓我們再來定義 <code class=" language-php">first_name</code> 屬性的修改器。當我們嘗試在模型上設置 <code class=" language-php">first_name</code> 的值時，將會自動調用此修改器：<pre class=" language-php"><code class=" language-php"><?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); } }</code></pre>修改器會獲取屬性已經被設置的值，讓你可以操作該值并將其設置到 Eloquent 模型內部的 <code class=" language-php">$attributes</code> 屬性上。舉個例子，如果我們嘗試將 <code class=" language-php">first_name</code> 屬性設置成 <code class=" language-php">Sally</code>：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); $user->first_name = 'Sally';</code></pre>在這個例子中，<code class=" language-php">setFirstNameAttribute</code> 函數將會使用 <code class=" language-php">Sally</code> 作為參數來調用。修改器會對該名字使用 <code class=" language-php">strtolower</code> 函數并將其值設置于內部的 <code class=" language-php">$attributes</code> 數組。<a name="date-mutators"></a><h2><a href="#date-mutators">日期轉換器</a></h2>默認情況下，Eloquent 將會把 <code class=" language-php">created_at</code> 和 <code class=" language-php">updated_at</code> 字段轉換成 <a href="https://github.com/briannesbitt/Carbon">Carbon</a> 實例，它提供了各種各樣的方法，并繼承了 PHP 原生的 DateTime 類。你可以在模型中自定義哪些字段需要被自動修改，或完全禁止修改，可通過重寫模型的 <code class=" language-php">$dates</code> 屬性來實現：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 應被轉換為日期的屬性。 * * @var array */ protected $dates = [ 'created_at', 'updated_at', 'deleted_at' ]; }</code></pre>當某個字段被認為是日期時，你或許想將其數值設置成一個 UNIX 時間戳、日期字符串（<code class=" language-php">Y-m-d</code>）、日期時間（ <code class=" language-php">date-time</code> ）字符串，當然還有 <code class=" language-php">DateTime</code> 或 <code class=" language-php">Carbon</code> 實例，然后日期數值將會被自動保存到數據庫中：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); $user->deleted_at = Carbon::now(); $user->save();</code></pre>如上所述，在 <code class=" language-php">$dates</code> 屬性中列出的所有屬性被獲取到時，都將會自動轉換成 <a href="https://github.com/briannesbitt/Carbon">Carbon</a> 實例，讓你可在屬性上使用任何 <code class=" language-php">Carbon</code> 方法：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); return $user->deleted_at->getTimestamp();</code></pre><h4>時間格式</h4>默認情況下，時間戳將會以 <code class=" language-php">'Y-m-d H:i:s'</code> 格式化。如果你想要自定義自己的時間戳格式，可在模型中設置 <code class=" language-php">$dateFormat</code> 屬性。該屬性定義了時間屬性應如何被保存到數據庫，以及模型應被序列化成一個數組或 JSON 格式：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class Flight extends Model { /** * 模型的數據字段的保存格式。 * * @var string */ protected $dateFormat = 'U'; }</code></pre><a name="attribute-casting"></a><h2><a href="#attribute-casting">屬性類型轉換</a></h2><code class=" language-php">$casts</code> 屬性在模型中提供了將屬性轉換為常見的數據類型的方法。<code class=" language-php">$casts</code> 屬性應是一個數組，且鍵是那些需要被轉換的屬性名稱，值則是代表字段要轉換的類型。支持的轉換的類型有：<ul><li>integer</li><li>real</li><li>float</li><li>double</li><li>string</li><li>boolean</li><li>object</li><li>array</li><li>collection</li><li>date</li><li>datetime</li><li>timestamp</li></ul>例如，<code class=" language-php">is_admin</code> 屬性以整數（<code class=" language-php">0</code> 或 <code class=" language-php">1</code>）被保存在我們的數據庫中，讓我們來把它轉換為布爾值：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 應該被轉換成原生類型的屬性。 * * @var array */ protected $casts = [ 'is_admin' => 'boolean', ]; }</code></pre>現在當你訪問 <code class=" language-php">is_admin</code> 屬性時，它將會被轉換成布爾值，即便保存在數據庫里的值是一個整數：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); if ($user->is_admin) { // }</code></pre><a name="array-and-json-casting"></a><h3>數組 & JSON 轉換</h3>若原本字段保存的是被序列化的 JSON，則 <code class=" language-php">array</code> 類型轉換將會特別有用。例如，在你的數據庫中有一個 <code class=" language-php">JSON</code> 或 <code class=" language-php">TEXT</code> 字段類型，其包含了被序列化的 JSON，且對該屬性添加了 <code class=" language-php">array</code> 類型轉換。當你在 Eloquent 模型上訪問該屬性時，它將會被自動反序列化成一個 PHP 數組：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 應該被轉換成原生類型的屬性。 * * @var array */ protected $casts = [ 'options' => 'array', ]; }</code></pre>一旦類型轉換被定義，則可以訪問 <code class=" language-php">options</code> 屬性，它將會自動把 JSON 反序列化成一個 PHP 數組。當你設置 <code class=" language-php">options</code> 屬性的值時，指定的數組將會被自動序列化成 JSON 以便進行保存：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); $options = $user->options; $options['key'] = 'value'; $user->options = $options; $user->save();</code></pre><h2>譯者署名</h2><table><thead><tr><th>用戶名</th><th>頭像</th><th>職能</th><th>簽名</th></tr></thead><tbody><tr><td><a href="https://laravel-china.org/users/79">@skyverd</a></td><td><img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/79_1427370664.jpeg?imageView2/1/w/100/h/100"></td><td>翻譯</td><td>全桟工程師，<a href="https://skyverd.com">時光博客</a></td></tr></tbody></table></article>