ApiProblem

ApiProblem

该库提供了 IETF Problem Details for HTTP API (RFC 9457) 的简单直接实现。

RFC 9457 是一个简单规范，用于格式化网络上 RESTful API 的错误响应。该库提供了一种与该规范交互的简单便捷的方法。它支持生成和解析 JSON 和 XML 变体中的 RFC 9457 消息。

生成响应

你说什么？有人向您的 API 发送了错误请求？告诉他们这是一个问题！

ApiProblem ; $problem = new ApiProblem ("You do not have enough credit.", "http://example.com/probs/out-of-credit"); // Defined properties in the API have their own setter methods. $problem ->setDetail("Your current balance is 30, but that costs 50.") ->setInstance("http://example.net/account/12345/msgs/abc"); // But you can also support any arbitrary extended properties! $problem['balance'] = 30; $problem['accounts'] = [ "http://example.net/account/12345", "http://example.net/account/67890" ]; $json_string = $problem->asJson(); // Now send that JSON string as a response along with the appropriate HTTP error // code and content type which is available via ApiProblem ::CONTENT_TYPE_JSON. // Also check out asXml() and ApiProblem ::CONTENT_TYPE_XML for the angle-bracket fans in the room.">

 use Crell  ApiProblem  ApiProblem ;

$ problem = new ApiProblem ( " You do not have enough credit. " , " http://example.com/probs/out-of-credit " );
// Defined properties in the API have their own setter methods.
$ problem
  -> setDetail ( " Your current balance is 30, but that costs 50. " )
  -> setInstance ( " http://example.net/account/12345/msgs/abc " );
// But you can also support any arbitrary extended properties!
$ problem [ ' balance ' ] = 30 ;
$ problem [ ' accounts ' ] = [
  " http://example.net/account/12345 " ,
  " http://example.net/account/67890 "
];

$ json_string = $ problem -> asJson ();

// Now send that JSON string as a response along with the appropriate HTTP error
// code and content type which is available via ApiProblem ::CONTENT_TYPE_JSON.
// Also check out asXml() and ApiProblem ::CONTENT_TYPE_XML for the angle-bracket fans in the room.

或者，更好的是，您可以针对特定问题类型对ApiProblem进行子类化（因为类型和标题应该放在一起并且相对固定），然后只需填充您自己的特定于错误的数据。就像扩展例外一样！

如果您使用的库或框架想要进行自己的 JSON 序列化，那么也完全支持。 ApiProblem实现了JsonSerializable ，因此您可以将其直接传递给json_encode()就像它是一个裸数组一样。

 $ response = new MyFrameworksJsonResponse ( $ problem );

// Or do it yourself
$ body = json_encode ( $ problem );

发送回复

您可能正在使用 PSR-7 进行回答。这就是为什么这个库包含一个实用程序，可以使用您选择的 PSR-17 工厂将ApiProblem对象转换为 PSR-7 ResponseInterface对象。就像这样：

ApiProblemHttpConverter; $factory = getResponseFactoryFromSomewhere(); // The second parameter says whether to pretty-print the output. $converter = new HttpConverter($factory, true); $response = $converter->toJsonResponse($problem); // or $response = $converter->toXmlResponse($problem);">

 use Crell  ApiProblem  HttpConverter ;

$ factory = getResponseFactoryFromSomewhere ();

// The second parameter says whether to pretty-print the output.
$ converter = new HttpConverter ( $ factory , true );

$ response = $ converter -> toJsonResponse ( $ problem );
// or
$ response = $ converter -> toXmlResponse ( $ problem );

这会返回一个功能齐全且已标记的 Response 对象，准备发送回客户端。

接收回复

您是否正在向响应 API 问题错误的 API 发送消息？没问题！您可以像这样轻松处理该响应：

ApiProblem ; $problem = ApiProblem ::fromJson($some_json_string); $title = $problem->getTitle(); $type = $problem->getType(); // Great, now we know what went wrong, so we can figure out what to do about it.">

 use Crell  ApiProblem  ApiProblem ;

$ problem = ApiProblem :: fromJson ( $ some_json_string );
$ title = $ problem -> getTitle ();
$ type = $ problem -> getType ();
// Great, now we know what went wrong, so we can figure out what to do about it.

（它也适用于 fromXml()！）

安装

像任何其他 Composer 包一样安装ApiProblem ：

 composer require crell/api-problem

有关更多详细信息，请参阅 Composer 文档。

安全

如果您发现任何与安全相关的问题，请使用 GitHub 安全报告表而不是问题队列。

制作人员

• [拉里·加菲尔德][链接作者]
• [所有贡献者][链接贡献者]

执照

该库是在 MIT 许可下发布的。简而言之，“保留版权声明完整，否则玩得开心。”请参阅许可证了解更多信息。

贡献

已接受拉取请求！目标是完全符合 IETF 规范。