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();
}

References

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

Tags

Related Terms