Httpful

https://github.com/nategood/httpful
Admin
Httpful is a simple HTTP client library for PHP 8.0+ with emphasis on readability, simplicity, and...
Tokens:61,901
Snippets:498
Trust Score:7.5
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
### Composer installation configuration

Source: https://github.com/nategood/httpful/blob/master/README.md

Adds the nategood/httpful package to a composer.json file for installation via Composer. The package is PSR-0 compliant and can be used in larger projects.

```json
{
    "require": {
        "nategood/httpful": "*"
    }
}
```

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

### Request::post usage example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Example of creating a POST request with a JSON payload using the static factory.

```php
$req = \Httpful\Request::post('https://api.example.com/items', ['name' => 'x'], 'json');
```

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

### Example using expectsJson and withXTrivialHeader

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Shows how to use the magic __call with expectsJson() and a custom header via withXTrivialHeader().

```php
$response = \Httpful\Request::get($url)->expectsJson()
    ->withXTrivialHeader('Just as a demo')->send();
```

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

### Request::getQuick($uri, $mime = null)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Creates a Request for a GET request and sends it immediately, returning a Response object.

```APIDOC
## Request::getQuick($uri, $mime = null)

### Description
Creates a Request for a GET request and sends it immediately, returning a Response object.

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
- `$uri` (string) - Required - Request URI
- `$mime` (string) - Optional - Mime short name or full type (sets send + expect)

### Returns
`Response` object.

### Example
```php
$response = \Httpful\Request::getQuick('https://api.example.com/users');
```
```

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

### JsonHandler usage examples

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Three usage examples: basic JSON response parsing, registering a handler with decode_as_array to get associative arrays, and error handling for invalid JSON responses.

```php
// basic
$response = \Httpful\Request::get($url)->expectsJson()->send();
$obj = $response->body; // stdClass
```

```php
// decode as array
\Httpful\Httpful::register(\Httpful\Mime::JSON,
    new \Httpful\Handlers\JsonHandler(['decode_as_array' => true]));
$response = \Httpful\Request::get($url)->expectsJson()->send();
$arr = $response->body['event'];
```

```php
// error handling
try {
    \Httpful\Request::get('https://api.example.com/not-json')->expectsJson()->send();
} catch (\Httpful\Exception\JsonParseException $e) {
    echo $e->getMessage(); // 'Unable to parse response as JSON: ' . json_last_error_msg()
}
```

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

### __toString() usage example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/response.md

Shows how to echo a response object, which prints the raw body via __toString().

```php
echo $response; // prints $response->raw_body
```

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

### Request::ini usage example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets a template with strict SSL disabled so future requests use these defaults.

```php
$template = \Httpful\Request::get('https://api.example.com')->withoutStrictSSL();
\Httpful\Request::ini($template); // future requests use these defaults
```

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

### Request::resetIni()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Restores the library default template (GET method, strict SSL off per template).

```APIDOC
## Request::resetIni()

### Description
Restores the library default template (GET method, strict SSL off per template).

### Method
N/A (configuration)

### Endpoint
N/A (SDK method)

### Parameters
None

### Returns
`void`

### Example
```php
\Httpful\Request::resetIni();
```
```

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

### Request::getQuick signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Like get() but sends immediately and returns a Response instead of a Request.

```php
public static function getQuick($uri, $mime = null)
```

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

### whenError usage example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Example of using `whenError` to log errors with a custom function instead of the default `error_log`.

```php
\Request::get($url)->whenError(function ($err) { log_error($err); })->send();
```

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

### Httpful\Bootstrap class with autoloader and handler setup

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

Defines the Bootstrap class with constants and static properties used for autoloading and handler registration. The class provides init(), pharInit(), autoload(), pharAutoload(), and registerHandlers() methods; registerHandlers() is idempotent and registers JsonHandler, XmlHandler, FormHandler, and CsvHandler for their mimes.

```php
class Bootstrap
{
    public const DIR_GLUE = DIRECTORY_SEPARATOR;
    public const NS_GLUE = '\\';
    public static $registered = false;
}
```

```php
$handlers = [
    \Httpful\Mime::JSON => new \Httpful\Handlers\JsonHandler(),
    \Httpful\Mime::XML  => new \Httpful\Handlers\XmlHandler(),
    \Httpful\Mime::FORM => new \Httpful\Handlers\FormHandler(),
    \Httpful\Mime::CSV  => new \Httpful\Handlers\CsvHandler(),
];
```

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

### Request::get()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Static factory method to create a new Request instance with the GET HTTP method. Returns a chainable request builder.

```APIDOC
## Request::get()

### Description
Static factory method to create a new Request instance with the GET HTTP method. Returns a chainable request builder.

### Method
GET

### Endpoint
N/A (factory method)

### Parameters
- **$uri** (string) - Required - The request URI.

### Request Example
```php
$request = \Httpful\Request::get('http://example.com');
```

### Response
Returns a new `Httpful\Request` instance.
```

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

