README

A PSR-7/PSR-17/PSR-18 HTTP message/client implementation.

Documentation

An API documentation created with phpDocumentor can be found at https://chillerlan.github.io/php-httpinterface/ (WIP).

Requirements

• PHP 8.4+
  • ext-curl
  • from dependencies:
    • ext-fileinfo
    • ext-intl
    • ext-json
    • ext-mbstring
    • ext-simplexml
    • ext-zlib

Installation with composer

Terminal

composer require chillerlan/php-httpinterface

composer.json

{
	"require": {
		"php": "^8.4",
		"chillerlan/php-httpinterface": "dev-main#<commit_hash>"
	}
}

Note: replace dev-main with a version constraint, e.g. ^7.0 - see releases for valid versions.

Profit!

Quickstart

The HTTP clients CurlClient and StreamClient are invoked with a ResponseFactoryInterface instance as the first parameter, followed by optional HTTPOptions and PSR-3 LoggerInterface instances. You can then send a request via the implemented PSR-18 method ClientInterface::sendRequest(), using a PSR-7 RequestInterface and expect a PSR-7 ResponseInterface.

CurlClient, StreamClient

$options                      = new HTTPOptions;
$options->user_agent          = 'my cool user agent 1.0';
$options->ca_info             = '/path/to/cacert.pem';
$options->dns_over_https      = 'https://cloudflare-dns.com/dns-query';
$options->curl_check_OCSP     = true;
$options->curl_check_doh_OCSP = true;

$httpClient = new CurlClient($responseFactory, $options, $logger);
$request    = $requestFactory->createRequest('GET', 'https://www.example.com?foo=bar');

$httpClient->sendRequest($request);

CurlMultiClient

The CurlMultiClient client implements asynchronous multi requests ("rolling-curl"). It needs a MultiResponseHandlerInterface that parses the incoming responses, the callback may return a failed request to the stack:

$handler = new class () implements MultiResponseHandlerInterface{

	public function handleResponse(
		ResponseInterface $response,  // the incoming response
		RequestInterface  $request,   // the corresponding request
		int               $id,        // the request id
		array|null        $curl_info, // the curl_getinfo() result for this request
	):RequestInterface|null{
	
		if($response->getStatusCode() !== 200){
			// return the failed request back to the stack
			return $request;
		}
		
		try{
			$body = $response->getBody();
			
			// the response body is empty for some reason, we pretend that's fine and exit
			if($body->getSize() === 0){
				return null;
			}
			
			// parse the response body, store the result etc.
			$data = $body->getContents();
			
			// save data to file, database or whatever...
			// ...
	
		}
		catch(Throwable){
			// something went wrong, return the request to the stack for another try
			return $request;
		}
		
		// everything ok, nothing to return
		return null;
	}

};

You can then invoke the multi request client - the MultiResponseHandlerInterface and ResponseFactoryInterface are mandatory, HTTPOptions and LoggerInterface are optional:

$options              = new HTTPOptions;
$options->ca_info     = '/path/to/cacert.pem';
$options->user_agent  = 'my cool user agent 1.0';
$options->sleep       = 750000; // microseconds, see usleep()
$options->window_size = 5;
$options->retries     = 1;

$multiClient = new CurlMultiClient($handler, $responseFactory, $options, $logger);

// create and add the requests
foreach(['..', '...', '....'] as $item){
	$multiClient->addRequest($factory->createRequest('GET', $endpoint.'/'.$item));
}

// process the queue
$multiClient->process();

Auto generated API documentation

The API documentation can be auto generated with phpDocumentor. There is an online version available via the gh-pages branch that is automatically deployed on each push to main.

Locally created docs will appear in the directory .build/phpdocs/. If you'd like to create local docs, please follow these steps:

• download phpDocumentor v3+ as .phar archive
• run it in the repository root directory:
  • on Windows c:\path\to\php.exe c:\path\to\phpDocumentor.phar --config=phpdoc.xml
  • on Linux just php /path/to/phpDocumentor.phar --config=phpdoc.xml
• open index.html in a browser
• profit!

Disclaimer

Use at your own risk!