序列化 · 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>