### CsvHandler usage example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Shows fetching a CSV response with expectsCsv() and iterating over rows; each row is an array of fields.

```php
$response = \Httpful\Request::get('https://example.com/data.csv')->expectsCsv()->send();
foreach ($response->body as $row) { /* $row is an array of fields */ }
```

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

### SimpleCsvHandler custom handler example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Example custom handler extending MimeHandlerAdapter. Implements parse using str_getcsv and serialize casting to string. Register with Httpful::register as shown.

```php
class SimpleCsvHandler extends \Httpful\Handlers\MimeHandlerAdapter
{
    public function parse($body) { return str_getcsv($body); }
    public function serialize($payload): string { return (string) $payload; }
}
```

```php
\Httpful\Httpful::register('text/csv', new SimpleCsvHandler());
```

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

### Using Httpful\Request to send a GET request and handle response

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/response.md

Sends a GET request to the GitHub API expecting JSON, checks for errors, and accesses parsed body, content type, headers, and raw body. Demonstrates case-insensitive header lookup and error handling for 4xx/5xx responses.

```php
$response = \Httpful\Request::get('https://api.github.com/users/nategood')
    ->expectsJson()
    ->send();

if ($response->hasErrors()) {           // check 4xx/5xx
    throw new \RuntimeException("HTTP {$response->code}");
}
$name = $response->body->name;          // parsed JSON -> object
$type = $response->content_type;       // 'application/json'
$ua   = $response->headers['Content-Type']; // case-insensitive lookup
echo $response->raw_body;              // raw string
```

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

### Request::resetIni signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Restores the library default template (GET method, strict SSL off per template).

```php
public static function resetIni()
```

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

### Http::safeMethods

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

Returns an array of HTTP methods that are considered safe (i.e., do not modify server state). This includes HEAD, GET, OPTIONS, and TRACE.

```APIDOC
## Http::safeMethods

### Description
Returns an array of HTTP methods that are considered safe (i.e., do not modify server state). This includes HEAD, GET, OPTIONS, and TRACE.

### Method
`public static function safeMethods(): array`

### Return Value
- **array** - List of safe HTTP methods: `['HEAD', 'GET', 'OPTIONS', 'TRACE']`

### Example
```php
$safeMethods = Http::safeMethods();
// Result: ['HEAD', 'GET', 'OPTIONS', 'TRACE']
```
```

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

### FormHandler usage example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Demonstrates sending form data with sendsForm() and parsing a form response with expectsForm(). The response body is an associative array.

```php
$response = \Httpful\Request::post('https://httpbin.org/post', ['a' => 1, 'b' => 2])->sendsForm()->send();
$parsed = \Httpful\Request::get('https://httpbin.org/forms/form')->expectsForm()->send(); // body is array
```

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

### send() usage with error handling

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sends a GET request and prints the response body. Catches ConnectionErrorException and logs the cURL error number and string.

```php
try {
    $response = \Httpful\Request::get($url)->send();
    echo $response->body;
} catch (\Httpful\Exception\ConnectionErrorException $e) {
    error_log("cURL error {$e->getCurlErrorNumber()}: {$e->getCurlErrorString()}");
}
```

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

### Request::get($uri, $mime = null)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Creates a new Request object configured for an HTTP GET request. Optionally sets the MIME type for sending and expecting.

```APIDOC
## Request::get($uri, $mime = null)

### Description
Creates a new Request object configured for an HTTP GET request. Optionally sets the MIME type for sending and expecting.

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
- `$uri` (string) - Required - Request URI
- `$mime` (string) - Optional - Mime short name or full type (sets send + expect)

### Returns
`Request` configured for `Http::GET`.

### Example
```php
$request = \Httpful\Request::get('https://api.example.com/users');
```
```

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

### GitHub API request with custom header and JSON parsing

Source: https://github.com/nategood/httpful/blob/master/README.md

Sends a GET request to the GitHub API with a custom header 'X-Trvial-Header: Just as a demo' and expects JSON response. The response body is parsed as an array of objects, and the user's name and join date are printed.

```php
// Make a request to the GitHub API with a custom
// header of "X-Trvial-Header: Just as a demo".
$url = "https://api.github.com/users/nategood";
$response = \Httpful\Request::get($url)
    ->expectsJson()
    ->withXTrivialHeader('Just as a demo')
    ->send();

echo "{$response->body->name} joined GitHub on " .
                        date('M jS', strtotime($response->body->created_at)) ."\n";
```

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

### Registering a custom JSON handler

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

Example call to Httpful::register that overrides the default handler for JSON mime type with a JsonHandler configured to decode as an array.

