AMPHP HTTP Client

https://github.com/amphp/http-client
Admin
An advanced asynchronous HTTP client library for PHP enabling efficient, non-blocking, and...
Tokens:63,448
Snippets:456
Trust Score:9.8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Include Artax autoloader

Source: https://github.com/amphp/http-client/wiki/Getting-Up-and-Running

Include the autoloader file from the vendor directory to start using Artax after downloading via git or installing with Composer.

```php
<?php
require '/hard/path/to/artax/vendor/autoload.php';
```

--------------------------------

### Install amphp/http-client via Composer

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Install the package as a Composer dependency. Optionally install the nghttp2 library to use FFI for improved performance and reduced memory usage.

```bash
composer require amphp/http-client
```

--------------------------------

### Track download speed with Client::EVENT_WRITE listener

Source: https://github.com/amphp/http-client/wiki/Client-Events

Example from the EVENT_READ section showing how to track download speed in real time by adding a listener for Client::EVENT_WRITE. The listener receives $key, $data, $bytes, and $info parameters; $info['avgDownKbps'] provides the average download speed in KB/s. Note that the example uses EVENT_WRITE even though the section is about EVENT_READ, and the output echoes the bytes read and average speed.

```php
<?php
use Spl\HashingMediator,
    Artax\Client;

$eventMediator = new HashingMediator;
$eventMediator->addListener(Client::EVENT_WRITE, function($key, $data, $bytes, $info) {
    echo "($key) $bytes bytes read -- ";
    echo "average download speed: " . $info['avgDownKbps'] . ' KB/s' . PHP_EOL;
});

```

--------------------------------

### Simple GET request with Artax\Client

Source: https://github.com/amphp/http-client/wiki/Basic-Client-Usage

Creates an Artax client and sends a GET request to http://example.com, printing the response body. The request transparently redirects to http://www.iana.org/domains/example/. Artax normalizes headers like User-Agent, Host, Connection, Accept-Encoding, Content-Length, and Transfer-Encoding.

```php
<?php

$client = new Artax\Client();
try {
    $response = $client->send('http://example.com');
    echo $response->getBody();
} catch (Artax\ClientException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Basic GET request with HttpClientBuilder

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Creates a default HTTP client and sends a GET request to a URL. Standard headers like Accept, Connection, or Host are added automatically if not present. The response status, headers, and body are output.

```php
use Amp\Http\Client\HttpClientBuilder;

$client = HttpClientBuilder::buildDefault();

$response = $client->request(new Request("https://httpbin.org/get"));

var_dump($response->getStatus());
var_dump($response->getHeaders());
var_dump($response->getBody()->buffer());
```

--------------------------------

### Clone Artax repository with --recursive

Source: https://github.com/amphp/http-client/wiki/Installation

Use this command to clone the latest Artax source from GitHub. The --recursive option automatically installs the PHP-Datastructures dependency.

```bash
$ git clone --recursive git://github.com/rdlowrey/Artax.git
```

--------------------------------

### Raw request message for simple GET

Source: https://github.com/amphp/http-client/wiki/Basic-Client-Usage

Shows the raw HTTP request message that the client sends for the simple GET example. Includes the request line and normalized headers.

```http
GET / HTTP/1.1
User-Agent: Artax/1.0.0 (PHP5.3+)
Host: example.com
```

--------------------------------

### Configure interceptors with HttpClientBuilder

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Build a client with request and response header interceptors. The example adds 'x-foo' to requests and 'x-tea' to responses, then buffers the response body.

```php
use Amp\Http\Client\Client;
use Amp\Http\Client\HttpClientBuilder;
use Amp\Http\Client\Interceptor\SetRequestHeader;
use Amp\Http\Client\Interceptor\SetResponseHeader;
use Amp\Http\Client\Request;

$client = (new HttpClientBuilder)
    ->intercept(new SetRequestHeader('x-foo', 'bar'))
    ->intercept(new SetResponseHeader('x-tea', 'now'))
    ->build();

$response = $client->request(new Request("https://httpbin.org/get"));
$body = $response->getBody()->buffer();
```

--------------------------------

### Iterate over redirection chain with Artax\ClientResponse

Source: https://github.com/amphp/http-client/wiki/How-it-Works

After a redirect, use next() to advance to the next response in the chain, then access its start line and headers. The example shows output from a 302 response.

```php
<?php
// redirects to http://www.iana.org/domains/example/
$response = $client->send('http://example.com');

$response->next(); // advance the pointer to the next response in the chain

echo $response->getStartLine() . PHP_EOL;
foreach ($response->getAllHeaders() as $header) {
    echo "$header\r\n";
}
```

```http
HTTP/1.0 302 Found
Server: BigIP
Connection: Keep-Alive
Content-Length: 0
Location: http://www.iana.org/domains/example/
```

--------------------------------

### Request::__construct(string $uri, string $method = 'GET')

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Creates a new Request object with the given URI and optional HTTP method. The method defaults to GET.

```APIDOC
## Request::__construct(string $uri, string $method = 'GET')

### Description
Creates a new Request object with the given URI and optional HTTP method. The method defaults to GET.

### Method
__construct

### Endpoint
Request::__construct(string $uri, string $method = 'GET')

### Parameters
#### Request Body
- **$uri** (string) - Required - The absolute request URI
- **$method** (string) - Optional - The HTTP method, defaults to 'GET'

### Request Example
```php
$request = new Request("https://httpbin.org/post", "POST");
```

