README

Laravel API Response Helpers

一个允许在整个Laravel应用程序中保持一致API响应的简单包。

要求

• PHP ^8.0
• Laravel ^8.12, ^9.0, ^10.0 或 ^11.0

遗留支持

对于PHP ^7.4 和Laravel ^6.0 / ^7.0 的支持，请使用包版本 ^1.5

安装/使用

composer require f9webltd/laravel-api-response-helpers

只需在控制器中引用所需的特性即可

<?php

namespace App\Http\Api\Controllers;

use F9Web\ApiResponseHelpers;
use Illuminate\Http\JsonResponse;

class OrdersController
{
    use ApiResponseHelpers;

    public function index(): JsonResponse
    {
        return $this->respondWithSuccess();
    }
}

可选地，可以在基控制器中导入该特性。

可用方法

respondNotFound(string|Exception $message, ?string $key = 'error')

返回404 HTTP状态码，可以可选地传递一个异常对象。

respondWithSuccess(array|Arrayable|JsonSerializable|null $contents = null)

返回200 HTTP状态码，可以可选地传递$contents作为要返回的JSON。默认返回['success' => true]。

respondOk(string $message)

返回200 HTTP状态码

respondUnAuthenticated(?string $message = null)

返回401 HTTP状态码

respondForbidden(?string $message = null)

返回403 HTTP状态码

respondError(?string $message = null)

返回400 HTTP状态码

respondCreated(array|Arrayable|JsonSerializable|null $data = null)

返回201 HTTP状态码，带有可选的响应数据

respondNoContent(array|Arrayable|JsonSerializable|null $data = null)

返回204 HTTP状态码，带有可选的响应数据。严格来说，响应体应该是空的。然而，为了处理遗留项目，添加了可选地返回数据的功能。在您自己的项目中，您可以直接调用该方法，省略参数，以生成正确的204响应，即return $this->respondNoContent()

setDefaultSuccessResponse(?array $content = null): self

可选地，用$content替换respondWithSuccess返回的默认['success' => true]响应。此方法可以从构造函数（用于更改所有调用时的默认值）中调用，从基API控制器或需要的地方调用。

setDefaultSuccessResponse 是一个返回 $this 的流畅方法，允许进行链式方法调用

$users = collect([10, 20, 30, 40]);

return $this->setDefaultSuccessResponse([])->respondWithSuccess($users);

或者

public function __construct()
{
    $this->setDefaultSuccessResponse([]);
}

...

$users = collect([10, 20, 30, 40]);

return $this->respondWithSuccess($users);

使用额外的对象类型

除了普通的PHP array之外，以下数据类型可以传递给相关方法

• 实现Laravel Illuminate\Contracts\Support\Arrayable契约的对象
• 实现原生PHP JsonSerializable契约的对象

这允许传递和自动转换各种对象类型。

以下是一些可以传递的常见对象类型。

Laravel 集合 - Illuminate\Support\Collection

$users = collect([10, 20, 30, 40]);

return $this->respondWithSuccess($users);

Laravel Eloquent 集合 - Illuminate\Database\Eloquent\Collection

$invoices = Invoice::pending()->get();

return $this->respondWithSuccess($invoices);

Laravel API 资源 - Illuminate\Http\Resources\Json\JsonResource

此包旨在与Laravel的API资源一起使用，绝对不替换它们。

$resource = PostResource::make($post);

return $this->respondCreated($resource);

动机

确保在整个应用程序中保持一致的JSON API响应。动机主要基于一个非常古老的可继承的Laravel项目。该项目包含了许多用于返回错误响应的方法/结构

• response()->json(['error' => $error], 400)
• response()->json(['data' => ['error' => $error], 400)
• response()->json(['message' => $error], Response::HTTP_BAD_REQUEST)
• response()->json([$error], 400)
• 等等。

我想添加一个简单的特质来保持一致性，在这种情况下

$this->respondError('Ouch')

升级

有关详细信息，请参阅 UPGRADING。

贡献

欢迎任何想法。请随时提交任何问题或拉取请求。

测试

composer test

安全

如果您发现任何与安全相关的问题，请通过电子邮件 rob@f9web.co.uk 联系，而不是使用问题跟踪器。

鸣谢

• Rob Allport 来自 F9 Web Ltd.
• 所有贡献者

许可

MIT 许可证 (MIT)。请参阅 许可文件 了解更多信息。