```php
\Httpful\Httpful::register(\Httpful\Mime::JSON,
    new \Httpful\Handlers\JsonHandler(['decode_as_array' => true]));
```

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

### Http::idempotentMethods

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

Returns an array of HTTP methods that are considered idempotent (i.e., multiple identical requests have the same effect as a single request). This includes HEAD, GET, PUT, DELETE, OPTIONS, TRACE, and PATCH, but excludes POST.

```APIDOC
## Http::idempotentMethods

### Description
Returns an array of HTTP methods that are considered idempotent (i.e., multiple identical requests have the same effect as a single request). This includes HEAD, GET, PUT, DELETE, OPTIONS, TRACE, and PATCH, but excludes POST.

### Method
`public static function idempotentMethods(): array`

### Return Value
- **array** - List of idempotent HTTP methods: `['HEAD', 'GET', 'PUT', 'DELETE', 'OPTIONS', 'TRACE', 'PATCH']`

### Example
```php
$idempotentMethods = Http::idempotentMethods();
// Result: ['HEAD', 'GET', 'PUT', 'DELETE', 'OPTIONS', 'TRACE', 'PATCH']
```
```

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

### XmlHandler::serialize_clean

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Alternative XML serialization using XMLWriter. Starts a document with version '1.0' and encoding 'ISO-8859-1', then recursively writes the payload.

```APIDOC
## XmlHandler::serialize_clean

### Description
Alternative XML serialization using XMLWriter. Starts a document with version '1.0' and encoding 'ISO-8859-1', then recursively writes the payload.

### Method
serialize_clean

### Signature
`public function serialize_clean($payload): string`

### Parameters
- **$payload** (mixed) - Required - The data to serialize.

### Return Value
- **string** - The XML string.

### Usage Example
```php
$handler = new \Httpful\Handlers\XmlHandler();
$xml = $handler->serialize_clean(['user' => ['name' => 'Nate']]);
```
```

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

### Request::get signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Static factory for a GET request. Accepts a URI and optional MIME type that sets both send and expect types. Returns a Request configured for Http::GET.

```php
public static function get($uri, $mime = null)
```

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

### Httpful handler registration and lookup

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Shows how to register, retrieve, and check for handlers via \Httpful\Httpful. register() overrides existing handlers; get() falls back to a shared MimeHandlerAdapter singleton for unknown types; hasParserRegistered() returns a boolean.

```php
\Httpful\Httpful::register($mimeType, \Httpful\Handlers\MimeHandlerAdapter $handler); // register/override
$handler = \Httpful\Httpful::get($mimeType = null);               // lookup; falls back to a shared MimeHandlerAdapter singleton for unknown types
$has = \Httpful\Httpful::hasParserRegistered($mimeType);           // bool
```

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

### clientSideCert($cert, $key, $passphrase = null, $encoding = 'PEM')

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets client-side certificate and key for SSL authentication. Throws an exception if either file is missing.

```APIDOC
## clientSideCert($cert, $key, $passphrase = null, $encoding = 'PEM')

### Description
Sets client-side certificate and key for SSL authentication. Throws an exception if either file is missing.

### Method
PHP method

### Endpoint
Request::clientSideCert($cert, $key, $passphrase = null, $encoding = 'PEM')

### Parameters
- `$cert` (string) - Required - Path to client cert file
- `$key` (string) - Required - Path to client key file
- `$passphrase` (string) - Optional - Passphrase for the client key (default: null)
- `$encoding` (string) - Optional - Cert/key encoding (default: 'PEM')

### Returns
`Request` - The current Request instance for chaining.
```

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

### useSocks5Proxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Shortcut for useProxy with Proxy::SOCKS5.

```APIDOC
## useSocks5Proxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null)

### Description
Shortcut for useProxy with Proxy::SOCKS5.

### Method
PHP method

### Endpoint
Request::useSocks5Proxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null)

### Parameters
- `$proxy_host` (string) - Required - Proxy hostname/address
- `$proxy_port` (int) - Optional - Proxy port (default: 80)
- `$auth_type` (string) - Optional - CURLAUTH_BASIC or CURLAUTH_NTLM; null = no auth
- `$auth_username` (string) - Optional - Proxy username (used only when auth_type is set)
- `$auth_password` (string) - Optional - Proxy password (used only when auth_type is set)

### Returns
`Request` - The current Request instance for chaining.
```

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

### Request::init()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Static factory method to create a new Request instance with a custom HTTP method. Returns a chainable request builder.

```APIDOC
## Request::init()

### Description
Static factory method to create a new Request instance with a custom HTTP method. Returns a chainable request builder.

### Method
Custom (e.g., POST, PUT, DELETE)

### Endpoint
N/A (factory method)

### Parameters
- **$method** (string) - Required - The HTTP method string.
- **$uri** (string) - Required - The request URI.

### Request Example
```php
$request = \Httpful\Request::init('POST', 'http://example.com');
```

### Response
Returns a new `Httpful\Request` instance.
```

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

