JsonResponse - viames/pair GitHub Wiki

Pair framework: JsonResponse

Pair\Http\JsonResponse is the explicit JSON response object for Pair v4 controllers.

Use it when an action should return a ResponseInterface instead of sending JSON immediately through legacy helpers.

Constructor

`new JsonResponse(mixed $payload, int $httpCode = 200, array $headers = [])`

Arguments:

payload: JSON payload to emit. Arrays, objects, read models, scalar values, and null are accepted.
httpCode: HTTP status code.
headers: optional additional headers keyed by header name.

Example:

use Pair\Http\JsonResponse;

return new JsonResponse(['saved' => true], 201);

With explicit cache headers:

return new JsonResponse(['id' => 7], 200, [
	'ETag' => '"abc123"',
	'Cache-Control' => 'public, max-age=300',
]);

Read-model payloads are converted to arrays before JSON encoding.

Read-model example:

use Pair\Data\ArraySerializableData;
use Pair\Data\ReadModel;
use Pair\Http\JsonResponse;

/**
 * Public health payload for an API endpoint.
 */
final readonly class HealthReadModel implements ReadModel {

	use ArraySerializableData;

	/**
	 * Build the health payload.
	 */
	public function __construct(
		public bool $ok,
		public string $version
	) {}

	/**
	 * Export the public health payload.
	 *
	 * @return	array<string, mixed>
	 */
	public function toArray(): array {

		return [
			'ok' => $this->ok,
			'version' => $this->version,
		];

	}

}

return new JsonResponse(new HealthReadModel(true, '4.0-alpha'), 200);

Behavior

send() emits Content-Type: application/json and then any additional headers.
Empty payloads keep the historical promotion to HTTP 204.
send() does not terminate execution by itself; the v4 dispatcher sends the response and then finishes the request.
When APP_DEBUG=true and observability debug headers are enabled, send() also emits Pair correlation and trace timing headers.
Legacy ApiResponse::respond(), error(), success(), and paginated() still terminate after sending to preserve their old contract.

Scalar Payloads

Scalar payloads are supported for bridge cases such as idempotency replay:

return new JsonResponse('stored', 200);

Normal public API endpoints should still prefer explicit array/object/read-model payloads.