### Response
#### Success Response
- **Request** - The created Request object
```

--------------------------------

### Custom autoloader for Artax

Source: https://github.com/amphp/http-client/wiki/Getting-Up-and-Running

Define a custom autoloader that loads Artax classes from the src directory, using a constant for the system directory.

```php
<?php
define('ARTAX_SYSTEM_DIR', '/hard/path/to/artax');
spl_autoload_register(function($class) {
    if (0 === strpos($class, 'Artax\\')) {
        $class = str_replace('\\', DIRECTORY_SEPARATOR, $class);
        require ARTAX_SYSTEM_DIR . "/src/$class.php";
    }
});
```

--------------------------------

### Retrieve response status and reason with getStatus() and getReason()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Use after a request to get the HTTP status code as an integer and the optional reason phrase. The response is available once headers are received.

```php
$response = $client->request($request);

var_dump($response->getStatus(), $response->getReason());
```

--------------------------------

### Raw HTTP response message with redirect

Source: https://github.com/amphp/http-client/wiki/An-HTTP-Primer

Shows the HTTP response message from the server, including the start line, headers, and no entity body. Indicates a 302 redirect with a Location header.

```http
HTTP/1.0 302 Found
Location: http://www.iana.org/domains/example/
Server: BigIP
Connection: Keep-Alive
Content-Length: 0
```

--------------------------------

### Log HTTP Archive with LogHttpArchive

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Use the LogHttpArchive event listener to log all requests and responses with timing details to an HTTP archive (HAR) file. The example builds an HTTP client with the listener and then performs a request. Be cautious: log files may contain sensitive information in URLs or headers if shared with third parties.

```php
use Amp\Http\Client\HttpClientBuilder;
use Amp\Http\Client\EventListener\LogHttpArchive;

$httpClient = (new HttpClientBuilder)
    ->listen(new LogHttpArchive('/tmp/http-client.har'))
    ->build();

$httpClient->request(...);
```

--------------------------------

### Retrieve response protocol version with getProtocolVersion()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Use to get the HTTP protocol version (e.g., '1.1' or '2') of the response.

```php
$response = $client->request($request);

var_dump($response->getProtocolVersion());
```

--------------------------------

### PSR-0 autoloading with SplClassLoader

Source: https://github.com/amphp/http-client/wiki/Getting-Up-and-Running

Alternative to including autoload.php: use a PSR-0-compatible SplClassLoader for Artax. Note that you still need an autoloader for PHP-Datastructures.

```php
<?php
// You still need to install an autoloader for PHP-Datastructures if you do this!
$loader = new SplClassLoader('Artax', '/hard/path/to/artax/src');
$loader->register();
```

--------------------------------

### Response Header Methods

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Provides methods to access response headers: hasHeader(), getHeader(), getHeaderArray(), and getHeaders(). These allow checking presence, retrieving single or multiple values, and getting all headers as an associative array.

```APIDOC
## Response Header Methods

### Description
Provides methods to access response headers: hasHeader(), getHeader(), getHeaderArray(), and getHeaders(). These allow checking presence, retrieving single or multiple values, and getting all headers as an associative array.

### Methods
- `hasHeader(string $name): bool` - Returns whether a given header is present.
- `getHeader(string $name): ?string` - Returns the first header with the given name or null if not present.
- `getHeaderArray(string $name): array` - Returns all headers with the given name, possibly an empty array.
- `getHeaders(): array` - Returns all headers as an associative array.

### Parameters
- **name** (string) - Required - The header name to query.

### Request Example
```php
$response = $client->request($request);
var_dump($response->hasHeader('content-type'));
var_dump($response->getHeader('content-type'));
var_dump($response->getHeaderArray('set-cookie'));
var_dump($response->getHeaders());
```

### Response
#### Success Response (200)
- **hasHeader** (bool) - Whether the header exists.
- **getHeader** (string|null) - The first header value or null.
- **getHeaderArray** (array) - All header values.
- **getHeaders** (array) - Associative array of all headers.

#### Response Example
```php
bool(true)
string(24) "application/json"
array(2) { [0]=> string(10) "session=abc" [1]=> string(10) "theme=dark" }
array(2) { ["content-type"]=> array(1) { [0]=> string(24) "application/json" } ["set-cookie"]=> array(2) { [0]=> string(10) "session=abc" [1]=> string(10) "theme=dark" } }
```
```

--------------------------------

### Raw HTTP message for form-encoded POST

Source: https://github.com/amphp/http-client/wiki/Basic-Client-Usage

Shows the raw HTTP message sent by the client for the form-encoded POST example, including headers and body.

```http
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
User-Agent: Artax/1.0.0 (PHP5.3+)
Host: example.com
Content-Length: 16

