PSR-7 HTTP Message Interfaces

psr/http-message is the official PHP-FIG package defining PSR-7: a shared set of interfaces (RequestInterface, ResponseInterface, ServerRequestInterface, StreamInterface, UriInterface, UploadedFileInterface) for representing HTTP messages in PHP. It contains no implementation of its own — only the contracts — so that frameworks, HTTP clients, and middleware can be written against a common HTTP message abstraction instead of each defining incompatible request/response classes.

Because nearly every modern PHP framework, HTTP client (Guzzle, Symfony HttpClient), and middleware system (PSR-15) either implements or consumes these interfaces, psr/http-message functions as foundational interoperability plumbing for the PHP ecosystem: with over 18 million monthly installs, it is one of the most widely depended-upon packages in Composer’s registry, even though most developers never interact with it directly — they interact with concrete implementations (e.g. guzzlehttp/psr7, nyholm/psr7, or a framework’s own request/response objects) that satisfy these interfaces.

What You Get

• MessageInterface and its RequestInterface/ResponseInterface/ServerRequestInterface extensions describing an immutable HTTP message
• StreamInterface for representing an HTTP message body as a PSR-7-compatible stream abstraction
• UriInterface for representing and manipulating a URI per RFC 3986
• UploadedFileInterface for representing a file uploaded via an HTTP request
• Documentation (docs/PSR7-Interfaces.md, docs/PSR7-Usage.md) describing method contracts and correct usage patterns

Common Use Cases

• Type-hinting middleware or controller methods against RequestInterface/ResponseInterface instead of a framework-specific request class
• Building a PSR-7-compatible HTTP client or server library that any PSR-7 consumer can use interchangeably
• Implementing PSR-15 middleware, which is built directly on top of these PSR-7 message interfaces
• Writing framework-agnostic PHP libraries that need to accept or return HTTP messages without depending on a specific framework

Under The Hood

Architecture — The package is a pure interface definition set under src/: MessageInterface is the base contract extended by RequestInterface (adds method/target/URI) and further by ServerRequestInterface (adds server params, query params, parsed body, uploaded files, attributes), while ResponseInterface extends MessageInterface with a status code and reason phrase; StreamInterface, UriInterface, and UploadedFileInterface are separate, composed-in contracts rather than inheritance targets. There is no src/ implementation code beyond these interface declarations — by design, this repository defines the contract only. Tech Stack — Plain PHP interfaces requiring PHP 7.2+/8.0, with zero dependencies (composer.json requires only php); autoloaded via PSR-4 under the Psr\Http\Message\ namespace. Code Quality — There is no test suite in this repository because there is no executable code to test — correctness is instead enforced socially, through the PHP-FIG standards process and by the extensive third-party test suites of libraries (Guzzle, nyholm/psr7, Laminas) that implement these interfaces. API Design — Every mutating method (e.g. withHeader(), withBody(), withUri()) explicitly returns a new instance rather than mutating in place, documented immutability that gives implementers an unambiguous, consistent contract; the interfaces are intentionally minimal (no convenience methods), keeping them easy to implement fully but requiring implementers to add ergonomic helpers themselves.