README

Fracture 是一个库，用于使基于 Laravel 的 API 响应更一致。

安装

composer require flipboxstudio/api-fracture

配置

将此行添加到服务提供者列表中

Flipbox\Fracture\FractureServiceProvider::class,

之后，运行

php artisan vendor:publish

此命令将一个空的 fracture.php 配置文件复制到您的 config 目录。您可能需要阅读此文件以进行更多自定义配置。

可选

将此行添加到外观列表中

'Fracture' => Flipbox\Fracture\Facades\Fracture::class,

用法

Fracture 将覆盖 Laravel 控制器的调用方式。因此，为了使此功能在您的项目中工作，您需要更改您的基控制器。在以下位置找到此文件：

app/Http/Controllers/Controller.php

将此文件更改为

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Flipbox\Fracture\Routing\Controller as FractureController;

class Controller extends FractureController
{
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}

然后您就可以开始使用了！下面是使用 fracture 的示例。

<?php

namespace App\Http\Controllers\Api;

use App\User;
use App\Http\Requests;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        Fracture::setMessage('user_list_fetched');

        return User::all(); // identical with Fracture::responseCollection(User::all(), 'user_list_fetched')
    }

    /**
     * Display the specified resource.
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     */
    public function show($id)
    {
        Fracture::setMessage('user_fetched');

        return User::findOrFail($id); // identical with Fracture::responseItem(User::findOrFail($id), 'user_fetched')
    }

Fracture 有它自己的默认转换器，您可以在 fracture.php 配置文件中进行配置。从上面的控制器（使用 fracture 默认转换器），您的响应将被转换成以下内容：

{
  "success": true,
  "data": {
    "data": [
      {
        "id": 1,
        "name": "Krisan Alfa Timur",
        "email": "alfa@flipbox.co.id",
        "created_at": "2016-08-29 07:01:08",
        "updated_at": "2016-08-29 11:37:10",
        "type": "user"
      }
    ]
  },
  "message": "user_list_fetched"
}

要配置您的转换器，Fracture 将确定控制器返回的对象。因此，为了转换您的 App\User 对象，您需要在 fracture.php 配置文件中配置转换器，在 transformers 目录内，添加 app_user 信息。

<?php

return [

    'transformers' => [

        'app_user' => [
            'class' => App\Transformers\UserTransformer::class,
        ],

    ],


    // [... OMITTED ...]

];

Fracture 将自动将您的当前转换器转换为小驼峰命名法，以确定应使用哪个配置。因此，对于 App\User 资源类型，它将解析为 app_user。在此键中，使用具有 class 值的数组键值对作为它的转换器。以下是一个基本的转换器：

<?php

namespace App\Transformers;

use URL;
use App\User;
use League\Fractal\TransformerAbstract;

class UserTransformer extends TransformerAbstract
{
    public function transform(User $user)
    {
        return [
            'type' => 'user',
            'id' => (int) $user->id,
            'name' => (string) $user->name,
            'links' => [[
                'rel' => 'self',
                'type' => 'api',
                'uri' => URL::to('/api/resource/user/'.$user->id),
            ]],
        ];
    }
}

从上面的转换器，响应将被转换成以下内容：

{
  "success": true,
  "data": [
    {
      "type": "user",
      "id": "1",
      "attributes": {
        "name": "Krisan Alfa Timur",
        "links": [
          {
            "rel": "self",
            "type": "api",
            "uri": "http://laravel.ivory.dev/api/resource/user/1"
          }
        ]
      }
    }
  ],
  "message": "user_list_fetched"
}

动态设置转换器

您可以在将响应发送给客户端之前设置转换器。要做到这一点，在控制器方法中返回任何响应之前，您可能需要调用 Fracture::setTransformer 方法。

<?php

use App\Transformers\UserTransformer;

Fracture::setTransformer(UserTransformer::class);
// Or
Fracture::setTransformer(new UserTransformer());

路由转换器

您还可以通过路由操作告诉 Fracture 使用特定的转换器。

<?php

Route::get('/user', [
    'uses' => 'UserController@index',
    'transformer' => App\Transformers\UserTransformer::class,
    'middleware' => ['auth:api'],
    'as' => 'user.list'
]);

自定义 HTTP 状态码

<?php

return Fracture::responseCollection(
    $collection, // Collection
    'user_list', // API Message
    true, // API success status
    200, // HTTP status code
    ['Custom-Header' => 'Flipbox'] // Your header goes here
);

return Fracture::responseItem(
    $item, // Item
    'user_info', // API Message
    true, // API success status
    200, // HTTP status code
    ['Custom-Header' => 'Flipbox'] // Your header goes here
);

生成错误响应

以下是生成错误响应的代码片段：

<?php

return Fracture::responseError(
    'awww_snap', // API Message
    new \Exception('something_goes_wrong') // An exception instance
);

从上面的代码，响应是：

{
  "success": false,
  "data": {
    "type": "error",
    "code": 0
  },
  "message": "awww_snap"
}

在调试模式下

{
  "success": false,
  "data": {
    "type": "error",
    "code": 0,
    "message": "something_goes_wrong",
    "trace": [
      "#0 [internal function]: App\\Http\\Controllers\\Api\\UserController->index()",
      // [... OMITTED ...]
    ]
  },
  "message": "awww_snap"
}

待办事项

重构（需要志愿者）
单元测试
全局错误处理
可配置序列化器
可配置错误序列化器
可配置错误转换器
所有资源的默认转换器
拦截默认 Laravel 响应准备以使用 Fracture
您想要的任何功能；)

flipboxstudio / api-fracture

维护者

详细信息