foo=bar&baz=boom
```

--------------------------------

### Follow Location headers for 3xx and 2xx responses

Source: https://github.com/amphp/http-client/wiki/Setting-Client-Attributes

Configures the client to follow Location headers for all 3xx and 2xx responses to GET or HEAD requests by combining the FOLLOW_LOCATION_ON_3XX and FOLLOW_LOCATION_ON_2XX flags.

```php
<?php
$client->setAttribute(
    Client::ATTR_FOLLOW_LOCATION,
    Client::FOLLOW_LOCATION_ON_3XX | Client::FOLLOW_LOCATION_ON_2XX
);
```

--------------------------------

### Send a simple HTTP request with Artax\Client::send()

Source: https://github.com/amphp/http-client/wiki/How-it-Works

Pass a URI string to Artax\Client::send() to send a GET request. The client internally generates a Request instance for the transfer.

```php
<?php
$client = new Artax\Client();
$response = $client->send('http://www.google.com');
```

--------------------------------

### Assigning request method with StdRequest::setMethod

Source: https://github.com/amphp/http-client/wiki/Differences-From-cURL

Artax's StdRequest can assign a method verb using setMethod(). Defaults to GET if not specified. Method verbs are case-sensitive; the client will not correct capitalization.

```php
<?php
$request = new StdRequest(); // defaults to GET if not specified
$request->setUri('http://example.com');
$request->setMethod('PUT');
$request->setMethod('HEAD');
// and so on ...
```

--------------------------------

### Form-encoded POST request with Artax\Http\StdRequest

Source: https://github.com/amphp/http-client/wiki/Basic-Client-Usage

Builds a POST request with application/x-www-form-urlencoded content type, sets form-encoded body using http_build_query, and sends it. Prints the response start line.

```php
<?php
$client = new Artax\Client();

$request = new Artax\Http\StdRequest();
$request->setUri('http://example.com');
$request->setMethod('POST');
$request->setHeader('Content-Type', 'application/x-www-form-urlencoded');

$postVars = array(
    'foo'=>'bar',
    'baz'=>'boom'
);
$formEncodedVars = http_build_query($postVars);

