http-factory

psr/http-factory is the official PHP-FIG package that defines PSR-17, the common set of interfaces for HTTP message factories. It does not ship an implementation of its own; instead it specifies six factory contracts for producing PSR-7 objects, letting frameworks, middleware, and client libraries create requests, responses, streams, URIs, and uploaded files without binding themselves to any concrete implementation.

By depending on these interfaces rather than a specific library, PHP applications can swap between compatible implementations such as Nyholm PSR-7, Guzzle, Laminas Diactoros, or Slim’s PSR-7 with no code changes. This is the same interoperability pattern the PHP ecosystem relies on for PSR-3 logging and PSR-18 HTTP clients.

What You Get

• Six factory interfaces covering every PSR-7 object type: requests, server requests, responses, streams, URIs, and uploaded files
• A framework-agnostic contract that lets you depend on abstractions instead of a concrete PSR-7 library
• Seamless interoperability with any PSR-17 implementation (Nyholm, Guzzle, Laminas Diactoros, Slim)
• Precise PHPDoc describing the required behavior of each factory method
• A tiny, dependency-light package requiring only PHP 7.1+ and psr/http-message

Common Use Cases

• Writing framework-agnostic middleware that creates responses without hard-coding a PSR-7 implementation
• Building reusable libraries that accept a factory via dependency injection so consumers choose the implementation
• Decoupling application code from Guzzle, Nyholm, or Diactoros so the underlying library can be swapped freely
• Implementing PSR-15 request handlers that need to construct new HTTP messages

Under The Hood

Architecture - The package is intentionally minimal: six PHP interfaces under the Psr\Http\Message namespace in src/, each declaring one or two factory methods (RequestFactoryInterface::createRequest, ResponseFactoryInterface::createResponse, StreamFactoryInterface::createStream/createStreamFromFile/createStreamFromResource, ServerRequestFactoryInterface::createServerRequest, UriFactoryInterface::createUri, UploadedFileFactoryInterface::createUploadedFile). There is no execution flow or data handling here — the interfaces sit above any PSR-7 implementation, so the real work happens in downstream libraries that satisfy these contracts.

Tech Stack - Pure PHP with no runtime dependencies beyond psr/http-message (^1.0 || ^2.0), requiring PHP 7.1 or newer. Autoloading is PSR-4 mapping Psr\Http\Message\ to src/. There is no build tooling, no compilation, and the entire package is a handful of interface files plus composer.json and a short README.

Code Quality - Every method carries precise PHPDoc that mirrors the normative PSR-17 specification, spelling out parameter meaning, return types, and thrown exceptions (for example the RuntimeException/InvalidArgumentException contract on createStreamFromFile). Because the package defines only interfaces, it ships no unit tests of its own — conformance testing is the responsibility of the implementation libraries — which is appropriate for a specification package.

API Design - The developer experience is excellent by design: method names read naturally (createResponse, createUri), each factory has a single clear responsibility, and consumers get full IDE and static-analysis support from the typed signatures. Depending on these interfaces rather than a concrete class is the entire point, and the near-universal ecosystem adoption (17M+ monthly installs) reflects how frictionless the contract is to implement and consume.