Call API: Format Response

在 [Day 14] Laravel HTTP Response 簡介 一文中，提到 Laravel 會自動將 陣列 轉換為 JSON Response，以及前篇 [Day XX] Laravel 的 XXXResource::make() 的 make() 作用 - new static() 提及 XXXResource::make() 的 make() 作用。
本文會利用上述的這兩篇文章，介紹 Laravel 提供的 Eloquent's resource 方法，此方法可以將 Model 與 Model Collection 轉換為 JSON。

• 起手式 cli:
  Laravel 提供的 Eloquent's resource 可以經過 cli 產生，只要在終端機輸入 php artisan make:resource ModelResource，例如 php artisan make:resource ProductResource

<?php

class ProductResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id'               => $this->id,
            'customer_id'      => $this->customer_id,
            'product_number'   => $this->product_number
        ];
    }
}

• 在 class XXXResource 直接使用 $this 變數來存取 Model 的屬性 - 參考 Eloquent's resource #concept-overview

使用 Eloquent's resource 前後差異

• 未使用 Eloquent's resource
  • 輸出 Model 所有的屬性

<?php
Route::get('product', function(){
    
    $firstProduct = Product::first();
    return $firstProduct;
}
           
/* call api: 127.0.0.1:8001/v1/product
 * {
 *  "id": 1,
 *  "customer_id": 1,
 *  "product_number": "230626000001",
 *  "serial_number": "5",
 *  "registered_date": "2023-06-26",
 *  "registered_status": 1,
 *  "created_at": "2023-06-26T08:30:12.000000Z",
 *  "updated_at": null
 * }
 */ 

• 使用 Eloquent's resource
  • 僅輸出 class resource 設定的內容
  • class resource 的 key 和 value 都可以做更改，本例未作更改

<?php
Route::get('product', function(){
    
    $firstProduct = Product::first();
    return ProductResource::make($firstProduct);
}
           
/* call api: 127.0.0.1:8001/v1/product
 * {
 *  "id": 1,
 *  "customer_id": 1,
 *  "product_number": "230626000001"
 * }
 */    

• 若遇上 Model 多筆資料 (Model Collection)，使用 Resource 類別提供的 collection 方法 (collection()) ，表示如下:

<?php
Route::get('product', function(){
    
    $allProduct = Product::all();
    return ProductResource::collection($allProduct);
}


/* call api: 127.0.0.1:8001/v1/product
 * {
 *   "data": [
 *     {
 *       "id": 1,
 *       "customer_id": 1,
 *       "product_number": "230626000001"
 *     },
 *     {
 *       "id": 2,
 *       "customer_id": 1,
 *       "product_number": "230626000002"
 *     },
 *     ...略
 *    ]
 * }
 */         

結語

使用了 Eloquent's resource 後，可以將一些 Model 屬性提供給特定使用者看到；或者，可以在 Model 的 JSON 呈現上包含特定的關聯，達到 Format Response 功能。

參考文章

1 [Day 14] Laravel HTTP Response 簡介
2 [Day XX] Laravel 的 XXXResource::make() 的 make() 作用 - new static()
3 Eloquent's resource
4 Eloquent's resource #concept-overview