### Configure library-wide defaults with Request::ini

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Creates a template with JSON expectation, strict SSL, and a 10-second timeout, then sets it as the default for all future requests. Subsequent requests inherit these settings.

```php
// Configure library-wide defaults: expect JSON, strict SSL on, 10s timeout
$template = \Httpful\Request::get('https://api.example.com')
    ->expectsJson()
    ->withStrictSSL()
    ->timeout(10);
\Httpful\Request::ini($template);

$response = \Httpful\Request::get('https://api.example.com/users')->send(); // inherits all settings
```

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

### Request::init signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Generic factory wrapped by the get/post/... methods. Calls Bootstrap::init(), initializes the template if needed, then returns $request->_setDefaults()->method($method)->sendsType($mime)->expectsType($mime).

```php
public static function init($method = null, $mime = null)
```

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

### Request::init($method = null, $mime = null)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Generic factory method that initializes a Request with the given HTTP method and MIME type. It is wrapped by the specific get/post/put/patch/delete methods.

```APIDOC
## Request::init($method = null, $mime = null)

### Description
Generic factory method that initializes a Request with the given HTTP method and MIME type. It is wrapped by the specific get/post/put/patch/delete methods.

### Method
N/A (factory)

### Endpoint
N/A (SDK method)

### Parameters
- `$method` (string) - Optional - HTTP method (e.g., 'GET', 'POST')
- `$mime` (string) - Optional - Mime short name or full type

### Returns
`Request` with defaults applied, method set, and MIME types set.

### Example
```php
$request = \Httpful\Request::init('GET', 'json');
```
```

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

### useSocks4Proxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Shortcut for useProxy with Proxy::SOCKS4.

```APIDOC
## useSocks4Proxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null)

### Description
Shortcut for useProxy with Proxy::SOCKS4.

### Method
PHP method

### Endpoint
Request::useSocks4Proxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null)

### Parameters
- `$proxy_host` (string) - Required - Proxy hostname/address
- `$proxy_port` (int) - Optional - Proxy port (default: 80)
- `$auth_type` (string) - Optional - CURLAUTH_BASIC or CURLAUTH_NTLM; null = no auth
- `$auth_username` (string) - Optional - Proxy username (used only when auth_type is set)
- `$auth_password` (string) - Optional - Proxy password (used only when auth_type is set)

### Returns
`Request` - The current Request instance for chaining.
```

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

### sendIt()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Alias of send() that executes the request and returns a Response object.

```APIDOC
## sendIt()

### Description
Alias of `send()`. Executes the request and returns a Response object.

### Method
`sendIt()`

### Return Type
`Httpful\Response`
```

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

### Constructor

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/response.md

Creates a Response instance. Although instances are typically created by Request::buildResponse(), the constructor is public and can be called directly.

```APIDOC
## Constructor

### Description
Creates a Response instance. Although instances are typically created by Request::buildResponse(), the constructor is public and can be called directly.

### Method
__construct

### Signature
```php
public function __construct(string $body, string $headers, Request $request, array $meta_data = [])
```

### Parameters
- **$body** (string) - Required - Raw response body
- **$headers** (string) - Required - Raw header block (status line + headers)
- **$request** (Request) - Required - The originating request (drives parsing options)
- **$meta_data** (array) - Optional - Extra metadata, e.g. from curl_getinfo() (redirect count, etc.)

### Description of Behavior
The constructor sets $request, $raw_headers, $raw_body, $meta_data, then:
- $code = $this->_parseCode($headers) — parses the status code from the status line
- $headers = Response\Headers::fromString($headers) — case-insensitive header collection
- _interpretHeaders() — extracts content_type, charset, vendor/personal flags, parent_type
- $body = $this->_parse($body) — mime-based body parsing
```

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

### buildUserAgent() method signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Declares the public method that builds the User-Agent string, appending server software and terminal program details if set.

```php
public function buildUserAgent(): string
```

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

### Register XmlHandler with namespace and libxml_opts

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Creates an XmlHandler with a custom namespace and libxml options (LIBXML_NOCDATA) and registers it for XML MIME type. The 'namespace' and 'libxml_opts' keys are optional with defaults '' and 0.

```php
$handler = new \Httpful\Handlers\XmlHandler([
    'namespace'   => 'http://example.com',
    'libxml_opts' => LIBXML_NOCDATA,
]);
\Httpful\Httpful::register(\Httpful\Mime::XML, $handler);
```

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

### sendIt() method signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Declares the public sendIt() method, which is an alias of send().

```php
public function sendIt()
```

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

### Request::setClientCert()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets client certificate for SSL. Returns the current Request instance for chaining.

