序列化 · laravel 5.4

<article><h1>Eloquent: 序列化</h1><ul><li><a href="#introduction">簡介</a></li><li><a href="#serializing-models-and-collections">序列化模型 & 集合</a><ul><li><a href="#serializing-to-arrays">序列化成數組</a></li><li><a href="#serializing-to-json">序列化成 JSON</a></li></ul></li><li><a href="#hiding-attributes-from-json">隱藏來自 JSON 的屬性</a></li><li><a href="#appending-values-to-json">添加參數到 JSON 中</a></li></ul><a name="introduction"></a><h2><a href="#introduction">簡介</a></h2>當你在創建 JSON API 的時候，經常會需要將模型和關聯轉換成數組或 JSON。Eloquent 提供了一些便捷的方法來讓我們可以完成這些轉換，以及控制哪些屬性需要被包括在序列化中。<a name="serializing-models-and-collections"></a><h2><a href="#serializing-models-and-collections">序列化模型 & 集合</a></h2><a name="serializing-to-arrays"></a><h3>序列化成數組</h3>如果要將模型還有其加載的 <a href="/docs/5.4/eloquent-relationships">關聯</a> 轉換成一個數組，則可以使用 toArray 方法。這個方法是遞歸的，因此，所有屬性和關聯（包含關聯中的關聯）都會被轉換成數組：<pre class=" language-php"><code class=" language-php">$user = App\User::with('roles')->first(); return $user->toArray();</code></pre>你也可以將整個 <a href="/docs/5.4/eloquent-collections">集合</a> 轉換成數組：<pre class=" language-php"><code class=" language-php">$users = App\User::all(); return $users->toArray();</code></pre><a name="serializing-to-json"></a><h3>序列化成 JSON</h3>如果要將模型轉換成 JSON，則可以使用 <code class=" language-php">toJson</code> 方法。如同 <code class=" language-php">toArray</code> 方法一樣，<code class=" language-php">toJson</code> 方法也是遞歸的。因此，所有的屬性以及關聯都會被轉換成 JSON：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); return $user->toJson();</code></pre>或者，你也可以強制把一個模型或集合轉型成一個字符串，它將會自動調用 <code class=" language-php">toJson</code> 方法：<pre class=" language-php"><code class=" language-php">$user = App\User::find(1); return (string) $user;</code></pre>當模型或集合被轉型成字符串時，模型或集合便會被轉換成 <code class=" language-php">JSON</code> 格式，因此你可以直接從應用程序的路由或者控制器中返回 <code class=" language-php">Eloquent</code> 對象：<pre class=" language-php"><code class=" language-php">Route::get('users', function () { return App\User::all(); });</code></pre><a name="hiding-attributes-from-json"></a><h2><a href="#hiding-attributes-from-json">隱藏來自 JSON 的屬性</a></h2>有時候你可能會想要限制包含在模型數組或 JSON 表示中的屬性，比如說密碼。則可以通過在模型中增加 <code class=" language-php">$hidden</code> 屬性定義來實現：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 在數組中想要隱藏的屬性。 * * @var array */ protected $hidden = ['password']; }</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 當你要對關聯進行隱藏時，需使用關聯的 方法 名稱，而不是它的動態屬性名稱。</blockquote>另外，你也可以使用 <code class=" language-php">visible</code> 屬性來定義應該包含在你的模型數組和 JSON 表示中的屬性白名單。白名單外的其他屬性將隱藏，不會出現在轉換后的數組或 JSON 中：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 在數組中可見的屬性。 * * @var array */ protected $visible = ['first_name', 'last_name']; }</code></pre><h4>臨時修改屬性的可見度</h4>你可以在模型實例后使用 <code class=" language-php">makeVisible</code> 方法來顯示通常隱藏的屬性，且為了便于使用，<code class=" language-php">makeVisible</code> 方法會返回一個模型實例：<pre class=" language-php"><code class=" language-php">return $user->makeVisible('attribute')->toArray();</code></pre>相應的，你可以在模型實例后使用 <code class=" language-php">makeHidden</code> 方法來隱藏通常顯示的屬性：<pre class=" language-php"><code class=" language-php">return $user->makeHidden('attribute')->toArray();</code></pre><a name="appending-values-to-json"></a><h2><a href="#appending-values-to-json">添加參數到 JSON 中</a></h2>有時候，在轉換模型到數組或 JSON 時，你希望添加一個在數據庫中沒有對應字段的屬性。首先你需要為這個值定義一個 <a href="/docs/5.4/eloquent-mutators">訪問器</a> ：<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 為用戶獲取管理者的標記。 * * @return bool */ public function getIsAdminAttribute() { return $this->attributes['admin'] == 'yes'; } }</code></pre>訪問器創建成功后，只需添加該屬性到改模型的 <code class=" language-php">appends</code> 屬性中。注意，屬性名稱通常遵循「<a href="https://en.wikipedia.org/wiki/Snake_case">Snake Case</a>」的命名方式，即是訪問器的名稱是基于「<a href="https://en.wikipedia.org/wiki/Camel_case">Camel Case</a>」的命名方式。<pre class=" language-php"><code class=" language-php"><?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 訪問器被附加到模型數組的形式。 * * @var array */ protected $appends = ['is_admin']; }</code></pre>一旦屬性被添加到 <code class=" language-php">appends</code> 清單，便會將模型中的數組和 JSON 這兩種形式都包含進去。在 <code class=" language-php">appends</code> 數組中的屬性也遵循模型中 <code class=" language-php">visible</code> 和 <code class=" language-php">hidden</code> 設置。<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>