Laravel & Lumen RESTFul API 擴充包：Dingo API（五） -- 轉化器（Transformer）

1、簡介

通過轉化器，你可以將對象轉化為數組，並強制轉化整型和布爾類型，包括分頁結果和嵌套關聯。

本章節我們主要討論轉化器及其使用，這裡的轉化器包括以下兩層意思：

• 轉化層（transformation layer）是一個準備和處理轉化器的庫
• 轉化器（transformer）是一個擷取未經處理資料並將其轉化為數組格式的類，處理器的處理方式取決於轉化層。

2、使用轉化器

有多種方式使用轉化器。

為某個類註冊轉化器

當你為某個類註冊轉化器後就可以從路由返回這個類（假設它可以被轉化為數組）並自動經過轉化器處理：

app('Dingo\Api\Transformer\Factory')->register('User', 'UserTransformer');

這在使用模型的簡單API中很有用，因為你可以從路由中直接返回模型。

使用響應構建器

參考響應構建器章節。

2、 Fractal

Fractal是Dingo API預設的轉化層，它提供了一系列有用的特性來保持資料的一致性。

使用Fractal之前建議好好閱讀其官方文檔。

全自動關聯關係渴求式載入

當使用Fractal的內建功能嵌入關聯關係時確保其命名和模型中的命名一致。擴充包會自動為你渴求式載入這些關聯關係。

進階配置

Fractal以預設配置註冊為預設轉化層，要手動設定需要在服務提供者中執行個體化 Dingo\Api\Transformer\Adapter\Fractal執行個體：

$this->app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) {     return new Dingo\Api\Transformer\Adapter\Fractal(new League\Fractal\Manager, 'include', ',');});

如果你使用的是Lumen可以在開機檔案（bootstrap.php）中這麼做：

app('Dingo\Api\Transformer\Factory')->setAdapter(function ($app) {    return new Dingo\Api\Transformer\Adapter\Fractal(new League\Fractal\Manager, 'include', ',');});

通過響應構建器實現進階使用

與響應構建器相結合使用Fractal通常是從控制器返回資料的最佳方式。響應構建器上的 item、 collection和 paginator方法都可以接收額外參數用於自訂Fractal。

資源key

return $this->item($user, new UserTransformer, ['key' => 'user']);

使用回調

Fractal轉化層允許你註冊一個建立資源之後觸發的回調，這個回調接收 League\Fractal\Resource\Item或者 League\Fractal\Resource\Collection作為第一個參數， League\Fractal\Manager執行個體作為第二個參數。然後你可以使用這個回調在更複雜的層級上與資源進行互動。

最常見的使用案例就是設定分頁遊標或者修改響應串列：

return $this->collection($users, new UserTransformer, [], function ($resource, $fractal) {    $resource->setCursor($cursor);});

如果你不想傳遞資源key參數可以省略這個空數組：

return $this->collection($users, new UserTransformer, function ($resource, $fractal) {    $fractal->setSerializer(new CustomSerializer);});

3、自訂轉化層

如果你想對資料轉化進行更多的自訂，可以在Dingo API中實現自己的轉化層。這需要建立一個實現 Dingo\Api\Contract\Transformer\Adapter的類並且實現 transform方法：

use Dingo\Api\Http\Request;use Dingo\Api\Transformer\Binding;use Dingo\Api\Contract\Transformer\Adapter;class MyCustomTransformer implements Adapter{    public function transform($response, $transformer, Binding $binding, Request $request)    {        // Make a call to your transformation layer to transformer the given response.    }}

transform是唯一必須的方法，你可以自由添加自己想要的其他方法。 transform方法的目的是擷取 $response，然後和 $transformer一起傳遞給轉化層處理，然後轉化層會返回一個數組，最終這個數組被 transform方法返回。如果你的轉化層很簡單，可以完全在這個類中實現所有邏輯。

$bindings參數在你的轉化層包含更多特性比如添加中繼資料或者允許開發人員通過回調與轉化層互動時很有用。

$request參數是當前被執行的HTTP請求，當你的轉化層需要查詢字串參數或者其他相關資料時很有用。

