README

JSON HTTP客户端库。此项目也是扩展PHP基本HTTP客户端的参考实现。

安装

{
   	"require": {
        "chroma-x/json-http-client": "~4.0"
    }
}

使用

自动加载和命名空间

require_once('path/to/vendor/autoload.php');

简单使用

准备HTTP客户端

use ChromaX\JsonHttpClient;
use ChromaX\BasicHttpClient\Request\Authentication;
use ChromaX\BasicHttpClient\Request\Message;

// Instantiating a basic HTTP client with the endpoints URL
// If the endpoint uses the `HTTPS` schema a `HttpsTransport` instance will be used automatically.
$client = new JsonHttpClient\JsonHttpClient('http://requestb.in/1aipzl31');

// Adding an authentication method
$client
	->getRequest()
	->addAuthentication(new Authentication\BasicAuthentication('username', 'password'));

执行请求并读取响应

无体请求（GET、HEAD和DELETE）

执行以下带有附加查询参数的GET请求

$response = $client->get(array(
	'paramName1' => 'paramValue1',
	'paramName2' => 'paramValue2'
));

将生成以下HTTP请求。

GET /1aipzl31?paramName1=paramValue1&paramName2=paramValue2 HTTP/1.1
Host: requestb.in
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
User-Agent: PHP Basic HTTP Client 1.0
Accept: application/json
Content-Type: application/json

相同的机制可用于执行HEAD和DELETE请求，这些都是无体的。

带体请求（POST、PUT、PATCH）

执行以下带有正文数据的POST请求

$response = $client->post(array(
	'paramName1' => 'paramValue1',
	'paramName2' => 'paramValue2',
	'paramName3' => array(
		'key1' => 'value1',
		'key2' => 'value2'
	)
));

将生成以下HTTP请求。

POST /1aipzl31?paramName1=paramValue1&paramName2=paramValue2 HTTP/1.1
Host: requestb.in
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
User-Agent: PHP Basic HTTP Client 1.0
Accept: application/json
Content-Type: application/json
Content-Length: 102

{"paramName1":"paramValue1","paramName2":"paramValue2","paramName3":{"key1":"value1","key2":"value2"}}

相同的机制可用于执行PUT和PATCH请求，这些都是带体的。

详细使用方法

以下示例显示了带有更详细配置的使用方法。

配置HTTP传输实例

use ChromaX\BasicHttpClient\Request\Transport\HttpTransport;

// Configuring a Transport instance
$transport = new HttpTransport();
$transport
	->setHttpVersion(HttpTransport::HTTP_VERSION_1_1)
	->setTimeout(5)
	->setReuseConnection(true)
	->setAllowCaching(true)
	->setFollowRedirects(true)
	->setMaxRedirects(10);

配置HTTPS传输实例

use ChromaX\BasicHttpClient\Request\Transport\HttpsTransport;

// Configuring a Transport instance
$transport = new HttpsTransport();
$transport
	->setHttpVersion(HttpsTransport::HTTP_VERSION_1_1)
	->setTimeout(5)
	->setReuseConnection(true)
	->setAllowCaching(true)
	->setFollowRedirects(true)
	->setMaxRedirects(10)
	->setVerifyPeer(true);

配置带有正文的消息实例

use ChromaX\BasicHttpClient\Request\Message\Cookie\Cookie;
use ChromaX\BasicHttpClient\Request\Message\Header\Header;
use ChromaX\BasicHttpClient\Request\Message\Message;
use ChromaX\JsonHttpClient\Request\Message\Body\JsonBody;

// Configuring a message Body instance
$messageBody = new JsonBody(array(
	'paramName1' => 'paramValue1',
	'paramName2' => 'paramValue2',
	'paramName3' => array(
		'key1' => 'value1',
		'key2' => 'value2'
	)
));

// Configuring a Message instance
$message = new Message();
$message
	->addHeader(new Header('Content-Type', array('application/json')))
	->addHeader(new Header('Accept', array('application/json')))
	->addHeader(new Header('Runscope-Bucket-Auth', array('7a64dde7-74d5-4eed-b170-a2ab406eff08')))
	->addCookie(new Cookie('PHPSESSID', '<MY_SESSION_ID>'))
	->setBody($messageBody);

