README

A framework-agnostic PHP library for handling HTTP. Includes:

PHPDoc type annotations for static analyzers
Common types related to HTTP, such as Field, MediaType, Url and IpAddress
Parsing and serialization of IPv4 and IPv6 addresses
Parsing and serialization of structured fields per RFC 9651

Installation

Requires PHP >= 8.5. Simply run composer install slendium/http to add it to your project. Most likely you do not want to use this package directly, but use the following implementation(s) instead:

slendium/http-superglobals - implements these interfaces directly using the PHP superglobal variables
slendium/http-client - a cURL-based HTTP client implementation based on these interfaces

Examples

Consume a request

$networked = $framework->getRequest(); // returns a Networked<Request>
$request = $networked->payload; // the request message with headers, body and trailers
$address = $networked->address; // contain IP and port, can be passed around independently

// implementation-agnostic access to POST-ed data ($_POST, form data, JSON, CBOR, mocked data)
if ($request->body instanceof Structured) {
	$post = $request->body->root; // ArrayAccess&Countable&Traversable
}

// access query arguments
$queryData = $request->url->getQuery(); // (ArrayAccess&Countable&Traversable)|null

// implementation-agnostic access to cookies (a parsed header, $_COOKIES or even mocked values)
if ($request->headers['cookie'] instanceof Structured) {
	$cookies = $request->headers['cookie']->root; // ArrayAccess&Countable&Traversable
	// or get the raw value instead
	$cookieString = $request->headers['cookie']->value;
}

Uploaded files

if ($request->body instanceof Structured) {
	// files are merged with body data
	$upload = $request->body->root['file'];
	if ($upload instanceof UploadedFile) {
		// process file
	} else if ($upload instanceof UploadFailure) {
		// handle error
	}
}

Structured fields

// check if implementation recognized the header
$field = $request->headers['x-custom-field'];
if ($field instanceof DictionaryField) {
	// do something with an RFC 9651 dictionary
	$dictionary = $field->toDictionary();
} else if ($field instanceof ListField) {
	// do something with an RFC 9651 list
	$list = $field->toList();
} else if ($field instanceof ItemField) {
	// do something with an RFC 9651 item
	$item = $field->toItem();
	if ($item instanceof Item\BinarySequence) { ... } // etc.
}

IP-addresses

// create raw ip address from octets or 16-bit values and convert them to strings later
$ipv4 = IpAddress::V4([ 127, 0, 0, 1 ]);
echo (string)$ipv4, "\n";
$ipv6 = IpAddress::V6([ 0, 0, /* ... */ 0x80 ]);
echo (string)$ipv6, "\n";

// parse a string into ipv4 or ipv6
$parsed = IpAddress::fromString($addrString);
if ($parsed instanceof Ipv4Address) { ... }
else if ($parsed instanceof Ipv6Address { ... }

Motivation

This library serves a similar purpose as PSR-7, but the decision not to use PSR-7 was based on the following factors:

The design has aged, many of the interface "getters" can be replaced by property hooks now
The interfaces force implementation of a builder pattern - e.g. withMethod() - which requires implementing a lot of methods you don't need when you are simply responding to a single request received through PHP/CGI
Some of the interfaces contain methods that could be folded into built-in PHP types: e.g. hasHeader(), getHeader(), withHeader(), addHeader(), getHeaders() could all be replaced using an ArrayAccess&Traversable type hint for a $headers property
The PHP "superglobals" are not integrated transparently, they require a separate interface which RequestInterface consumers need to be aware of
No abstractions for messages that contain structured objects - a message consumer should be able to treat input data generically without knowing the serialization method (form data, JSON, CBOR, ...)
Missing interfaces for common HTTP concepts such as "fields", "media types", "structured values", etc.

slendium / http

Maintainers

Details