序列化 · Laravel 5.6 中文文檔

* * * * * [TOC] ## 簡介構建 JSON API 時，經常需要把模型和關聯轉化為數組或 JSON。針對這些操作，Eloquent 提供了一些便捷方法，以及對序列化中的屬性控制。 ## 序列化模型 & 集合 ### 序列化為數組要轉化模型及其加載的?[關聯](http://www.hmoore.net/tonyyu/laravel_5_6/786273)?為數組，可以使用?`toArray`方法。這是一個遞歸的方法，因此所有的屬性和關聯（包括關聯的關聯）都將轉化成數組： ~~~ $user = App\User::with('roles')->first(); return $user->toArray(); ~~~ 也可以轉化整個模型[集合](http://www.hmoore.net/tonyyu/laravel_5_6/786274)為數組： ~~~ $users = App\User::all(); return $users->toArray(); ~~~ ### 序列化為 JSON 方法`toJson`可以把模型轉化成 JSON。和方法`toArray`一樣，`toJson`方法也是遞歸的，因此所有屬性和關聯都會轉化成 JSON： ~~~ $user = App\User::find(1); return $user->toJson(); ~~~ 也可以把模型或集合轉成字符串，方法`toJson`將自動調用： ~~~ $user = App\User::find(1); return (string) $user; ~~~ 由于模型和集合在轉化為字符串的時候會轉成 JSON，因此可以在應用的路由或控制器中直接返回 Eloquent 對象： ~~~ Route::get('users', function () { return App\User::all(); }); ~~~ ## 隱藏 JSON 屬性有時要將模型數組或 JSON 中的某些屬性進行隱藏，比如密碼，則可以在模型中添加`$hidden`屬性： ~~~ <?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 數組中的屬性會被隱藏 * * @var array */ protected $hidden = ['password']; } ~~~ > {note} 隱藏關聯時，需使用關聯的方法名。此外，也可以使用屬性`$visible`定義一個模型數組和 JSON 可見的白名單。轉化后的數組或 JSON 不會出現其他的屬性： ~~~ <?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 數組中的屬性會被展示 * * @var array */ protected $visible = ['first_name', 'last_name']; } ~~~ #### 臨時修改可見屬性如果需要在一個模型實例中顯示隱藏的屬性，就可以使用`makeVisible`方法。方法`makeVisible`返回模型實例： ~~~ return $user->makeVisible('attribute')->toArray(); ~~~ 相應地, 需要在一個模型實例中隱藏可見的屬性，則可以使用`makeHidden`方法。 ~~~ return $user->makeHidden('attribute')->toArray(); ~~~ ## 追加 JSON 值有時，需要在數組或 JSON 中添加一些數據庫沒有字段對應的屬性。要實現這個功能，先為其定義一個[訪問器](http://www.hmoore.net/tonyyu/laravel_5_6/786275)： ~~~ <?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 為用戶獲取管理員標識 * * @return bool */ public function getIsAdminAttribute() { return $this->attributes['admin'] == 'yes'; } } ~~~ 然后，在模型屬性`appends`中添加該屬性名。注意，盡管訪問器使用「Camel Case」方式定義，但是屬性名通常以「Snake Case」方式引用。 ~~~ <?php namespace App; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * 追加到模型數組表單的訪問器. * * @var array */ protected $appends = ['is_admin']; } ~~~ 屬性只要添加到`appends`列表里，就會被包含到模型數組和 JSON 中。`appends`數組里的屬性也會遵循模型配置的`visible`和`hidden`。 #### 運行時追加在單個模型實例上，使用方法`append`追加屬性，或者，使用方法`setAppends`重寫整個追加屬性的數組： ~~~ return $user->append('is_admin')->toArray(); return $user->setAppends(['is_admin'])->toArray(); ~~~ ## 序列化日期 #### 自定義任意屬性的日期格式可以在 Eloquent 的[屬性類型轉換](http://www.hmoore.net/tonyyu/laravel_5_6/786275#_160)中單獨為日期屬性自定義日期格式： ~~~ protected $casts = [ 'birthday' => 'date:Y-m-d', 'joined_at' => 'datetime:Y-m-d H:00', ]; ~~~ #### 經由 Carbon 全局自定義 Laravel 擴展了[Carbon](https://github.com/briannesbitt/Carbon)日期庫，這為 Carbon 的 JSON 序列化提供了便利。要自定義所有 Carbon 日期在整個應用中的序列化，可以使用`Carbon::serializeUsing`方法。方法`serializeUsing`接受一個閉包，該閉包返回一個字符串形式的日期。 ~~~ <?php namespace App\Providers; use Illuminate\Support\Carbon; use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider { /** * 執行注冊后，啟動服務. * * @return void */ public function boot() { Carbon::serializeUsing(function ($carbon) { return $carbon->format('U'); }); } /** * 在服務容器中注冊綁定 * * @return void */ public function register() { // } } ~~~