Laravel - Eloquent ORM - Serialization (官方文件原子化翻譯)

# 前言

學習一個框架, Ray 的想法是, 在深入理解底層實作的原理之前, 應該先知道這個框架的 使用方法; 先學習怎麼使用這個前人造的輪子, 再學習怎麼樣造一個輪子。
所以本篇文章重點在於細讀官方文件, 並將內容理解後以 Q&A 的方式記錄下來, 加速學習以及查詢。

# Serializing Models & Collections

# Serializing To Arrays

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use App\Models\User;
  
  $user = User::with('roles')->first();
  
  return $user->toArray();

• Answer:
  convert model 以及其 relation to array

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $user = User::first();
  
  return $user->attributesToArray();

• Answer:
  將 $user model 的 attribute 轉為 array, 不包含 relation

以下的 Laravel example code 的意思是？

• Example:

  <?php
  $users = User::all();
  
  return $users->toArray();

• Answer:
  將 $users collection 轉為 array

# Serializing To JSON

以下的 Laravel example code 的意思是？

• Example:

  <?php
  use App\Models\User;
  
  $user = User::find(1);
  
  return $user->toJson();
  
  return $user->toJson(JSON_PRETTY_PRINT);

• Answer:
  將 model 轉為 JSON, 也可帶入 PHP 支援的 JSON encoding option

以下的 Laravel example code 的意思是？

• Example:

  <?php
  return (string) User::find(1);

• Answer:
  cast model 或 collection to string, 會自動呼叫 toJson method

以下的 Laravel example code 的意思是？

• Example:

  <?php
  Route::get('users', function () {
      return User::all();
  });

• Answer:
  如果直接 return Eloquent objects, Laravel 會自動將其轉為 JSON

# Hiding Attributes From JSON

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Models;
  
  use Illuminate\Database\Eloquent\Model;
  
  class User extends Model
  {
      protected $hidden = ['password'];
  }

• Answer:
  $hidden 內的 attribute 不會被 serialized 成 JSON

Laravel 中, 如果我要讓一個 model 的 relation hidden, 可以怎麼做？

在 $hidden property 內帶入 relation method name

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Models;
  
  use Illuminate\Database\Eloquent\Model;
  
  class User extends Model
  {
      protected $visible = ['first_name', 'last_name'];
  }

• Answer:
  所以不在 $visible property 內的 attribute 都不會被 serialized 到 model array 或 JSON

# Temporarily Modifying Attribute Visibility

以下的 Laravel example code 的意思是？

• Example:

  <?php
  return $user->makeVisible('attribute')->toArray();

• Answer:
  暫時性的讓原本被 hidden 的 attribute visible, 這樣才會被 serialized 到 array 內

以下的 Laravel example code 的意思是？

• Example:

  <?php
  return $user->makeHidden('attribute')->toArray();

• Answer:
  暫時性的讓原本被 visible 的 attribute hidden, 這樣才不會被 serialized 到 array 內

# Appending Values To JSON

以下的 Laravel example code 的意思是？

• Example:

  <?php
  
  namespace App\Models;
  
  use Illuminate\Database\Eloquent\Model;
  
  class User extends Model
  {
      protected $appends = ['is_admin'];
  
      public function getIsAdminAttribute()
      {
          return $this->attributes['admin'] === 'yes';
      }
      
  }

• Answer:
  Model 中, 使用 accessor 取得值, 在放到 $appends property 中, 這樣每次都會 serializing 到 array 或 JSON 中, 也會反應 $visible 或 $hidden 的設定

# Appending At Run Time

以下的 Laravel example code 的意思是？

• Example:

  <?php
  return $user->append('is_admin')->toArray();
  
  return $user->setAppends(['is_admin'])->toArray();

• Answer:
  使用 append 以及 setAppend, 在 run time 加入, 這樣該 value 才會被 serialized to array 或 JSON

# Date Serialization

# Customizing The Default Date Format

以下的 Laravel example code 的意思是？

• Example:

  <?php
  protected function serializeDate(DateTimeInterface $date)
  {
      return $date->format('Y-m-d');
  }

• Answer:
  在 model 中, 使用 serializeDate() 定義 date serialization format, 此設定並不會影響 date 要存進資料庫時的格式化過程

# Customizing The Date Format Per Attribute

以下的 laravel example code 的意思是？

• example:

  <?php
  protected $casts = [
      'birthday' => 'date:y-m-d',
      'joined_at' => 'datetime:y-m-d h:00',
  ];

• answer:
  在 model 的 $casts property 內, 可以針對不同的 date attribute 定義不同的 serialization format

以下的 laravel example code 的意思是？

• example:

  <?php
  protected $casts = [
      'birthday' => 'immutable_date:y-m-d',
      'joined_at' => 'immutable_datetime:y-m-d h:00',
  ];

• answer:
  在 model 的 $casts property 內, 可以針對不同的 date attribute 定義不同的 serialization format