```APIDOC
## Request::setClientCert()

### Description
Sets client certificate for SSL. Returns the current Request instance for chaining.

### Method
N/A (setter)

### Endpoint
N/A

### Parameters
- **$cert** (string) - Required - Path to certificate file.
- **$key** (string) - Optional - Path to key file.
- **$passphrase** (string) - Optional - Passphrase.
- **$encoding** (string) - Optional - Encoding (default 'PEM').

### Request Example
```php
$request->setClientCert('/path/to/cert.pem', '/path/to/key.pem', 'pass');
```

### Response
Returns `$this` for chaining.
```

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

### Library default template initialization

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Sets the static default template for all new Request instances. The template disables strict SSL verification by default, overriding the class property default of true.

```php
self::$_template = new Request(['method' => Http::GET]);
self::$_template->withoutStrictSSL();
```

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

### hasErrors() usage example

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/response.md

Shows how to check if a response has errors after sending a request with Httpful\Request::get(). If hasErrors() returns true, it prints the HTTP status code and 'failed'.

```php
$response = \Httpful\Request::get($url)->send();
if ($response->hasErrors()) {
    echo "HTTP {$response->code} failed\n";
}
```

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

### Request::options signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Static factory for an OPTIONS request.

```php
public static function options($uri)
```

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

### Request::useProxy(...) / useSocks4Proxy / useSocks5Proxy

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Configures proxy settings for the request. Supports HTTP, SOCKS4, and SOCKS5 proxies.

```APIDOC
## Request::useProxy(...) / useSocks4Proxy / useSocks5Proxy

### Description
Configures proxy settings for the request. Supports HTTP, SOCKS4, and SOCKS5 proxies.

### Method
useProxy(...) / useSocks4Proxy / useSocks5Proxy

### Endpoint
Request::useProxy(...) / Request::useSocks4Proxy / Request::useSocks5Proxy

### Parameters
None specified in the source.

### Response
Returns the current Request instance for chaining.
```

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

### Request::ini(Request $template)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Clones the provided template and uses it as the default for all future requests. This allows library-wide configuration of request defaults.

```APIDOC
## Request::ini(Request $template)

### Description
Clones the provided template and uses it as the default for all future requests. This allows library-wide configuration of request defaults.

### Method
`public static function ini(Request $template)`

### Parameters
- **$template** (Request) - Required - The template to clone and use as default.

### Request Example
```php
$template = \Httpful\Request::get('https://api.example.com')
    ->expectsJson()
    ->withStrictSSL()
    ->timeout(10);
\Httpful\Request::ini($template);
```

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

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

### Catch plain \Exception when sending without a URI

Source: https://github.com/nategood/httpful/blob/master/_autodocs/errors.md

Attempting to send a request before defining a URI endpoint throws a plain \Exception with message 'Attempting to send a request before defining a URI endpoint.' This example passes null as the URI to trigger the condition.

```php
try {
    \Httpful\Request::post(null, ['x' => 1])->send(); // uri not set
} catch (\Exception $e) { /* 'Attempting to send a request before defining a URI endpoint.' */ }
```

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

### Httpful\Bootstrap::init

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

Registers the autoloader and default handlers. This is called automatically by Request::init() and can be called manually.

```APIDOC
## [PHP] Httpful\Bootstrap::init

### Description
Registers the autoloader and default handlers. This is called automatically by Request::init() and can be called manually.

### Method
PHP static method

### Endpoint
`Httpful\Bootstrap::init()`

### Parameters
None

### Request Example
```php
Httpful\Bootstrap::init();
```

### Response
No return value.
```

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

### Httpful::get method signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

Signature for the static get method that returns the registered handler for a mime type, or a lazily created shared MimeHandlerAdapter singleton when nothing is registered or mimeType is null.

```php
public static function get($mimeType = null)
```

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

### Request::options($uri)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Creates a Request configured for an HTTP OPTIONS request.

```APIDOC
## Request::options($uri)

### Description
Creates a Request configured for an HTTP OPTIONS request.

### Method
OPTIONS

### Endpoint
N/A (SDK method)

### Parameters
- `$uri` (string) - Required - Request URI

### Returns
`Request` configured for `Http::OPTIONS`.

### Example
```php
$request = \Httpful\Request::options('https://api.example.com/users');
```
```

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

### Request::parseWith, whenError, beforeSend

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Sets callbacks for response parsing, error handling, and pre-send hooks.

```APIDOC
## Request::parseWith, whenError, beforeSend

### Description
Sets callbacks for response parsing, error handling, and pre-send hooks.

### Method
parseWith / whenError / beforeSend

### Endpoint
Request::parseWith / Request::whenError / Request::beforeSend

### Parameters
None specified in the source.

### Response
Returns the current Request instance for chaining.
```

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

### useProxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null, $proxy_type = Proxy::HTTP)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Configures proxy settings for the request. Sets CURLOPT_PROXY and CURLOPT_PROXYTYPE, and optionally proxy authentication.

```APIDOC
## useProxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null, $proxy_type = Proxy::HTTP)

