README

此包提供了一些工具，用于基于PHP的白宫标准生成API响应。

安装

$ composer require emyoutis/whitehouse-responder

用法

创建对象

use Emyoutis\WhiteHouseResponder\ErrorsRepository;
use Emyoutis\WhiteHouseResponder\Response;

$errorsRepository = new ErrorsRepository();
$response = new Response($errorsRepository);

注册错误

根据白宫标准，每个错误代码都应指向一个错误实体。在WhiteHouse Responder中，您可以在ErrorsRepository类中注册您的错误及其信息，以便之后使用。

$errorsRepository->register(
     '40001',
     'Verbose, plain language description of the problem. Provide developers suggestions about how to solve their problems here',
     'This is a message that can be passed along to end-users, if needed.',
     'http://www.example.gov/developer/path/to/help/for/444444'
);

注销错误

注销错误是一个常见问题。您可以使用以下代码来完成此操作。

$errorsRepository->unregister('40001');

创建失败响应

根据白宫标准，失败响应应返回400或500响应。因此，我们有两种可用的方法来返回具有这些状态的错误。

clientError()：此方法可以生成客户端错误的响应体。
```
$response->clientError('40001');
```
clientError()：此方法可以生成服务器错误的响应体。
```
$response->serverError('40001');
```

之后，我们还有一个用于手动指定状态的方法。

$response->error('40001', 422);

替换

在注册错误时，您可以在错误信息中放置一些可替换的短语，使它们的内容动态化。可替换的短语应以一个:开头。

$errorsRepository->register(
     '40001',
     'The class `:class` is undefined.',
     'An error has been occurred in while finding the :entity.',
     'http://www.example.gov/developer/path/to/help/for/444444'
);

return $response->clientError(40001, [
     'class'  => 'Entities/User',
     'entity' => 'user',
])

返回值将是

{
  "status": 400,
  "developerMessage": "The class `Entities/User` is undefined.",
  "userMessage": "An error has been occurred in while finding the user.",
  "errorCode": "40001",
  "moreInfo": "http://www.example.gov/developer/path/to/help/for/444444"
}

省略错误异常

默认情况下，错误存储库在注册已注册的错误代码或请求不存在的错误代码时抛出异常。但您可以使用以下代码禁用抛出这些异常。

$errorsRepository->disableExceptions();

创建成功响应

如白宫标准所述，成功响应必须包含两个部分；results和metadata。这些部分可以通过传递给success()方法的参数来生成成功响应。

$results  = [
     [
          'id'    => 1,
          'title' => 'First Item',
     ],
     [
          'id'    => 2,
          'title' => 'Second Item',
     ],
];
$metadata = ['page' => 1];
    
$response = $response->success($results, $metadata);

键格式化器

您可以为包装生成的所有键注册一个闭包进行格式化。例如，如果我们有一个将字符串映射到蛇形格式的snake_case()函数，我们可以有以下的代码。

$errorsRepository->register(
     '40001',
     'Verbose, plain language description of the problem. Provide developers suggestions about how to solve their problems here',
     'This is a message that can be passed along to end-users, if needed.',
     'http://www.example.gov/developer/path/to/help/for/444444'
);

$response->registerFormatter(function ($key) {
    return snake_case($key);
});


return $response->clientError(40001);

此代码的返回结果将是

{
  "status": 400,
  "developer_message": "Verbose, plain language description of the problem. Provide developers suggestions about how to solve their problems here",
  "user_message": "This is a message that can be passed along to end-users, if needed.",
  "error_code": "40001",
  "more_info": "http://www.example.gov/developer/path/to/help/for/444444"
}

💡更改键可能会使您的响应不符合白宫标准。

emyoutis / whitehouse-responder

维护者

详细信息