PHP JSON HTTP Client
, (*1)
A JSON HTTP client library. This project also is the reference implementation for extending the PHP Basic HTTP Client., (*2)
Installation
```{json}
{
"require": {
"chroma-x/json-http-client": "~4.0"
}
}, (*3)
## Usage
### Autoloading and namesapce
```{php}
require_once('path/to/vendor/autoload.php');
Simple usage
Preparing the HTTP client
```{php}
use ChromaX\JsonHttpClient;
use ChromaX\BasicHttpClient\Request\Authentication;
use ChromaX\BasicHttpClient\Request\Message;, (*4)
// 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');, (*5)
// Adding an authentication method
$client
->getRequest()
->addAuthentication(new Authentication\BasicAuthentication('username', 'password'));, (*6)
#### Performing requests and read the response
##### Body-less requests (GET, HEAD and DELETE)
Perfoming the following `GET` request with additional query parameters
```{php}
$response = $client->get(array(
'paramName1' => 'paramValue1',
'paramName2' => 'paramValue2'
));
will result in the following HTTP request., (*7)
```{http}
GET /1aipzl31?paramName1=paramValue1¶mName2=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, (*8)
The same mechanic is offered to perform `HEAD` and `DELETE` requests wich all are body-less.
##### Body-full requests (POST, PUT, PATCH)
Perfoming the following `POST` request with body data
```{php}
$response = $client->post(array(
'paramName1' => 'paramValue1',
'paramName2' => 'paramValue2',
'paramName3' => array(
'key1' => 'value1',
'key2' => 'value2'
)
));
will result in the following HTTP request., (*9)
```{http}
POST /1aipzl31?paramName1=paramValue1¶mName2=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, (*10)
{"paramName1":"paramValue1","paramName2":"paramValue2","paramName3":{"key1":"value1","key2":"value2"}}, (*11)
The same mechanic is offered to perform `PUT` and `PATCH` requests wich all are body-full.
---
### Detailed usage
The following example shows the usage with a more detailed configuration.
#### Configuring a HTTP Transport instance
```{php}
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);
Configuring a HTTPS Transport instance
```{php}
use ChromaX\BasicHttpClient\Request\Transport\HttpsTransport;, (*12)
// 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);, (*13)
#### Configuring a Message instance with Body
```{php}
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);
Message and request Header instances
Please note, that headers have some unusual behaviours. Header names have an uniform way of nomenclature so the following three getter calls would have the same result., (*14)
```{php}
$header1 = $message->getHeaderByName('Content-Type');
$header2 = $message->getHeaderByName('content-type');
$header3 = $message->getHeaderByName('CONTENT-Type');, (*15)
To allow multiple request headers using the same name, the method `addAdditionalHeader` provides such a logic.
```{php}
// 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')));
For more information about the usage of the URL object please take a look at the PHP URL Util project., (*16)
```{php}
use ChromaX\BasicHttpClient\Request\Authentication\BasicAuthentication;
use ChromaX\JsonHttpClient\Request\JsonRequest;
use ChromaX\UrlUtil\Url;, (*17)
// Setting up the endpoints URL
$url = new Url('https://john:secret@yourapihere-com-98yq3775xff0.runscope.net:443/path/to/resource?arg1=123#fragment');, (*18)
// 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();, (*19)
The resulting HTTP request would be the following.
```{http}
POST /?paramName1=paramValue1¶mName2=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"}}
Usage of authentication methods
You can add one or more Authentication instances to every Request instance. At the moment this project provides classes for HTTP Basic Authentication and SSL Client Certificate Authentication., (*20)
HTTP Basic Authentication
Required credentials are a username and a password that get provided to the class constructor as arguments., (*21)
```{php}
use ChromaX\BasicHttpClient\Request\Authentication\BasicAuthentication;
use ChromaX\JsonHttpClient\Request\JsonRequest;, (*22)
// Configuring the authentication
$basicAuthentication = new BasicAuthentication('username', 'password');, (*23)
// Adding the authentication instance to the Request
$request = new JsonRequest();
$response = $request->addAuthentication($basicAuthentication);, (*24)
#### SSL Client Certificate Authentication
Required credentials are a *Certificate Authority Certificate*, a *Client Certificate* and the password that is used to decrypt the Client Certificate that get provided to the class constructor as arguments.
```{php}
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);
Reading from the resulting Response object
Getting the response object
If using the JsonHttpClient the response object is returned by the termination methods listed above. If directly using the JsonRequest instance, you can get the JsonResponse object via a getter., (*25)
```{php}
// Getting the response ChromaX\BasicHttpClient\Response\JsonResponse object
$response = $request->getResponse();, (*26)
// Reading the HTTP status code as integer; will return 200
echo print_r($response->getStatusCode(), true) . PHP_EOL;, (*27)
// Reading the HTTP status text as string; will return HTTP/1.1 200 OK
echo print_r($response->getStatusText(), true) . PHP_EOL;, (*28)
// Reading the HTTP response headers as array of ChromaX\BasicHttpClient\Response\Header\Header objects
echo print_r($response->getHeaders(), true) . PHP_EOL;, (*29)
// Reading the HTTP response body as associative array
echo print_r($response->getBody(), true) . PHP_EOL;, (*30)
---
## Getting effective Request information
After successful performing the request, the effective request information is tracked back to the JsonRequest object. They can get accessed as follows.
```{php}
// 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¶mName2=paramValue2¶mName3=1¶mName4=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 some transactional statistics
```{php}
// Getting the statistics ChromaX\BasicHttpClient\Response\Statistics\Statistics object
$statistics = $request->getResponse()->getStatistics();, (*31)
// 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;, (*32)
// Reading the numbers of redirection as integer
echo print_r($statistics->getRedirectCount(), true).PHP_EOL;, (*33)
// Getting the time in seconds the redirect utilized as float
echo print_r($statistics->getRedirectTime(), true).PHP_EOL;, (*34)
// Getting the time in seconds that was utilized until the connection was established
echo print_r($statistics->getConnectionEstablishTime(), true).PHP_EOL;, (*35)
// Getting the time in seconds that was utilized until the DNS hostname lookup was done
echo print_r($statistics->getHostLookupTime(), true).PHP_EOL;, (*36)
// Getting the time in seconds that was utilized before the first data was sent
echo print_r($statistics->getPreTransferTime(), true).PHP_EOL;, (*37)
// Getting the time in seconds that was utilized before the first data was received
echo print_r($statistics->getStartTransferTime(), true).PHP_EOL;, (*38)
// Getting the time in seconds that was utilized to perfom the request an read the response
echo print_r($statistics->getTotalTime(), true).PHP_EOL;
```, (*39)
Exception handling
PHP JSON HTTP Client provides different exceptions – also provided by the PHP Common Exceptions project – for proper handling.
You can find more information about PHP Common Exceptions at Github., (*40)
Exceptions to be expected
In general you should expect that any setter method could thrown an \InvalidArgumentException. The following exceptions could get thrown while using PHP Basic HTTP Client., (*41)
-
ChromaX\CommonException\IoException\FileNotFoundException on configuring a ClientCertificateAuthenticationinstance
-
ChromaX\CommonException\IoException\FileReadableException on configuring a ClientCertificateAuthenticationinstance
-
ChromaX\BasicHttpClient\Exception\HttpRequestAuthenticationException on performing a request
-
ChromaX\BasicHttpClient\Exception\HttpRequestException on performing a request
-
ChromaX\CommonException\NetworkException\ConnectionTimeoutException on performing a request
-
ChromaX\CommonException\NetworkException\CurlException on performing a request
-
ChromaX\BasicHttpClient\Exception\HttpResponseException if parsing the JSON response body fails
Contribution
Contributing to our projects is always very appreciated.
But: please follow the contribution guidelines written down in the CONTRIBUTING.md document., (*42)
License
PHP JSON HTTP Client is under the MIT license., (*43)
Wallogit.com