### Description
Configures proxy settings for the request. Sets CURLOPT_PROXY and CURLOPT_PROXYTYPE, and optionally proxy authentication.

### Method
PHP method

### Endpoint
Request::useProxy($proxy_host, $proxy_port = 80, $auth_type = null, $auth_username = null, $auth_password = null, $proxy_type = Proxy::HTTP)

### Parameters
- `$proxy_host` (string) - Required - Proxy hostname/address
- `$proxy_port` (int) - Optional - Proxy port (default: 80)
- `$auth_type` (string) - Optional - CURLAUTH_BASIC or CURLAUTH_NTLM; null = no auth
- `$auth_username` (string) - Optional - Proxy username (used only when auth_type is set)
- `$auth_password` (string) - Optional - Proxy password (used only when auth_type is set)
- `$proxy_type` (int) - Optional - One of Proxy::HTTP, Proxy::SOCKS4, Proxy::SOCKS5 (default: Proxy::HTTP)

### Returns
`Request` - The current Request instance for chaining.
```

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

### Httpful\Http class with HTTP method constants

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

Defines the Http class with public constants for HTTP methods: HEAD, GET, POST, PUT, DELETE, PATCH, OPTIONS, and TRACE. These constants are used throughout the library for method classification.

```php
class Http
{
    public const HEAD      = 'HEAD';
    public const GET       = 'GET';
    public const POST      = 'POST';
    public const PUT       = 'PUT';
    public const DELETE    = 'DELETE';
    public const PATCH     = 'PATCH';
    public const OPTIONS   = 'OPTIONS';
    public const TRACE     = 'TRACE';
}
```

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

### Request::basicAuth()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets basic authentication credentials. Returns the current Request instance for chaining.

```APIDOC
## Request::basicAuth()

### Description
Sets basic authentication credentials. Returns the current Request instance for chaining.

### Method
N/A (setter)

### Endpoint
N/A

### Parameters
- **$username** (string) - Required - Username.
- **$password** (string) - Required - Password.

### Request Example
```php
$request->basicAuth('user', 'pass');
```

### Response
Returns `$this` for chaining.
```

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

### Request::with*()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Magic method to set various options (e.g., withStrictSSL, withTimeout). Returns the current Request instance for chaining.

```APIDOC
## Request::with*()

### Description
Magic method to set various options (e.g., withStrictSSL, withTimeout). Returns the current Request instance for chaining.

### Method
N/A (setter)

### Endpoint
N/A

### Parameters
- **$value** (mixed) - Required - The value for the option.

### Request Example
```php
$request->withStrictSSL(true);
```

### Response
Returns `$this` for chaining.
```

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

### JsonHandler::init

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Initializes the handler with constructor options. Reads the 'decode_as_array' option to determine whether JSON responses should be parsed as associative arrays.

```APIDOC
## JsonHandler::init

### Description
Initializes the handler with constructor options. Reads the 'decode_as_array' option to determine whether JSON responses should be parsed as associative arrays.

### Method
`init`

### Signature
`public function init(array $args)`

### Parameters
- **$args** (array) - Required - Constructor options. Supports `decode_as_array` (bool, default `false`). When `true`, JSON responses are parsed as associative arrays instead of objects.

### Returns
`void`

### Example
```php
$handler = new \Httpful\Handlers\JsonHandler(['decode_as_array' => true]);
$handler->init(['decode_as_array' => true]);
```
```

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

### Request::followRedirects()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets whether to follow redirects. Returns the current Request instance for chaining.

```APIDOC
## Request::followRedirects()

### Description
Sets whether to follow redirects. Returns the current Request instance for chaining.

### Method
N/A (setter)

### Endpoint
N/A

### Parameters
- **$follow** (bool) - Required - Whether to follow redirects.

### Request Example
```php
$request->followRedirects(true);
```

### Response
Returns `$this` for chaining.
```

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

### Request::uri($uri)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Sets the target URI for the request. This is required before calling send().

```APIDOC
## Request::uri($uri)

### Description
Sets the target URI for the request. This is required before calling send().

### Method
uri($uri)

### Endpoint
Request::uri($uri)

### Parameters
#### Path Parameters
- **$uri** (string) - Required - The target URI for the request.

### Response
Returns the current Request instance for chaining.
```

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

### Request::autoParse($auto = true)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Enables or disables smart response parsing. Defaults to true.

```APIDOC
## Request::autoParse($auto = true)

### Description
Enables or disables smart response parsing. Defaults to true.

### Method
autoParse($auto = true)

### Endpoint
Request::autoParse($auto = true)

### Parameters
#### Path Parameters
- **$auto** (bool) - Optional - Whether to enable smart response parsing. Defaults to true.