消息和请求头实例

请注意，头部有一些不寻常的行为。头部名称具有统一的命名方式，因此以下三个获取器调用将产生相同的结果。

$header1 = $message->getHeaderByName('Content-Type');
$header2 = $message->getHeaderByName('content-type');
$header3 = $message->getHeaderByName('CONTENT-Type');

为了允许使用相同名称的多个请求头，方法addAdditionalHeader提供了这样的逻辑。

// Add or replace a request header
$message->addHeader(new Header('Custom-Header', array('CustomHeaderValue')));
// Add a request header and keep the existing one untouched
$message->addAdditionalHeader(new Header('Custom-Header', array('AnotherCustomHeaderValue')));

配置端点URL，构建请求实例并执行HTTP请求

有关URL对象使用的更多信息，请参阅PHP URL Util项目。

use ChromaX\BasicHttpClient\Request\Authentication\BasicAuthentication;
use ChromaX\JsonHttpClient\Request\JsonRequest;
use ChromaX\UrlUtil\Url;

// Setting up the endpoints URL
$url = new Url('https://john:secret@yourapihere-com-98yq3775xff0.runscope.net:443/path/to/resource?arg1=123#fragment');

// Configuring and performing a Request
$request = new JsonRequest();
$request
	->setUserAgent('PHP JSON HTTP Client Test 1.0')
	->setUrl($url)
	->addAuthentication(new BasicAuthentication('username', 'password'))
	->setMethod(JsonRequest::REQUEST_METHOD_POST)
	->setTransport($transport)
	->setMessage($message)
	->perform();

生成的HTTP请求如下。

POST /?paramName1=paramValue1&paramName2=paramValue2 HTTP/1.1
Host: yourapihere-com-98yq3775xff0.runscope.net
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
User-Agent: PHP JSON HTTP Client Test 1.0
Cookie: PHPSESSID=<MY_SESSION_ID>
Content-Type: application/json
Accept: application/json
Runscope-Bucket-Auth: 7a64dde7-74d5-4eed-b170-a2ab406eff08
Content-Length: 102

{"paramName1":"paramValue1","paramName2":"paramValue2","paramName3":{"key1":"value1","key2":"value2"}}

认证方法的使用

您可以为每个请求实例添加一个或多个认证实例。目前，此项目提供了HTTP基本认证和SSL客户端证书认证的类。

HTTP基本认证

所需的凭证是一个用户名和一个密码，它们作为参数传递给类构造函数。

use ChromaX\BasicHttpClient\Request\Authentication\BasicAuthentication;
use ChromaX\JsonHttpClient\Request\JsonRequest;

// Configuring the authentication
$basicAuthentication = new BasicAuthentication('username', 'password');

// Adding the authentication instance to the Request
$request = new JsonRequest();
$response = $request->addAuthentication($basicAuthentication);

SSL客户端证书认证

所需的凭证是一个证书颁发机构证书、一个客户端证书以及用于解密客户端证书的密码，这些凭证作为参数传递给类构造函数。

use ChromaX\BasicHttpClient\Request\Authentication\ClientCertificateAuthentication;
use ChromaX\JsonHttpClient\Request\JsonRequest;

// Configuring the authentication
$clientCertificateAuthentication = new ClientCertificateAuthentication(
	'/var/www/project/clientCert/ca.crt',
	'/var/www/project/clientCert/client.crt',
	'clientCertPassword'
);

// Adding the authentication instance to the Request
$request = new JsonRequest();
$response = $request->addAuthentication($clientCertificateAuthentication);

从结果响应对象读取

获取响应对象

如果使用JsonHttpClient，则响应对象由上述终止方法返回。如果直接使用JsonRequest实例，您可以通过获取器获取JsonResponse对象。

// Getting the response ChromaX\BasicHttpClient\Response\JsonResponse object
$response = $request->getResponse();

