README

欢迎使用FTD默认API响应！

关于
安装
如何使用
- 成功方法
- 分页方法
- 错误方法
- 成功、分页和错误方法的进阶使用
- 自定义方法
- 默认状态码方法
- 默认状态码方法的代码列表

关于

该软件包是为了扩展Laravel框架的响应系统，并将其提升到{json:api}网站所描述的标准而创建的¹。

除了创建更友好和可读的格式之外，这些响应还考虑了根据最新代码控制头部。

安装

使用composer安装我们的包

composer require ftd/default-api-response

并在您的Laravel /config/app.php文件中调用提供者

    'providers' => [
    ...
        /*
         * FTD Default API Response
         */
         FTD\DefaultAPIResponse\DefaultAPIResponseServiceProvider::class,
    ],

现在已完成，我们准备出发！

如何使用

FTD API Response为我们提供了5个新方法

成功
分页
错误
自定义
默认状态码

每个方法都有特定的使用方式，但总是很简单。

成功方法

此方法将抛出状态码头 200 并将您的内容放入一个 data 包装器中

示例

  public function index()
  {
      return response()->success(App\User::all());
  }

结果

{
  "data": [
    {
      "id": 1,
      "name": "Rodolfo",
      "email": "rodolfo@ftdapi.com",
      "created_at": null,
      "updated_at": null
    },
    {
      "id": 2,
      "name": "Shirley",
      "email": "shirlei@ftdapi.com",
      "created_at": "2017-06-16 01:02:03",
      "updated_at": null
    }
  ]
}

示例

  public function show(User $user)
  {
      return response()->success($user);
  }

结果

{
  "data": {
    "id": 1,
    "name": "Rodolfo",
    "email": "rodolfo@ftdapi.com",
    "created_at": null,
    "updated_at": null
  }
}

分页方法

此方法将抛出状态码头 200 并将您的内容放入一个 data 包装器中，并创建另一个名为 meta 的包装器，用于分页属性

示例

  public function index()
  {
      $users = App\User::paginate(2);
    return response()->paginate($users);
  }

结果

{
  "meta": {
    "pagination": {
      "current_page": 2,
      "from": 3,
      "last_page": 3,
      "next_page_url": "http://ftdapi.com/api?page=3",
      "path": "http://ftdapi.com/api",
      "per_page": 2,
      "prev_page_url": "http://ftdapi.com/api?page=1",
      "to": 4,
      "total": 6
    }
  },
  "data": [
    {
      "id": 3,
      "name": "Marley",
      "email": "marley@ftdapi.com",
      "created_at": "2017-06-15 00:00:01",
      "updated_at": null
    },
    {
      "id": 4,
      "name": "Steve",
      "email": "steve@ftdapi.com",
      "created_at": "2017-06-16 01:02:03",
      "updated_at": null
    }
  ]
}

错误方法

此方法将抛出状态码头 400 并将您的内容放入一个 errors 包装器中

示例

  //User Custom Request
  public function rules()
  {
    return [
        'name'      => 'required|string|max:255',
        'username'  => 'required|unique:users|string|max:255',
        'password'  => 'required|string|max:255'
    ];
  }

  ...

  public function response(array $errors)
  {
    return response()->error($errors);
  }

结果

{
  "errors": [
    "Name must be provided.",
    "Username must be provided.",
    "Password must be provided."
  ]
}

成功、分页和错误方法的进阶使用

如果您需要更改这些方法的默认状态码，可以提供第二个参数，例如

  ...
  return response()->success($data, 201);

  ...
  return response()->paginate($data, 206);

  ...
  return response()->error($data, 401);

自定义方法

此方法用于需要更多控制整个响应的用户

默认内容为 null
默认 头部状态码 为 200
默认 额外头部 为 null
默认 头部内容类型 为 'application/json'

示例

  public function myCustomMethod()
  {
    return response()->custom(
      $content = [
            "Name" => "Rodolfo",
            "Age"=>13
            ],
      $status = 200,
      $headers = ["X-USER-INFO" => TRUE],
      $headerContentType = 'application/json'
    );
  }

结果： 在您的头部您将看到

  "X-USER-INFO" : true

或

  "X-USER-INFO" : 1

取决于您使用的浏览器。

最后，响应体将接收内容，但没有默认的 data 包装器

{
  "Name": "Rodolfo",
  "Age": 13
}

如果您需要强制下载PDF文件，例如，此方法是正确的方法。

默认状态码方法

此方法将抛出头部状态码，具体取决于哪个代码，将默认消息内容放入一个 data 或 errors 包装器中

示例

  public function store()
  {
    return response()->defaultStatusCode(400);
  }

结果

{
  "errors": [
    "Bad Request"
  ]
}

默认状态码方法的代码列表

如果您需要更多关于状态码的信息，HTTP状态码网站²可能对您有所帮助。

uglymanfirst / laravel-api_responses

维护者

详细信息