Payload Interfaces and Streams

Payload support is the feature that makes this package more than a collection of response shortcuts. It lets structured data stay available after it has been encoded into a PSR-7 body stream.

Name	Kind	Used By	Purpose
`PayloadAwareInterface`	Interface	`JsonResponse` , `JsonStream` , custom implementations	Exposes `getPayload()` so callers can retrieve the structured payload.
`PayloadImmutableInterface`	Interface	Internal composition building block	Exposes `withPayload()` for immutable payload replacement.
`PayloadResponseInterface`	Interface	`JsonResponse` and custom responses	Combines payload access with `ResponseInterface` .
`PayloadStreamInterface`	Interface	`JsonStream` and custom streams	Combines payload access with `StreamInterface` .
`JsonStream`	Concrete class	`JsonResponse` and direct stream usage	Encodes JSON while preserving the original payload value.

Understanding the Interfaces

For everyday usage, most developers only need these two ideas:

a payload-aware response implements PayloadResponseInterface ;
a payload-aware stream implements PayloadStreamInterface .

PayloadImmutableInterface is public because it participates in those contracts, but it is mainly useful when you build your own implementations.

Working with JsonResponse

use FastForward\Http\Message\JsonResponse;

$response = new JsonResponse(['foo' => 'bar']);

$payload = $response->getPayload();      // ['foo' => 'bar']
$updated = $response->withPayload(['baz' => 123]);

Working with JsonStream

use FastForward\Http\Message\JsonStream;

$stream = new JsonStream(['foo' => 'bar']);

$json    = (string) $stream;             // {"foo":"bar"}
$payload = $stream->getPayload();        // ['foo' => 'bar']

When This Matters

Payload-aware responses and streams are useful when:

middleware needs to inspect a JSON body without reparsing it;
you want a custom response object that still exposes structured data;
you care about immutability and do not want transport concerns to erase application data.

See also Responses, JSON Response, and JSON Stream.