README

• master

ApiProblem 是一个尝试提供在 Problem Details for HTTP APIs 中定义的功能和问题报告的功能。目标是提供一个简单的异常包装器，用于 PHP，可以发送所需的 JSON 和 XML 响应。

用法

sendHttpResponse 方法

sendHTTPResponse 有两个参数，都是可选的 $format 和 $terminate。

• 格式:
• ApiProblem::FORMAT_XML: application/api-problem+json
• ApiProblem::FORMAT_JSON: application/api-problem+xml
• terminate: bool
• true (默认) 发送头信息并终止执行。
• false 返回体负载

JSON 示例

<?php
$apiProblem = new ApiProblem(
    'http://api-problem.domain.com/some-url.html',
    'Bad Request',
    400,
    'some detail',
    'http://domain.com/this-request'
);
$apiProblem->sendHTTPResponse(ApiProblem::FORMAT_JSON);

结果

HTTP/1.0 400 Bad Request
Access-Control-Allow-Origin: *
Content-Type: application/api-problem+json
Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html" title="Bad Request"

{
    "problemType": "http://api-problem.domain.com/some-url.html",
    "title": "Bad Request",
    "httpStatus": 400,
    "detail": "some detail",
    "problemInstance": "http://domain.com/this-request"
}

XML 示例

<?php
try {
  throw new ApiProblem(
      'http://api-problem.domain.com/some-url.html',
      'Bad Request',
      400,
      'some detail',
      'http://domain.com/this-request'
  );
} catch (ApiProblem $e) {
  $e->sendHTTPResponse(ApiProblem::FORMAT_XML);
}

结果

HTTP/1.0 400 Bad Request
Access-Control-Allow-Origin: *
Content-Type: application/api-problem+xml
Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html"; title="Bad Request"


<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:draft:nottingham-http-problem">
    <problemType>http://api-problem.domain.com/some-url.html</problemType>
    <title>Bad Request</title>
    <httpStatus>400</httpStatus>
    <detail>some detail</detail>
    <problemInstance>http://domain.com/this-request</problemInstance>
</problem>

添加额外的头信息，例如 CORS、Auth 等

<?php
$apiProblem = new ApiProblem(
    'http://api-problem.domain.com/some-url.html',
    'Unauthorized',
    401,
    'some detail',
    'http://domain.com/this-request'
);

$apiProblem->setHeader('Access-Control-Allow-Origin', '*');
$apiProblem->setHeader('WWW-Authenticate', 'bearer realm="my_realm"');
$apiProblem->sendHTTPResponse(ApiProblem::FORMAT_JSON);

结果

HTTP/1.0 401 Unauthorized
Access-Control-Allow-Origin: *
WWW-Authenticate: bearer realm="my_realm"
Content-Type: application/api-problem+json
Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html" title="Bad Request"

{
    "problemType": "http://api-problem.domain.com/some-url.html",
    "title": "Unauthorized",
    "httpStatus": 401,
    "detail": "some detail",
    "problemInstance": "http://domain.com/this-request"
}

向问题实例添加扩展数据

<?php
$apiProblem = new ApiProblem(
    'http://api-problem.domain.com/some-url.html',
    'Unauthorized',
    401,
    'some detail',
    'http://domain.com/this-request'
);


$apiProblem->setExtensionData('ext_test', 'etx_test_value');
$apiProblem->setExtensionData('ext_test_array_i', array('a' => 'a_d', 'b' => 'b_d', 'c' => 'c_d'));
$apiProblem->setExtensionData('ext_test_array_ni', array('a', 'b', 'c'));
$apiProblem->sendHTTPResponse(ApiProblem::FORMAT_JSON);

结果

HTTP/1.0 401 Unauthorized
Content-Type: application/api-problem+json
Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html" title="Bad Request"

{
    "problemType": "http://api-problem.domain.com/some-url.html",
    "title": "Unauthorized",
    "httpStatus": 401,
    "detail": "some detail",
    "problemInstance": "http://domain.com/this-request",
    "ext_test":"etx_test_value",
    "ext_test_array_i":{
        "a":"a_d",
        "b":"b_d",
        "c":"c_d"
    }
    "ext_test_array_ni":[
        "a",
        "b",
        "c"
    ]
}