PSR-7: HTTP Message Interface

Also Known As

TL;DR

Explanation

PSR-7 defines interfaces for HTTP messages: RequestInterface, ServerRequestInterface (incoming requests with parsed body, cookies, uploaded files), ResponseInterface, and supporting types (UriInterface, StreamInterface, UploadedFileInterface). All PSR-7 objects are immutable — methods that modify state return new instances (withHeader(), withBody()). This enables safe middleware pipelines where each layer receives and returns message objects. Implementations include Guzzle PSR-7, Nyholm PSR-7 (lightest), and Laminas Diactoros. PSR-7 is the foundation of PSR-15 middleware.

Common Misconception

Why It Matters

Common Mistakes

• Not using the return value of withHeader(), withBody(), etc — PSR-7 messages are immutable; modifications return new instances.
• Type-hinting against concrete classes (GuzzleHttp\Psr7\Request) instead of the PSR-7 interfaces.
• Forgetting that getQueryParams() returns parsed query params but getParsedBody() returns POST data — different methods.
• Not using a PSR-17 factory to create PSR-7 objects — direct instantiation couples to one library.

Code Examples

// Mutating immutable PSR-7 object — original unchanged:
$response->withHeader('Content-Type', 'application/json'); // Returns new instance!
// $response is unchanged — the new instance is discarded

// Correct:
$response = $response->withHeader('Content-Type', 'application/json');
return $response->withBody($stream);

// PSR-7 — immutable HTTP message objects
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;

// All mutating methods return NEW instances — original unchanged
function addJsonHeader(ResponseInterface $response): ResponseInterface {
    return $response->withHeader('Content-Type', 'application/json');
                   // ^^ returns new object with header added
}

// Read request data
public function handle(ServerRequestInterface $request): ResponseInterface {
    $body    = (string) $request->getBody();
    $data    = json_decode($body, true);
    $userId  = $request->getAttribute('user_id');
    $query   = $request->getQueryParams();
    $cookies = $request->getCookieParams();
}

Tags

Related Terms

References

• https://www.php-fig.org/psr/psr-7/