Download the PHP package callismart/http without Composer

Callismart HTTP Client

A lightweight, multi-adapter HTTP client for PHP 8.1+ designed for maximum reliability across diverse hosting environments. It provides a clean, fluent API with native support for AWS Signature V4 and automatic adapter fallbacks.

Why Callismart HTTP?

Most modern PHP HTTP clients rely heavily on the cURL extension. However, in many shared hosting environments or restricted server setups, cURL may be disabled or outdated.

Callismart HTTP solves this by providing:

• Adapter Fallbacks: If ext-curl isn't available, the client automatically fails over to fopen or socket communication.
• Zero Hard Dependencies: Keep your project footprint small—ideal for WordPress plugins and CLI tools.
• AWS SigV4: Native support for signing requests to AWS services (SES, S3, Lambda, etc.) without the weight of the full AWS SDK.
• Immutable Value Objects: Predictable request and response objects that are thread-safe and cacheable.
• Performance Tracking: Built-in latency measuring for every request.
• Smart Streaming: Download large files directly to disk without buffering in memory.
• Cookie Management: Automatic parsing and replay of session cookies across requests.

Installation

Install the package via Composer:

Quick Start

Basic GET Request

POST Request with JSON

Download a File

Stream a large file directly to disk without holding it in memory:

AWS Service Request (SES)

Sign and send a request to AWS:

Client Initialization

Auto-Detection (Recommended)

The client automatically detects the best available adapter in this priority order:

1. cURL (ext-curl) — Highest performance, full feature support
2. fopen (allow_url_fopen = On) — Fallback for shared hosting
3. Socket (fsockopen) — Last resort, always available

Explicit Adapter Selection

If you want to force a specific adapter:

Check Current Adapter

Set Default Headers

Persistent headers applied to every request (useful for authentication):

Per-request headers always override client defaults.

Building Requests

Requests are immutable value objects built with a fluent API.

Named Constructors

Fluent Withers

All withers return a new immutable request copy:

Add a Header

JSON Body & Headers

Automatically sets Content-Type and Accept to application/json:

Add a Cookie

Stream Response to File

Downloads the response body directly to disk without buffering:

The destination directory must exist and be writable. Throws InvalidArgumentException otherwise.

Disable SSL Verification

Use only in development or testing:

Apply Multiple Options

Sending Requests

Via HttpClient

Convenience Methods

HttpClient provides shorthand methods for common patterns:

Handling Responses

Responses are immutable value objects with helper methods for common patterns.

Status Checks

Body Parsing

Headers

Cookies

Redirect Tracking

Download Responses

For buffered responses, save to file later:

Performance Metrics

HTTP Methods with Examples

GET

Retrieve data from a server:

POST

Submit data and create resources:

Custom headers:

PUT

Replace an entire resource:

PATCH

Partially update a resource:

DELETE

Remove a resource:

JSON Support

Automatic Encoding

The with_json() method automatically encodes your data and sets the correct headers:

Automatic Decoding

The json() method safely decodes JSON responses:

File Downloads

Stream to Disk (Recommended for Large Files)

Stream the response body directly to a file without buffering in memory:

The file is created at download time. On error, partially downloaded files are automatically cleaned up.

Buffer in Memory (Small Files)

For small responses, buffer in memory and save later:

Request-Level Sink

Manual sink configuration via request:

AWS Signature Version 4

Sign requests to AWS services without the full AWS SDK:

Setup

Sign a Request

The sign() method returns a new request with AWS signing headers applied:

Headers Added by the Signer

The signer adds or overwrites three headers:

• X-Amz-Date: Request timestamp in YYYYMMDDTHHmmssZ format (UTC)
• X-Amz-Content-Sha256: SHA256 hash of the request body (hex-encoded)
• Authorization: AWS4-HMAC-SHA256 signature string containing credentials, signed headers, and signature

All other headers (including custom ones) are preserved and included in the signature.

Example: AWS SES

Send an email via AWS SES:

Example: AWS S3

Sign a request to S3 (Get Object):

Adapters

The HTTP client uses a three-tier adapter system for maximum compatibility:

cURL Adapter

Availability: When ext-curl is loaded Features: Full support — redirects, SSL verification, cookies, timeouts Performance: Highest — uses native C implementation

fopen Adapter

Availability: When allow_url_fopen = On in php.ini Features: Redirects, SSL verification, cookies, timeouts Limitation: May not work with restrictive open_basedir settings

Socket Adapter

Availability: Always (when fsockopen function exists) Features: Redirects (manual), SSL via ssl:// wrapper, cookies Limitation: No proxy support, manual socket handling

Automatic Selection

The HttpClient tests adapters in priority order and uses the first available:

Manual Selection

Force a specific adapter:

Error Handling

Exception Hierarchy

Catch Exceptions

Common Errors

Configuration Options

Request Options

Client Configuration

Requirements

• PHP: 8.1 or higher
• ext-openssl: Recommended for HTTPS support
• At least one of:
  • ext-curl (preferred)
  • allow_url_fopen = On in php.ini
  • fsockopen() function enabled

Performance Tips

1. Use Streaming for Large Files: Use with_sink() or download() to avoid buffering entire files in memory.

2. Reuse HttpClient Instances: Create once, send many requests through it to benefit from connection pooling (cURL).

3. Set Appropriate Timeouts: Balance between catching truly broken connections and allowing slow networks:

4. Disable SSL Verification Only in Development: Use without_ssl_verification() only in trusted environments.

5. Check Redirect Loops: Monitor redirect_history to detect infinite redirects:

License

This project is licensed under the MIT License. See LICENSE file for details.

Author

Callistus Nwachukwu

Contributing

Contributions are welcome. Please ensure all code follows WordPress PHP Coding Standards (K&R braces, spaces inside parentheses, tab indentation).

Support

For issues, feature requests, or questions, please visit the project repository.