// Reading the HTTP status code as integer; will return `200`
echo print_r($response->getStatusCode(), true) . PHP_EOL;

// Reading the HTTP status text as string; will return `HTTP/1.1 200 OK`
echo print_r($response->getStatusText(), true) . PHP_EOL;

// Reading the HTTP response headers as array of ChromaX\BasicHttpClient\Response\Header\Header objects
echo print_r($response->getHeaders(), true) . PHP_EOL;

// Reading the HTTP response body as associative array
echo print_r($response->getBody(), true) . PHP_EOL;

获取有效的请求信息

请求成功执行后，有效的请求信息会跟踪回JsonRequest对象。它们可以按以下方式访问。

// Getting the effective endpoint URL including the query parameters
echo print_r($request->getEffectiveEndpoint(), true) . PHP_EOL;

// Getting the effective HTTP status, f.e. `POST /?paramName1=paramValue1&paramName2=paramValue2&paramName3=1&paramName4=42 HTTP/1.1`
echo print_r($request->getEffectiveStatus(), true) . PHP_EOL;

// Getting the effective raw request headers as string
echo print_r($request->getEffectiveRawHeader(), true) . PHP_EOL;

// Getting the effective request headers as array of `ChromaX\BasicHttpClient\Request\Message\Header\Header` objects
echo print_r($request->getEffectiveHeaders(), true) . PHP_EOL.PHP_EOL;

获取一些事务统计信息

// Getting the statistics ChromaX\BasicHttpClient\Response\Statistics\Statistics object
$statistics = $request->getResponse()->getStatistics();

// Reading the redirection URL if the server responds with an redirect HTTP header and 
// followRedirects is set to false
echo print_r($statistics->getRedirectEndpoint(), true).PHP_EOL;

// Reading the numbers of redirection as integer
echo print_r($statistics->getRedirectCount(), true).PHP_EOL;

// Getting the time in seconds the redirect utilized as float
echo print_r($statistics->getRedirectTime(), true).PHP_EOL;

// Getting the time in seconds that was utilized until the connection was established
echo print_r($statistics->getConnectionEstablishTime(), true).PHP_EOL;

// Getting the time in seconds that was utilized until the DNS hostname lookup was done
echo print_r($statistics->getHostLookupTime(), true).PHP_EOL;

// Getting the time in seconds that was utilized before the first data was sent
echo print_r($statistics->getPreTransferTime(), true).PHP_EOL;

// Getting the time in seconds that was utilized before the first data was received
echo print_r($statistics->getStartTransferTime(), true).PHP_EOL;

// Getting the time in seconds that was utilized to perfom the request an read the response
echo print_r($statistics->getTotalTime(), true).PHP_EOL;

异常处理

PHP JSON HTTP客户端提供了不同的异常，这些异常也由PHP Common Exceptions项目提供，以便于正确处理。
您可以在Github上的PHP Common Exceptions找到更多相关信息。

可能出现的异常

通常，您应该预料到任何setter方法都可能抛出\InvalidArgumentException异常。在使用PHP Basic HTTP Client时，可能会抛出以下异常：

在配置ClientCertificateAuthentication实例时抛出ChromaX\CommonException\IoException\FileNotFoundException
在配置ClientCertificateAuthentication实例时抛出ChromaX\CommonException\IoException\FileReadableException
执行请求时抛出ChromaX\BasicHttpClient\Exception\HttpRequestAuthenticationException
执行请求时抛出ChromaX\BasicHttpClient\Exception\HttpRequestException
执行请求时抛出ChromaX\CommonException\NetworkException\ConnectionTimeoutException
执行请求时抛出ChromaX\CommonException\NetworkException\CurlException
如果解析JSON响应体失败，抛出ChromaX\BasicHttpClient\Exception\HttpResponseException

贡献

对我们项目的贡献总是非常受欢迎。
但：请遵循在CONTRIBUTING.md文档中写明的贡献指南。

许可证

PHP JSON HTTP Client遵循MIT许可证。

markenwerk / json-http-client

维护者

详细信息