Request URL

The URL can be changed using the setUrl method:

$request->setUrl('http://domain.tld'); // static

Note that when the URL is changed, the Host header will be as well.

Request Protocol

With the Request object instantiated, it is possible to set the desired HTTP protocol, through a string or a constant of the Protocol class:

use Framework\HTTP\Protocol;

$request->setProtocol('HTTP/2'); // static
$request->setProtocol(Protocol::HTTP_2); // static

Request Method

By default, the request method is GET. And, it can be changed through the setMethod method, passing a string or a constant from the Method class:

use Framework\HTTP\Method;

$request->setMethod('post'); // static
$request->setMethod(Method::POST); // static

Request Headers

Headers can be passed via the header set methods.

Below we see an example using string and a constant of the RequestHeader class:

use Framework\HTTP\RequestHeader;

$request->setHeader('Content-Type', 'application/json'); // static
$request->setHeader(RequestHeader::CONTENT_TYPE, 'application/json'); // static

To set the Content-Type it is possible to use a method for this:

$request->setContentType('application/json'); // static

$request->setJson($data); // static

$username = 'johndoe';
$password = 'secr3t';
$request->setBasicAuth($username, $password); // static

$token = 'abc123';
$request->setBearerAuth($token); // static

$request->setUserAgent(); // static
$request->setUserAgent('Aplus HTTP Client'); // static

use Framework\HTTP\Cookie;

$cookie = new Cookie('session_id', 'abc123');
$request->setCookie($cookie); // static

Post Forms

To send data as a form you can set an array with fields and values using the setPost method:

$request->setPost([
    'name' => 'John Doe',
    'email' => '[email protected]',
]); // static

Request with Upload

You can upload files with the setFiles method.

In it, you set the name of the array keys as field names and the values can be the path to a file, an instance of CURLFile or CURLStringFile:

$request->setFiles([
    'invoices' => [
        __DIR__ . '/foo/invoice-10001.pdf',
        __DIR__ . '/foo/invoice-10002.pdf',
    ],
    'foo' => new CURLStringFile('foo', 'foo.txt', 'text/plain')
]); // static

Request to Download

When making requests to download files, define a callback in the setDownloadFunction method, with the first parameter receiving the data chunk:

$request->setDownloadFunction(function (string $data) {
    file_put_contents(__DIR__ . '/video.mp4', $data, FILE_APPEND);
}); // static

A simpler way is to use the setDownloadFile function, which requires the file path in the first parameter and allows you to overwrite the file in the second parameter:

$request->setDownloadFile(__DIR__ . '/video.mp4'); // static

Note that when these functions are set the Response body will be set as an empty string.

Synchronous Requests

A request can be made by passing a Request instance in the run method, which will return a Response or throw an Framework\HTTP\Client\RequestException if it fails:

$response = $client->run($request); // Framework\HTTP\Client\Response

If you call the Request's setGetInfo method, it will be possible to obtain information from Curl through the exception's getInfo method:

$request->setGetInfo();

try {
    $response = $client->run($request); // Framework\HTTP\Client\Response
} catch (Framework\HTTP\Client\RequestException $exception) {
    echo $exception->getMessage(); // string
    var_dump($exception->getInfo()); // array
}

Asynchronous Requests

To perform asynchronous requests use the runMulti method, passing an array with request identifiers as keys and Requests as values.

The runMulti method will return a Generator with the request id in the key and a Response, or Response Error, instance as a value.

Responses will be delivered as requests are finalized:

use Framework\HTTP\Client\Client;
use Framework\HTTP\Client\Request;
use Framework\HTTP\Client\ResponseError;

$client = new Client();

$requests = [
    1 => new Request('https://aplus-framework.com'),
    2 => new Request('https://aplus-framework.tld'),
];

foreach($client->runMulti($requests) as $id => $response) {
    if ($response instanceof ResponseError) {
        echo "Request $id has error: ";
        echo $response->getError() . '.<br>';
        continue;
    }
    echo "Request $id responded:";
    echo '<pre>' . htmlentities((string) $response) . '</pre>';
}

In the run method, the Framework\HTTP\Client\RequestException exception is thrown if the connection fails. On the other hand, the runMulti method does not throw exceptions so that requests are not interrupted.

To find out if a request failed, perform a check similar to the code example above.

Response Protocol

With it it is possible to obtain the protocol:

$protocol = $response->getProtocol(); // string

Response Status

Also, you can get the response status:

$response->getStatusCode(); // int
$response->getStatusReason(); // string
$response->getStatus(); // string

Response Headers

It is also possible to get all headers at once:

$headers = $response->getHeaders(); // array

Or, get the headers individually:

use Framework\HTTP\ResponseHeader;

$response->getHeader('Content-Type'); // string or null
$response->getHeader(ResponseHeader::CONTENT_TYPE); // string or null

Response Body

The message body, when set, can be obtained with the getBody method:

$body = $response->getBody(); // string

JSON Response

Also, you can check if the response content type is JSON and get the JSON data as an object or array in PHP:

if ($response->isJson()) {
    $data = $response->getJson(); // object, array or false
}

Response Links

The getLinks method get parsed Link header as array.

To be parsed, links must be in the GitHub REST API format and it is compatible with the Pagination HTTP Header Link.

$links = $response->getLinks(); // array