README

本包提供了一些工具，用于在Laravel中根据白宫标准生成API响应。

💡 在本包中，使用了此PHP包。

安装

$ composer require emyoutis/laravel-whitehouse-responder

用法

以下别名已在本包的主要服务提供者中注册。

WhiteHouseResponderResponse 对应于 Emyoutis\LaravelWhiteHouseResponder\Facades\Response
WhiteHouseResponderErrors 对应于 Emyoutis\LaravelWhiteHouseResponder\Facades\ErrorsRepository

在下面的所有示例中，都使用别名代替完整的命名空间。

注册错误

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

WhiteHouseResponderErrors::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'
);

注销错误

注销已注册的错误是一个常见问题。您可以使用下面的代码来做到这一点。

WhiteHouseResponderErrors::unregister('40001');

制作失败响应

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

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

之后，我们还有一个方法可以在您想手动指定状态时使用。

WhiteHouseResponderResponse::error('40001', 422);

替换

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

WhiteHouseResponderErrors::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 WhiteHouseResponderResponse::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"
}

省略错误异常

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

WhiteHouseResponderErrors::disableExceptions();

制作成功响应

正如白宫标准所说，成功响应必须包含两个部分：results和metadata。这些部分可以传递给success()方法以生成成功响应。

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

键格式化器

您可以注册一个闭包，用于格式化由包生成的所有键。例如，如果我们有一个将字符串映射到snake-case格式的snake_case()函数，我们可以使用以下代码。

WhiteHouseResponderErrors::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'
);

WhiteHouseResponderErrors::registerFormatter(function ($key) {
    return snake_case($key);
});


return WhiteHouseResponderErrors::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 / laravel-whitehouse-responder

维护者

详细信息