$request->setBody($formEncodedVars);
try {
    $response = $client->send($request);
    echo $response->getStartLine();
} catch (Artax\ClientException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Set multiple attributes: Client::setAllAttributes

Source: https://github.com/amphp/http-client/wiki/Setting-Client-Attributes

Sets multiple client attributes at once using the setAllAttributes instance method. The example sets the connect timeout to 42 seconds and the host concurrency limit to 3.

```php
<?php
$client->setAllAttributes([
    Client::ATTR_CONNECT_TIMEOUT => 42,
    Client::ATTR_HOST_CONCURRENCY_LIMIT => 3
]);
```

--------------------------------

### PHP Hello World script

Source: https://github.com/amphp/http-client/wiki/An-HTTP-Primer

A minimal PHP script that outputs 'Hello, world!'. PHP automatically constructs the HTTP response message, including headers and body.

```php
<?php
echo "Hello, world!";
```

--------------------------------

### HttpClientBuilder::buildDefault()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Builds a default HttpClient instance. This is the main entry point for creating an HTTP client.

```APIDOC
## HttpClientBuilder::buildDefault()

### Description
Builds a default HttpClient instance. This is the main entry point for creating an HTTP client.

### Method
buildDefault

### Endpoint
HttpClientBuilder::buildDefault()

### Parameters
None

### Request Example
```php
$client = HttpClientBuilder::buildDefault();
```

### Response
#### Success Response
- **HttpClient** - The built HTTP client instance

#### Response Example
```php
$client = HttpClientBuilder::buildDefault();
```
```

--------------------------------

### Set request header with Request::setHeader

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Creates a POST request and sets a custom header 'X-Foobar' to 'Hello World'. The request body is set to 'foobar'.

```php
$request = new Request("https://httpbin.org/post", "POST");
$request->setHeader("X-Foobar", "Hello World");
$request->setBody("foobar");
```

--------------------------------

### Raw HTTP response message with HTML body

Source: https://github.com/amphp/http-client/wiki/An-HTTP-Primer

Shows the final HTTP response message with a 200 OK status, headers, and an entity body containing HTML content.

```http
HTTP/1.1 200 OK
Date: Thu, 25 Oct 2012 01:09:09 GMT
Last-Modified: Wed, 09 Feb 2011 17:13:15 GMT
Vary: Accept-Encoding
Connection: close
Content-Length: 42
Content-Type: text/html; charset=UTF-8

<html xmlns="http://www.w3.org/1999/xhtml">
    ... blah blah blah ...
</html>
```

--------------------------------

### Raw HTTP request message from browser

Source: https://github.com/amphp/http-client/wiki/An-HTTP-Primer

Shows the raw HTTP request message a browser sends when navigating to a URL. Includes the request line, headers, and no entity body.

```http
GET / HTTP/1.1
User-Agent: Mozilla/123456...
Host: example.com
Accept: text/html, text/*;q=0.5, */*;q=0.2
Accept-Language: en-us, en;q=0.8, *;q=0.1
```

--------------------------------

### Setting multiple headers with Request::setAllHeaders

Source: https://github.com/amphp/http-client/wiki/Differences-From-cURL

Alternative syntax to set multiple headers at once using the Request::setAllHeaders method.

```php
<?php
$request->setAllHeaders([
    'Referrer' => 'http://some-referrer.com',
    'Cookie' => 'fruit=apple; colour=red'
]);
```

--------------------------------

### Combine EVENT_REQUEST and EVENT_RESPONSE to add gzip support

Source: https://github.com/amphp/http-client/wiki/Client-Events

Shows how to use event listeners to automatically add gzip to accepted encodings and decompress gzip-encoded responses. The EVENT_REQUEST listener sets the Accept-Encoding header, and the EVENT_RESPONSE listener decompresses the body if Content-Encoding is gzip. Note that EVENT_RESPONSE fires only after redirects are followed.

```php
<?php
use Spl\HashingMediator,
    Artax\Client,
    Artax\ClientBuilder;

$eventMediator = new HashingMediator;
$clientBuilder = new ClientBuilder;
$client = $clientBuilder->build($eventMediator);

// Add gzip to the set of accepted encodings in the request message
$eventMediator->addListener(Client::EVENT_REQUEST, function($key, $request) {
    $request->setHeader('Accept-Encoding', 'gzip, identity');
});

$decompressor = function($response) {
    if (!$response->hasHeader('Content-Encoding')) {
        return;
    }
    if ('gzip' == $response->getHeader('Content-Encoding')) {
        $body = $response->getBody();
        // decompress gzip-encoded body here
        $response->setBody($body);
    }
}

$eventMediator->addListener(
    Client::EVENT_RESPONSE,
    function($key, $response, $stats) use ($decompressor) { $decompressor($response); }
);

$request = new StdRequest('http://www.yahoo.com');
$response = $client->send($request);
```

--------------------------------

### HttpClient::request(Request $request)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Sends an HTTP request and returns the response. The request must be a Request object with a URI and optional method, headers, and body.

```APIDOC
## HttpClient::request(Request $request)

### Description
Sends an HTTP request and returns the response. The request must be a Request object with a URI and optional method, headers, and body.

### Method
request

### Endpoint
HttpClient::request(Request $request)

### Parameters
#### Request Body
- **$request** (Request) - Required - The request object to send

### Request Example
```php
$response = $client->request(new Request("https://httpbin.org/get"));
```

### Response
#### Success Response
- **Response** - The response object containing status, headers, and body

#### Response Example
```php
$response = $client->request(new Request("https://httpbin.org/get"));
var_dump($response->getStatus());
var_dump($response->getHeaders());
var_dump($response->getBody()->buffer());
```
```

--------------------------------

### Response::getRequest(), getOriginalRequest(), getPreviousResponse()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

These methods provide access to the request associated with the response, the original request sent by the client, and previous responses in case of redirects. They are useful for debugging and handling redirects manually.

```APIDOC
## Response::getRequest(), getOriginalRequest(), getPreviousResponse()

### Description
These methods provide access to the request associated with the response, the original request sent by the client, and previous responses in case of redirects. They are useful for debugging and handling redirects manually.

### Methods
- `getRequest(): Request` - Returns the request corresponding to the response (may differ from original due to redirects).
- `getOriginalRequest(): Request` - Returns the original request sent by the client.
- `getPreviousResponse(): ?Response` - Returns the previous response in case of redirects, or null if none.

### Parameters
None

### Request Example
```php
$response = $client->request($request);
$requestUsed = $response->getRequest();
$originalRequest = $response->getOriginalRequest();
$previousResponse = $response->getPreviousResponse();
```

### Response
#### Success Response (200)
- **request** (Request) - The request used for this response.
- **originalRequest** (Request) - The original request.
- **previousResponse** (Response|null) - The previous response or null.

#### Response Example
```php
Request object
Request object
null
```
```

--------------------------------

### Create and send a custom request with Artax\Http\StdRequest

Source: https://github.com/amphp/http-client/wiki/How-it-Works

Build a request instance with Artax\Http\StdRequest, set URI, method, headers, and body, then pass it to Artax\Client::send(). The client normalizes certain headers for correctness.

```php
<?php
$client = new Artax\Client();

$request = new Artax\Http\StdRequest();
$request->setUri('http://www.example.com');
$request->setMethod('PUT');
$request->setAllHeaders(
    'Content-Type' => 'application/json',
    'Content-Length' => strlen($myJson),
    'Connection' => 'close'
);

$request->setBody('{"firstName": "Dan"}');

$response = $client->send($request);
```

--------------------------------

### Request::getMethod()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Returns the request method of the Request object.

```APIDOC
## Request::getMethod()

### Description
Returns the request method of the Request object.

### Method
getMethod

### Endpoint
Request::getMethod()

### Parameters
None

### Request Example
```php
$method = $request->getMethod();
```

### Response
#### Success Response
- **string** - The request method
```

--------------------------------

### Setting and retrieving headers with case-insensitive normalization

Source: https://github.com/amphp/http-client/wiki/On-Headers

Shows how setHeader overrides previous values and how header names are case-insensitive. Demonstrates hasHeader, getCombinedHeader, and iterating getHeaders results.

```php
<?php
$request = new StdRequest;
$request->setHeader('cOnTeNt-LeNgTh', 1);
$request->setHeader('Content-Length', 42);

var_dump($request->hasHeader('CONTENT-LENGTH')); // bool(true)
var_dump($request->getCombinedHeader('content-length')); // 42

foreach ($request->getHeaders('Content-Length') as $header) {
    echo $header->getValue(); // 42
}
```

--------------------------------

### Raw HTTP request message following redirect

Source: https://github.com/amphp/http-client/wiki/An-HTTP-Primer

Shows the new HTTP request message the browser sends after receiving a redirect, using the updated location from the Location header.

```http
GET /domains/example/ HTTP/1.1
User-Agent: Mozilla/123456...
Host: www.iana.org
Accept: text/html, text/*;q=0.5, */*;q=0.2
Accept-Language: en-us, en;q=0.8, *;q=0.1
```

--------------------------------

### Request::getBody()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Returns the request body as an HttpContent instance.

```APIDOC
## Request::getBody()

### Description
Returns the request body as an HttpContent instance.

### Method
getBody

### Endpoint
Request::getBody()

### Parameters
None

### Request Example
```php
$body = $request->getBody();
```

### Response
#### Success Response
- **HttpContent** - The request body
```

--------------------------------

### Setting all headers at once with setAllHeaders

Source: https://github.com/amphp/http-client/wiki/On-Headers

Shows how setAllHeaders clears previously assigned headers before adding new ones. The output demonstrates that My-Header is removed.

```php
<?php
$request->setHeader('My-Header', 42);
$request->setAllHeaders(array(
    'Cookie' => array('foo=bar', 'bar=baz'),
    'Some-Header' => 'Ford Prefect'
});
$request->addHeader('COOKIE', 'someval=mycookie');
```

```text
Cookie: foo=bar
Cookie: bar=baz
COOKIE: someval=mycookie
Some-Header: Ford Prefect
```

--------------------------------

### Set request method with Request::setMethod

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Creates a POST request and changes the method to PUT. The request body is set to 'foobar'.

```php
$request = new Request("https://httpbin.org/post", "POST");
$request->setBody("foobar");
$request->setMethod("PUT");
```

--------------------------------

### Listen to EVENT_WRITE

Source: https://github.com/amphp/http-client/wiki/Client-Events

Registers a listener for the EVENT_WRITE event, which fires each time data is written to the socket. The callback receives the request key, raw data, byte count, and stats, and echoes the raw data.

```php
<?php
use Spl\HashingMediator,
    Artax\Client;

$eventMediator = new HashingMediator;
$eventMediator->addListener(Client::EVENT_WRITE, function($key, $data, $bytes, $stats) {
    echo $data;
});
```

--------------------------------

### Using Request constants for method assignment

Source: https://github.com/amphp/http-client/wiki/Differences-From-cURL

Use built-in Request constants to avoid capitalization errors when setting the method.

```php
<?php
$request = new StdRequest();
$request->setUri('http://example.com');
$request->setMethod(Request::GET);
```

--------------------------------

### Listen to EVENT_REDIRECT

Source: https://github.com/amphp/http-client/wiki/Client-Events

Registers a listener for the EVENT_REDIRECT event, which fires when a redirect occurs. The callback receives the request key, the response causing the redirection, and info, and prints the redirecting URI.

```php
<?php
use Spl\HashingMediator,
    Artax\Client,
    Artax\ClientBuilder;

$eventMediator = new HashingMediator;
$clientBuilder = new ClientBuilder;
$client = $clientBuilder->build($eventMediator);

$eventMediator->addListener(Client::EVENT_REDIRECT, function($key, $response, $info) {
    echo "+ REDIRECTING from ($key): " . $response->getRequestUri() . PHP_EOL;
});
```

--------------------------------

### Set request URI with Request::setUri

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Creates a POST request and changes the URI to https://google.com/. The request body is set to 'foobar'.

```php
$request = new Request("https://httpbin.org/post", "POST");
$request->setBody("foobar");
$request->setUri("https://google.com/");
```

--------------------------------

### Request::getHeaders()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Returns an associative array with keys being header names and values being arrays of header lines.

```APIDOC
## Request::getHeaders()

### Description
Returns an associative array with keys being header names and values being arrays of header lines.

### Method
getHeaders

### Endpoint
Request::getHeaders()

### Parameters
None

### Request Example
```php
$headers = $request->getHeaders();
```

### Response
#### Success Response
- **array** - Associative array of header names to arrays of values
```

--------------------------------

### Set request body with Request::setBody

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Creates a POST request and sets the body to 'foobar'. The body is automatically converted to an HttpContent instance.

```php
$request = new Request("https://httpbin.org/post", "POST");
$request->setBody("foobar");
```

--------------------------------

### Request::getUri()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Returns the request URI of the Request object.

```APIDOC
## Request::getUri()

### Description
Returns the request URI of the Request object.

### Method
getUri

### Endpoint
Request::getUri()

### Parameters
None

### Request Example
```php
$uri = $request->getUri();
```

### Response
#### Success Response
- **string** - The request URI
```

--------------------------------

### Request::getHeader(string $field)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Returns the first header line with the given name or null if no such header exists.

```APIDOC
## Request::getHeader(string $field)

### Description
Returns the first header line with the given name or null if no such header exists.

### Method
getHeader

### Endpoint
Request::getHeader(string $field)

### Parameters
#### Request Body
- **$field** (string) - Required - The header field name

### Request Example
```php
$header = $request->getHeader("X-Foobar");
```

### Response
#### Success Response
- **string|null** - The first header value or null if not found
```

--------------------------------

### Client::ATTR_CONNECT_TIMEOUT

Source: https://github.com/amphp/http-client/wiki/Setting-Client-Attributes

Number of seconds allowed before a connection attempt times out and an Artax\ClientException is thrown.

```APIDOC
## ATTR_CONNECT_TIMEOUT

### Description
Number of seconds allowed before a connection attempt times out and an `Artax\ClientException` is thrown.

### Type
int

### Default
`60`
```

--------------------------------

### Verify Artax requirements with PHP script

Source: https://github.com/amphp/http-client/wiki/Requirements

Checks PHP version, string function overloading, and openssl extension. Exits with an error message if any requirement is not met; prints 'All tests passed!' otherwise.

```php
<?php // verify Artax requirements

if (!defined('PHP_VERSION_ID') || PHP_VERSION_ID < 50300) {
    die(
        'Artax requires PHP 5.3 or higher'
    );
} elseif (extension_loaded('mbstring') && (ini_get('mbstring.func_overload') & 2)) { 
    die(
        'Artax cannot function in the presence of string function overloading ' .
        'with "mbstring.func_overload"'
    );
} elseif (!extension_loaded('openssl')) { 
    die(
        'The PHP openssl extension is not enabled -- Artax\\Client cannot send ' .
        'or receive encrypted HTTP transfers'
    );
}

echo "All tests passed!" . PHP_EOL;
```

--------------------------------

### Basic SSL request with certificate authority file

Source: https://github.com/amphp/http-client/wiki/Basic-Client-Usage

Makes an HTTPS request by setting the Client::ATTR_SSL_CA_FILE attribute to a CA certificate file. Artax verifies peer certificates by default; without this, the connection fails with an Artax\ClientException. The CA file is distributed with Artax and subject to MPL 1.1, GPL v2.0, or LGPL 2.1 licensing.

```php
<?php
use Artax\Client,
    Artax\ClientException,
    Artax\Http\StdRequest;

// This file is distributed with the Artax source
define('CERT_AUTHORITY_FILE', '/hard/path/to/artax/certs/cacert.pem');

$client = new Client();
$client->setAttribute(Client::ATTR_SSL_CA_FILE, CERT_AUTHORITY_FILE);

try {
    $response = $client->send('https://www.bankofamerica.com');
} catch (ClientException $e) {
    echo $e->getMessage();
}
```

--------------------------------

### Setting request headers with cURL

Source: https://github.com/amphp/http-client/wiki/Differences-From-cURL

cURL spreads header values across individual options like CURLOPT_REFERER and CURLOPT_COOKIE.

```php
<?php
// using cURL to set the referrer header
curl_setopt($curlHandle, CURLOPT_REFERER, 'http://some-referrer.com');
curl_setopt($curlHandle, CURLOPT_COOKIE, 'fruit=apple; colour=red');
```

--------------------------------

### Access response data from Artax\ClientResponse

Source: https://github.com/amphp/http-client/wiki/How-it-Works

Use methods like getStatusCode(), hasHeader(), getCombinedHeader(), getAllHeaders(), getBody(), and getRequestUri() to inspect the response. Iterate over the response to access each redirection step.

```php
<?php
$client = new Artax\Client();
$response = $client->request('http://example.com');

// What was the HTTP status code of the response?
echo $response->getStatusCode();

// Does a specific header exist in the response message? If so, what was it's value?
if ($response->hasHeader('Date')) {
    echo $response->getCombinedHeader('Date');
}

// Show me all the headers!
print_r($response->getAllHeaders());

// Output the full contents of the response entity in string form
echo $response->getBody();

// If redirection was used to retrieve the response, what was the final request URI?
echo $response->getRequestUri();

// Access the full response for each pit-stop in a redirection chain:
foreach ($response as $r) {
    echo $r->getRequestUri() . PHP_EOL;
    echo $r->getStartLine() . PHP_EOL;
}
```

--------------------------------

### Setting request headers with Artax

Source: https://github.com/amphp/http-client/wiki/Differences-From-cURL

Artax treats the request as a self-contained entity; add headers directly to the request instance before sending.

```php
<?php
$request->setHeader('Referrer', 'http://some-referrer.com');
$request->setHeader('Cookie', 'fruit=apple; colour=red');
```

--------------------------------

### Response::getStatus()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Retrieves the HTTP status code of the response as an integer. The optional reason phrase can be obtained separately with getReason().

```APIDOC
## Response::getStatus()

### Description
Retrieves the HTTP status code of the response as an integer. The optional reason phrase can be obtained separately with getReason().

### Method
GET

### Endpoint
Response::getStatus()

### Parameters
None

### Request Example
```php
$response = $client->request($request);
var_dump($response->getStatus(), $response->getReason());
```

### Response
#### Success Response (200)
- **status** (int) - The HTTP status code
- **reason** (string|null) - The reason phrase associated with the status

#### Response Example
```php
int(200)
string(2) "OK"
```
```

--------------------------------

### Listen for EVENT_RESPONSE to handle individual responses in parallel

Source: https://github.com/amphp/http-client/wiki/Client-Events

Attaches a listener to the client's EVENT_RESPONSE event to be notified as soon as each response is fully received, even before all multi-requests complete. The listener receives the request key, response, and stats, and prints the status code.

```php
<?php
use Spl\HashingMediator,
    Artax\Client,
    Artax\ClientBuilder;

$eventMediator = new HashingMediator;
$clientBuilder = new ClientBuilder;
$client = $clientBuilder->build($eventMediator);

$eventMediator->addListener(Client::EVENT_RESPONSE, function($requestKey, $response, $stats) {
    echo "`$requestKey` completed with status: " . $response->getStatusCode();
});

$multiResult = $client->sendMulti(array(
    'google' => 'http://www.google.com',
    'yahoo'  => 'http://www.yahoo.com',
    'microsoft' => 'http://www.microsoft.com'
));
```

--------------------------------

### Request::setBody($body)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Sets the request body. Accepted types are string, null, and HttpContent. Strings and null are converted to HttpContent.

```APIDOC
## Request::setBody($body)

### Description
Sets the request body. Accepted types are string, null, and HttpContent. Strings and null are converted to HttpContent.

### Method
setBody

### Endpoint
Request::setBody($body)

### Parameters
#### Request Body
- **$body** (string|null|HttpContent) - Required - The request body

### Request Example
```php
$request->setBody("foobar");
```

### Response
#### Success Response
- **void** - No return value
```

--------------------------------

### Response::getBody()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Returns a Payload object that allows buffering or streaming access to the response body. Use read() to read a single chunk or buffer() to read the entire body.

```APIDOC
## Response::getBody()

### Description
Returns a Payload object that allows buffering or streaming access to the response body. Use read() to read a single chunk or buffer() to read the entire body.

### Method
GET

### Endpoint
Response::getBody()

### Parameters
None

### Request Example
```php
$response = $client->request($request);
$chunk = $response->getBody()->read(); // reads a single chunk
$contents = $response->getBody()->buffer(); // buffers the complete body
```

### Response
#### Success Response (200)
- **body** (Payload) - The response body as a Payload object.

#### Response Example
```php
Payload object
```
```

--------------------------------

### Format of getHeaders() associative array

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Shows the structure returned by getHeaders(): an associative array mapping header names to arrays of values.

```php
[
    "header-1" => [
        "value-1",
        "value-2",
    ],
    "header-2" => [
        "value-1",
    ],
]
```

--------------------------------

### Request::hasHeader(string $field)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Checks whether at least one header line with the given name exists.

```APIDOC
## Request::hasHeader(string $field)

### Description
Checks whether at least one header line with the given name exists.

### Method
hasHeader

### Endpoint
Request::hasHeader(string $field)

### Parameters
#### Request Body
- **$field** (string) - Required - The header field name

### Request Example
```php
$hasHeader = $request->hasHeader("X-Foobar");
```

### Response
#### Success Response
- **bool** - True if the header exists, false otherwise
```

--------------------------------

### Client::EVENT_REQUEST

Source: https://github.com/amphp/http-client/wiki/Client-Events

Broadcast after request headers are normalized, before the socket connection is opened. Listeners can modify the request instance, such as changing headers.

```APIDOC
## EVENT_REQUEST

### Description
Broadcast by the client after request headers have been normalized for transport. This is the final notification before a socket connection is opened and the outbound request message is sent. Listeners may modify the request instance after the send process is initialized.

### Event Name
`Client::EVENT_REQUEST`

### Broadcast Parameters
- **$requestKey** (mixed) - Required - Key denoting which request instigated the event. For single requests via `Client::send`, this is always zero. For `Client::sendMulti`, it matches the key in the original request list.
- **$request** (Artax\Request) - Required - The request instance that can be modified by the listener.

### Listener Signature
```php
function($requestKey, $request) { }
```

### Example
```php
<?php
use Spl\HashingMediator,
    Artax\Client,
    Artax\ClientBuilder,
    Artax\ClientException;

$eventMediator = new HashingMediator;
$clientBuilder = new ClientBuilder;
$client = $clientBuilder->build($eventMediator);

$eventMediator->addListener(Client::EVENT_REQUEST, function($requestKey, $request) {
    $request->setHeader('User-Agent', 'My Custom User-Agent String');
});
try {
    $response = $client->send('http://www.google.com');
} catch (ClientException $e) {
    echo $e;
}
```

### Notes
- No corrections or alterations are made by the client after changes by `EVENT_REQUEST` listeners; invalid data may break the request.
```

--------------------------------

### Response::getProtocolVersion()

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Retrieves the HTTP protocol version of the response. This method is useful for checking whether the response uses HTTP/1.1 or HTTP/2.

```APIDOC
## Response::getProtocolVersion()

### Description
Retrieves the HTTP protocol version of the response. This method is useful for checking whether the response uses HTTP/1.1 or HTTP/2.

### Method
GET

### Endpoint
Response::getProtocolVersion()

### Parameters
None

### Request Example
```php
$response = $client->request($request);
var_dump($response->getProtocolVersion());
```

### Response
#### Success Response (200)
- **protocolVersion** (string) - The HTTP protocol version, e.g., "1.1" or "2"

#### Response Example
```php
string(3) "1.1"
```
```

--------------------------------

### Request::setHeaders(array $headers)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Sets multiple headers at once. The array keys are field names and values are header values or arrays of strings.

```APIDOC
## Request::setHeaders(array $headers)

### Description
Sets multiple headers at once. The array keys are field names and values are header values or arrays of strings.

### Method
setHeaders

### Endpoint
Request::setHeaders(array $headers)

### Parameters
#### Request Body
- **$headers** (array) - Required - Associative array of header names to values or arrays of values

### Request Example
```php
$request->setHeaders([
    "X-Foo" => "bar",
    "X-Baz" => ["qux", "quux"]
]);
```

### Response
#### Success Response
- **void** - No return value
```

--------------------------------

### Setting multiple header values with an array

Source: https://github.com/amphp/http-client/wiki/On-Headers

Shows how to assign multiple values to a single header field using setHeader with an array. The output displays each value as a separate header line.

```php
<?php
$request->setHeader('Cookie', array(
    'lu=Rg3vHJZnehYLjVg7qi3bZjzg',
    'made_write_conn=1295214458',
    'reg_fb_gate=deleted'
));

foreach ($request->getAllHeaders() as $header) {
    echo $header . "\r\n";
}
```

```text
Cookie: lu=Rg3vHJZnehYLjVg7qi3bZjzg
Cookie: made_write_conn=1295214458
Cookie: reg_fb_gate=deleted
```

--------------------------------

### Default SSL settings via Client::setAllAttributes

Source: https://github.com/amphp/http-client/wiki/Transport-Layer-Security

These attribute assignments are equivalent to the default SSL settings for secure https:// transfers. They are applied by default and will be implemented if no SSL settings are manually assigned by the user.

```php
<?php
$client->setAllAttributes([
    Client::ATTR_SSL_VERIFY_PEER => true,
    Client::ATTR_SSL_CA_FILE => '',
    Client::ATTR_SSL_VERIFY_DEPTH => 5,
    Client::ATTR_SSL_CN_MATCH => $request->getHost()
]);
```

--------------------------------

### Request::addHeader(string $field, string $value)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Adds an additional header line without removing existing lines for that field.

```APIDOC
## Request::addHeader(string $field, string $value)

### Description
Adds an additional header line without removing existing lines for that field.

### Method
addHeader

### Endpoint
Request::addHeader(string $field, string $value)

### Parameters
#### Request Body
- **$field** (string) - Required - The header field name
- **$value** (string) - Required - The header value

### Request Example
```php
$request->addHeader("X-Foobar", "Hello World");
```

### Response
#### Success Response
- **void** - No return value
```

--------------------------------

### Client::ATTR_AUTO_REFERER_ON_FOLLOW

Source: https://github.com/amphp/http-client/wiki/Setting-Client-Attributes

Automatically set the Referer header in requests that follow a Location header (redirects). Defaults to true.

```APIDOC
## ATTR_AUTO_REFERER_ON_FOLLOW

### Description
Automatically set the `Referer:` header in requests that follow a `Location:` header (redirects). Defaults to `true`.

### Type
bool

### Default
`true`
```

--------------------------------

### Message::addAllHeaders()

Source: https://github.com/amphp/http-client/wiki/On-Headers

Adds multiple headers to the message, preserving and appending to any previously set header values.

```APIDOC
## Message::addAllHeaders()

### Description
Adds multiple headers to the message, preserving and appending to any previously set header values.

### Method
addAllHeaders

### Parameters
- **$headers** (array) - Required - An associative array mapping header field names to values (string or array of strings).

### Request Example
```php
$request->addAllHeaders(array(
    'Cookie' => array('foo=bar', 'bar=baz'),
    'Some-Header' => 'Ford Prefect'
));
```

### Response
No return value specified.
```

--------------------------------

### Request::setMethod(string $method)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Changes the request method of the Request object.

```APIDOC
## Request::setMethod(string $method)

### Description
Changes the request method of the Request object.

### Method
setMethod

### Endpoint
Request::setMethod(string $method)

### Parameters
#### Request Body
- **$method** (string) - Required - The new HTTP method

### Request Example
```php
$request->setMethod("PUT");
```

### Response
#### Success Response
- **void** - No return value
```

--------------------------------

### Client::ATTR_FOLLOW_LOCATION

Source: https://github.com/amphp/http-client/wiki/Setting-Client-Attributes

A bitmask specifying if and how Location headers should be followed for transparent redirection. Defaults to Client::FOLLOW_LOCATION_ON_3XX.

```APIDOC
## ATTR_FOLLOW_LOCATION

### Description
A bitmask specifying if and how `Location:` headers should be followed for transparent redirection. By default, `Location:` headers for all responses with a `3xx` status code are followed.

### Type
int

### Default
`Client::FOLLOW_LOCATION_ON_3XX`

### Acceptable Values
- `Client::FOLLOW_LOCATION_NONE`
- `Client::FOLLOW_LOCATION_ON_3XX`
- `Client::FOLLOW_LOCATION_ON_2XX`
- `Client::FOLLOW_LOCATION_ON_UNSAFE_METHOD`
- `Client::FOLLOW_LOCATION_ALL`

### Usage Example
```php
<?php
$client->setAttribute(
    Client::ATTR_FOLLOW_LOCATION,
    Client::FOLLOW_LOCATION_ON_3XX | Client::FOLLOW_LOCATION_ON_2XX
);
```
```

--------------------------------

### Client::ATTR_HOST_CONCURRENCY_LIMIT

Source: https://github.com/amphp/http-client/wiki/Setting-Client-Attributes

Number of simultaneous connections allowed to the same host name.

```APIDOC
## ATTR_HOST_CONCURRENCY_LIMIT

### Description
Number of simultaneous connections allowed to the same host name.

### Type
int

### Default
`5`
```

--------------------------------

### Request::setHeader(string $field, string $value)

Source: https://github.com/amphp/http-client/blob/5.x/README.md

Sets a request header, removing any previous values for that field.

```APIDOC
## Request::setHeader(string $field, string $value)

### Description
Sets a request header, removing any previous values for that field.

### Method
setHeader

### Endpoint
Request::setHeader(string $field, string $value)

### Parameters
#### Request Body
- **$field** (string) - Required - The header field name
- **$value** (string) - Required - The header value

### Request Example
```php
$request->setHeader("X-Foobar", "Hello World");
```

### Response
#### Success Response
- **void** - No return value
```

--------------------------------

### Client::setAllAttributes

Source: https://github.com/amphp/http-client/wiki/Setting-Client-Attributes

Sets multiple client attributes at once using an associative array of attribute constants to values.

```APIDOC
## setAllAttributes

### Description
Sets multiple client attributes at once using an associative array of attribute constants to values.

### Method
setAllAttributes

### Parameters
- **attributes** (array) - Required - An associative array mapping attribute constants to their values.

### Request Example
```php
<?php
$client->setAllAttributes([
    Client::ATTR_CONNECT_TIMEOUT => 42,
    Client::ATTR_HOST_CONCURRENCY_LIMIT => 3
]);
```

### Response
No return value.
```
Tokens:
Raw