README

A 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 实例，您可以通过getter获取 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常见异常的信息。

预期的异常

通常，您应该预期任何setter方法可能会抛出 \InvalidArgumentException。在使用PHP基本HTTP客户端时，可能会抛出以下异常。

在配置 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客户端采用MIT许可证。

chroma-x / json-http-client

维护者

详细信息