HTTP Client Library
Lightweight PSR-7 HTTP message interfaces cURL client with support for PSR-17 HTTP factories interfaces., (*1)
Installation
Install via Composer., (*2)
composer require pdeans/http
Usage
The cURL client is built on top of the Laminas Diactoros PSR-7 and PSR-17 implementations., (*3)
Configuring the Client
The client accepts an optional associative array of curl options as the first parameter to configure the cURL client. Please note that the following cURL options cannot be set in order to comply with PSR-7 standards. Instead, these options should be provided as part of the request options:, (*4)
- CURLOPT_CUSTOMREQUEST
- CURLOPT_FOLLOWLOCATION
- CURLOPT_HEADER
- CURLOPT_HTTP_VERSION
- CURLOPT_HTTPHEADER
- CURLOPT_NOBODY
- CURLOPT_POSTFIELDS
- CURLOPT_RETURNTRANSFER
- CURLOPT_URL
- CURLOPT_USERPWD
The following is an example of how to create and configure the client:, (*5)
use pdeans\Http\Client;
$client = new Client();
// With options
$client = new Client([
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => true,
]);
HTTP Requests
The client comes bundled with helper methods to provide a convenient way for issuing the supported HTTP request methods., (*6)
GET, HEAD, and TRACE methods take the following parameters:, (*7)
- String representation of the target url OR a class instance that implements the PSR-7
Psr\Http\Message\UriInterface.
- Associative array of headers
[headerName => headerValue].
POST, PUT, PATCH, OPTIONS, and DELETE methods take the two parameters listed above, plus an optional 3rd parameter for the request body:, (*8)
- String of request body data OR a class instance that implements the PSR-7
Psr\Http\Message\StreamInterface OR a resource.
Request Usage
// GET request with header
$response = $client->get('https://example.com/1', ['custom-header' => 'header/value']);
// GET request without header
$response = $client->get('https://example.com/2');
// HEAD request
$response = $client->head('https://example.com/2');
// TRACE request
$response = $client->trace('https://example.com/2');
$headers = [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Basic ' . base64_encode('username:password'),
];
$data = json_encode(['json' => 'json data']);
// POST request with headers and request body
$response = $client->post('https://example.com/4', $headers, $data);
// PUT request
$response = $client->put('https://example.com/4', $headers, $data);
// PATCH request
$response = $client->patch('https://example.com/4', $headers, $data);
// OPTIONS request
$response = $client->options('https://example.com/4', $headers, $data);
// DELETE request
$response = $client->delete('https://example.com/4', $headers, $data);
If more control over the request is needed, the helper methods can be bypassed and the sendRequest method may be called directly. This method accepts a class instance that implements the PSR-7 Psr\Http\Message\RequestInterface., (*9)
Example GET request using the RequestFactory class instance:, (*10)
use pdeans\Http\Factories\RequestFactory;
$request = (new RequestFactory())->createRequest('GET', 'https://example.com/1');
$response = $client->sendRequest($request);
Example POST request using the Request class instance:, (*11)
use pdeans\Http\Request;
$request = new Request(
uri: 'https://example.com',
method: 'POST',
headers: ['Content-Type' => 'application/json'],
body: $client->getStream(json_encode(['json' => 'json data']))
);
$response = $client->sendRequest($request);
HTTP Responses
Each HTTP request returns a pdeans\Http\Response class instance, which is an implementation of the PSR-7 Psr\Http\Message\ResponseInterface., (*12)
Response Usage
// Issue request
$response = $client->get('https://example.com/1', ['custom-header' => 'header/value']);
// Response body output
echo (string) $response->getBody();
// Response headers output
var_dump($response->getHeaders());
var_dump($response->getHeader('custom-header'));
var_dump($response->hasHeader('custom-header'));
echo $response->getHeaderLine('custom-header');
// Response status code output
echo $response->getStatusCode();
// Response reason phrase output
echo $response->getReasonPhrase();
PSR-17 Factories
The following HTTP factory classes are available and each implement their associated PSR-17 factory interface:, (*13)
-
pdeans\Http\Factories\RequestFactory implements Psr\Http\Message\RequestFactoryInterface
-
pdeans\Http\Factories\ResponseFactory implements Psr\Http\Message\ResponseFactoryInterface
-
pdeans\Http\Factories\ServerRequestFactory implements Psr\Http\Message\ServerRequestFactoryInterface
-
pdeans\Http\Factories\StreamFactory implements Psr\Http\Message\StreamFactoryInterface
-
pdeans\Http\Factories\UploadedFileFactory implements Psr\Http\Message\UploadedFileFactoryInterface
-
pdeans\Http\Factories\UriFactory implements Psr\Http\Message\UriFactoryInterface
Factory Usage
use pdeans\Http\Factories\RequestFactory;
use pdeans\Http\Factories\ResponseFactory;
use pdeans\Http\Factories\ServerRequestFactory;
use pdeans\Http\Factories\StreamFactory;
use pdeans\Http\Factories\UploadedFileFactory;
use pdeans\Http\Factories\UriFactory;
// Psr\Http\Message\RequestFactoryInterface
$requestFactory = new RequestFactory();
// Psr\Http\Message\RequestInterface
$request = $requestFactory->createRequest('GET', 'https://example.com/1');
// Psr\Http\Message\ResponseFactoryInterface
$responseFactory = new ResponseFactory();
// Psr\Http\Message\ResponseInterface
$response = $responseFactory->createResponse();
// Psr\Http\Message\ServerRequestFactoryInterface
$serverRequestFactory = new ServerRequestFactory();
// Psr\Http\Message\ServerRequestInterface
$serverRequest = $serverRequestFactory->createServerRequest('GET', 'https://example.com/2');
// Psr\Http\Message\StreamFactoryInterface
$streamFactory = new StreamFactory();
// Psr\Http\Message\StreamInterface
$stream = $streamFactory->createStream();
$fileStream = $streamFactory->createStreamFromFile('dir/api.json');
$resourceStream = $streamFactory->createStreamFromResource(fopen('php://temp', 'r+'));
// Psr\Http\Message\UploadedFileFactoryInterface
$uploadedFileFactory = new UploadedFileFactory();
// Psr\Http\Message\UploadedFileInterface
$uploadedFile = $uploadedFileFactory->createUploadedFile($fileStream);
// Psr\Http\Message\UriFactoryInterface
$uriFactory = new UriFactory();
// Psr\Http\Message\UriInterface
$uri = $uriFactory->createUri();
Further Reading
As this library is a layer built upon existing libraries and standards, it is encouraged that you read through the documentation of these libraries and standards to get a better understanding of how the various components work., (*14)
Wallogit.com