### Response
Returns the current Request instance for chaining.
```

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

### _curlPrep() method signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Declares the public method that builds the cURL handle without sending. Throws \Exception when the URI is null or client cert/key files are missing.

```php
public function _curlPrep()
```

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

### Parsing with namespace and sending XML

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Shows how to register XmlHandler with a namespace for parsing and how to send XML in a POST request.

```php
// parsing with a namespace
\Httpful\Httpful::register(\Httpful\Mime::XML,
    new \Httpful\Handlers\XmlHandler(['namespace' => 'http://example.com']));
$response = \Httpful\Request::get($url)->expectsXml()->send();
$name = (string) $response->body->name; // SimpleXMLElement

// sending XML
$req = \Httpful\Request::post($url, ['user' => ['name' => 'Nate']], 'xml');
```

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

### withoutAutoParsing() / withAutoParsing()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Aliases for autoParse(false) and autoParse(true) respectively.

```APIDOC
## withoutAutoParsing() / withAutoParsing()

### Description
Aliases for autoParse(false) and autoParse(true) respectively.

### Method
PHP method

### Endpoint
Request::withoutAutoParsing() / Request::withAutoParsing()

### Parameters
None

### Returns
`Request` - The current Request instance for chaining.
```

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

### Request::strictSSL($strict)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Sets whether to enforce strict SSL peer and host verification. Defaults to false (effective).

```APIDOC
## Request::strictSSL($strict)

### Description
Sets whether to enforce strict SSL peer and host verification. Defaults to false (effective).

### Method
strictSSL($strict)

### Endpoint
Request::strictSSL($strict)

### Parameters
#### Path Parameters
- **$strict** (bool) - Required - Whether to enforce strict SSL verification.

### Response
Returns the current Request instance for chaining.
```

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

### __call($method, $args)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Magic method that enables dynamic method calls for setting request headers, MIME types, and other options. Supports 'sends*' and 'expects*' patterns for MIME types, and 'with*' prefix for custom headers.

```APIDOC
## __call($method, $args)

### Description
Magic method that enables dynamic method calls for setting request headers, MIME types, and other options. Supports 'sends*' and 'expects*' patterns for MIME types, and 'with*' prefix for custom headers.

### Method
__call

### Parameters
- **$method** (string) - Required - The method name being called.
- **$args** (array) - Required - The arguments passed to the method.

### Behavior
- If method name starts with 'sends' and the remainder is a supported MIME type (e.g., `sendsJson()`), it calls `sends(Mime::getFullMime($mime))`.
- If method name starts with 'expects' and the remainder is a supported MIME type (e.g., `expectsJson()`), it calls `expects(Mime::getFullMime($mime))`.
- Otherwise, if method name starts with 'with' (optional), the remainder is treated as a header name (e.g., `withXTrivialHeader('v')` sets header `X-Trivial-Header: v`). Returns `null` if no arguments are provided.

### Example
```php
$response = \Httpful\Request::get($url)->expectsJson()
    ->withXTrivialHeader('Just as a demo')->send();
```

### Supported MIME Types
json, xml, form, plain, text, upload, html, xhtml, js, javascript, yaml, csv
```

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

### Httpful\Bootstrap::autoload

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

PSR-0 autoloader that maps Httpful\X\Y to src/Httpful/X/Y.php and requires the file if it exists.

```APIDOC
## [PHP] Httpful\Bootstrap::autoload

### Description
PSR-0 autoloader that maps Httpful\X\Y to src/Httpful/X/Y.php and requires the file if it exists.

### Method
PHP static method

### Endpoint
`Httpful\Bootstrap::autoload($classname)`

### Parameters
#### Path Parameters
- **$classname** (string) - Required - The fully qualified class name to autoload.

### Request Example
```php
Httpful\Bootstrap::autoload('Httpful\Request');
```

### Response
No return value.
```

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

### send()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Executes the HTTP request and returns a Response object. Throws ConnectionErrorException on cURL failure.

```APIDOC
## send()

### Description
Initializes cURL if needed, executes the request, builds a Response, and returns it. Throws ConnectionErrorException when cURL fails.

### Method
`send()`

### Return Type
`Httpful\Response`

### Throws
- `Httpful\Exception\ConnectionErrorException` when cURL fails

### Example
```php
try {
    $response = \Httpful\Request::get($url)->send();
    echo $response->body;
} catch (\Httpful\Exception\ConnectionErrorException $e) {
    error_log("cURL error {$e->getCurlErrorNumber()}: {$e->getCurlErrorString()}");
}
```
```

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

### Httpful\Bootstrap::pharAutoload

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/support.md

PSR-0 autoloader for use within a phar archive.

```APIDOC
## [PHP] Httpful\Bootstrap::pharAutoload

### Description
PSR-0 autoloader for use within a phar archive.

