ApiProblem

其他类别 2025-08-20

ApiProblem

该库提供了HTTP API的IETF问题详细信息的简单直接实现,RFC 9457。

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

产生响应

你说什么?有人向您的API发送了不良要求?告诉他们这是一个问题!

ApiProblem ; $problem = new ApiProblem ("You do not have enough credit.", "http://*exam*p*le.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://exampl*e.**net/account/12345/msgs/abc"); // But you can also support any arbitrary extended properties! $problem['balance'] = 30; $problem['accounts'] = [ "http://exam*p*le.*net/account/12345", "http://*exam**ple.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://*exam*p*le.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://exampl*e.**net/account/12345/msgs/abc " );
// But you can also support any arbitrary extended properties!
$ problem [ ' balance ' ] = 30 ;
$ problem [ ' accounts ' ] = [
  " http://exam*p*le.*net/account/12345 " ,
  " http://*exam**ple.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子类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 );

这给了一个彻底的响应对象,准备回到客户端。

收到回复

您是否正在向正在响应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()!)

安装

像其他任何作曲家包一样安装ApiProblem :

 composer require crell/api-problem

有关更多详细信息,请参见作曲家文档。

安全

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

学分

  • [Larry Garfield] [Link-aTHOTOR]
  • [所有贡献者] [链接构造者]

执照

该库是根据麻省理工学院许可证发布的。简而言之,“让版权声明完好无损,否则会很开心。”有关更多信息,请参见许可证。

贡献

接受请求的请求!目标是完全符合IETF规格。

下载源码

通过命令行克隆项目:

git clone https://github.com/Crell/ApiProblem.git