### Method
PHP static method

### Endpoint
`Httpful\Bootstrap::pharAutoload($classname)`

### Parameters
#### Path Parameters
- **$classname** (string) - Required - The fully qualified class name to autoload.

### Request Example
```php
Httpful\Bootstrap::pharAutoload('Httpful\Request');
```

### Response
No return value.
```

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

### Request::head($uri)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Creates a Request configured for an HTTP HEAD request.

```APIDOC
## Request::head($uri)

### Description
Creates a Request configured for an HTTP HEAD request.

### Method
HEAD

### Endpoint
N/A (SDK method)

### Parameters
- `$uri` (string) - Required - Request URI

### Returns
`Request` configured for `Http::HEAD` (sets `CURLOPT_NOBODY` in `_curlPrep()`).

### Example
```php
$request = \Httpful\Request::head('https://api.example.com/users');
```
```

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

### Request::d($attr)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/configuration.md

Reads a default value from the template, or the whole template when null is passed.

```APIDOC
## Request::d($attr)

### Description
Reads a default value from the template, or the whole template when null is passed.

### Method
`public static function d($attr)`

### Parameters
- **$attr** (mixed) - Required - The attribute name to read, or null to get the whole template.

### Response
Returns the default value or the whole template.
```

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

### MimeHandlerAdapter::init

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/handlers.md

Override point for handler configuration. The base implementation is a no-op.

```APIDOC
## MimeHandlerAdapter::init

### Description
Override point for handler configuration. The base implementation is a no-op.

### Method
Method

### Signature
`public function init(array $args)`

### Parameters
- **$args** (array) - Required - Configuration arguments.

### Return Value
No return value (void).
```

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

### method($method)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets the HTTP method for the request. No-op if the method is empty.

```APIDOC
## method($method)

### Description
Sets the HTTP method for the request. No-op when `$method` is empty.

### Method
`method($method)`

### Parameters
- `$method` (string) - Required - The HTTP method to set.

### Return Type
`Request`
```

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

### send() method signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Declares the public send() method that initializes cURL, executes the request, builds a Response, and returns it. Throws ConnectionErrorException on cURL failure.

```php
public function send()
```

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

### uri($uri)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets the URI for the request and returns the Request instance for chaining.

```APIDOC
## uri($uri)

### Description
Sets the URI for the request.

### Method
`uri($uri)`

### Parameters
- `$uri` (string) - Required - The URI to set.

### Return Type
`Request`
```

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

### expects(?string $mime)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets the expected response mime type. No-op when empty.

```APIDOC
## expects(?string $mime)

### Description
Sets `expected_type = Mime::getFullMime($mime)`. No-op when empty.

### Method
`expects(?string $mime)`

### Parameters
- `$mime` (?string) - Required - Short name or full mime of the response type.

### Return Type
`Request`
```

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

### followRedirects($follow = true)

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sets whether to follow redirects. When true, sets max_redirects to 25 and enables CURLOPT_FOLLOWLOCATION.

```APIDOC
## followRedirects($follow = true)

### Description
Sets whether to follow redirects. When true, sets max_redirects to 25 and enables CURLOPT_FOLLOWLOCATION.

### Method
PHP method

### Endpoint
Request::followRedirects($follow = true)

### Parameters
- `$follow` (bool|int) - Optional - Whether to follow redirects (default: true)

### Returns
`Request` - The current Request instance for chaining.
```

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

### Request::send()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Sends the request and returns the response. Must be called after setting URI and other options.

```APIDOC
## Request::send()

### Description
Sends the request and returns the response. Must be called after setting URI and other options.

### Method
N/A (action)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
$response = $request->send();
```

### Response
Returns a `Httpful\Response` object.
```

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

### Request::addHeaders()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Adds multiple headers to the request. Returns the current Request instance for chaining.

```APIDOC
## Request::addHeaders()

### Description
Adds multiple headers to the request. Returns the current Request instance for chaining.

### Method
N/A (setter)

### Endpoint
N/A

### Parameters
- **$headers** (array) - Required - Associative array of header name => value.

### Request Example
```php
$request->addHeaders(['X-Custom' => 'value', 'Accept' => 'application/json']);
```

### Response
Returns `$this` for chaining.
```

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

### __toString()

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/response.md

Returns the raw body string of the response. Useful for direct output.

```APIDOC
## __toString()

### Description
Returns the raw body string.

### Method
__toString

### Signature
```php
public function __toString(): string
```

### Returns
- **string** - The raw body string.

### Example
```php
echo $response; // prints $response->raw_body
```
```

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

### method() method signature

Source: https://github.com/nategood/httpful/blob/master/_autodocs/api-reference/request.md

Declares the public method() method that sets the HTTP method; no-op when the method is empty.

```php
public function method($method)
```
Tokens:
Raw