Add JSON:API object meta support

tobyzerner · tobyzerner · commit 6038a8be251d · 2025-10-04T21:46:04.000+09:30
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,6 +30,10 @@ and this project adheres to
 
 ### Added
 
+- Add `Context::createResponse()` method for building JSON:API responses with
+  automatic `jsonapi` object inclusion
+- Add `JsonApi::meta()` method for including meta information in the `jsonapi`
+  object
 - Add full support for JSON:API profiles:
     - Parse profile URIs from `Accept` header
     - `Context::profileRequested(string $uri): bool` - check if a profile was
diff --git a/docs/context.md b/docs/context.md
@@ -94,5 +94,8 @@ class Context
 
     // Activate a JSON:API profile for the current response
     public function activateProfile(string $uri): static;
+
+    // Create a JSON:API response with document data
+    public function createResponse(array $document): Response;
 }
 ```
diff --git a/docs/extensions.md b/docs/extensions.md
@@ -21,8 +21,6 @@ use Psr\Http\Message\ResponseInterface;
 use Tobyz\JsonApiServer\Context\Context;
 use Tobyz\JsonApiServer\Extension\Extension;
 
-use function Tobyz\JsonApiServer\json_api_response;
-
 class MyExtension extends Extension
 {
     public function uri(): string
@@ -33,7 +31,7 @@ class MyExtension extends Extension
     public function handle(Context $context): ?ResponseInterface
     {
         if ($context->path() === 'my-extension') {
-            return json_api_response([
+            return $context->createResponse([
                 'my-extension:greeting' => 'Hello world!',
             ]);
         }
diff --git a/src/Context.php b/src/Context.php
@@ -4,6 +4,9 @@
 
 use ArrayObject;
 use HttpAccept\AcceptParser;
+use Nyholm\Psr7\Response;
+use Nyholm\Psr7\Stream;
+use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use RuntimeException;
 use Tobyz\JsonApiServer\Endpoint\Endpoint;
@@ -412,4 +415,45 @@ public function forModel(array $collections, ?object $model): static
             'No resource type defined to represent model ' . get_class($model),
         );
     }
+
+    /**
+     * Create a JSON:API response.
+     */
+    public function createResponse(array $document = []): ResponseInterface
+    {
+        $response = (new Response())->withHeader('Content-Type', $this->api::MEDIA_TYPE);
+
+        if ($document) {
+            $jsonapi = ['version' => $this->api::VERSION];
+
+            if ($meta = $this->api->serializeMeta($this)) {
+                $jsonapi['meta'] = $meta;
+            }
+
+            $document += ['jsonapi' => $jsonapi];
+
+            if ($meta = $this->documentMeta->getArrayCopy()) {
+                $document['meta'] = array_merge($document['meta'] ?? [], $meta);
+            }
+
+            if ($links = $this->documentLinks->getArrayCopy()) {
+                $document['links'] = array_merge($document['links'] ?? [], $links);
+            }
+
+            $response = $response->withBody(
+                Stream::create(
+                    json_encode(
+                        $document,
+                        JSON_HEX_TAG |
+                            JSON_HEX_APOS |
+                            JSON_HEX_AMP |
+                            JSON_HEX_QUOT |
+                            JSON_UNESCAPED_SLASHES,
+                    ),
+                ),
+            );
+        }
+
+        return $response;
+    }
 }
diff --git a/src/Endpoint/CollectionAction.php b/src/Endpoint/CollectionAction.php
@@ -16,8 +16,6 @@
 use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;
 use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;
 
-use function Tobyz\JsonApiServer\json_api_response;
-
 class CollectionAction implements Endpoint, OpenApiPathsProvider
 {
     use HasVisibility;
@@ -62,7 +60,7 @@ public function handle(Context $context): ?ResponseInterface
 
         ($this->handler)($context);
 
-        $response = json_api_response($this->buildDocument($context), status: 204);
+        $response = $context->createResponse($this->buildDocument($context))->withStatus(204);
 
         return $this->applyResponseHooks($response, $context);
     }
diff --git a/src/Endpoint/Concerns/BuildsDocument.php b/src/Endpoint/Concerns/BuildsDocument.php
@@ -13,18 +13,10 @@ private function buildDocument(Context $context): array
     {
         $document = [];
 
-        if ($meta = $context->documentMeta->getArrayCopy()) {
-            $document['meta'] = $meta;
-        }
-
         foreach ($this->serializeMeta($context) as $key => $value) {
             $document['meta'][$key] = $value;
         }
 
-        if ($links = $context->documentLinks->getArrayCopy()) {
-            $document['links'] = $links;
-        }
-
         return $document;
     }
 }
diff --git a/src/Endpoint/Create.php b/src/Endpoint/Create.php
@@ -22,7 +22,6 @@
 use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;
 
 use function Tobyz\JsonApiServer\has_value;
-use function Tobyz\JsonApiServer\json_api_response;
 use function Tobyz\JsonApiServer\set_value;
 
 class Create implements Endpoint, OpenApiPathsProvider
@@ -83,14 +82,14 @@ public function handle(Context $context): ?ResponseInterface
 
             if ($asyncResult !== null) {
                 if (is_string($asyncResult)) {
-                    $response = json_api_response($this->buildDocument($context))->withHeader(
+                    $response = $context->createResponse($this->buildDocument($context))->withHeader(
                         'Location',
                         $context->api->basePath . '/' . ltrim($asyncResult, '/'),
                     );
                 } else {
                     $context = $context->forModel([$this->asyncCollection], $asyncResult);
 
-                    $response = json_api_response(
+                    $response = $context->createResponse(
                         $this->buildResourceDocument($asyncResult, $context),
                     )->withHeader(
                         'Content-Location',
@@ -110,9 +109,9 @@ public function handle(Context $context): ?ResponseInterface
 
         $this->saveFields($context, $data, true);
 
-        $response = json_api_response(
-            $document = $this->buildResourceDocument($model, $context),
-        )->withStatus(201);
+        $response = $context
+            ->createResponse($document = $this->buildResourceDocument($model, $context))
+            ->withStatus(201);
 
         if ($location = $document['data']['links']['self'] ?? null) {
             $response = $response->withHeader('Location', $location);
diff --git a/src/Endpoint/Delete.php b/src/Endpoint/Delete.php
@@ -18,8 +18,6 @@
 use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;
 use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;
 
-use function Tobyz\JsonApiServer\json_api_response;
-
 class Delete implements Endpoint, OpenApiPathsProvider
 {
     use HasDescription;
@@ -64,7 +62,7 @@ public function handle(Context $context): ?ResponseInterface
 
         $resource->delete($model, $context);
 
-        $response = json_api_response($this->buildDocument($context), status: 204);
+        $response = $context->createResponse($this->buildDocument($context))->withStatus(204);
 
         return $this->applyResponseHooks($response, $context);
     }
diff --git a/src/Endpoint/Index.php b/src/Endpoint/Index.php
@@ -22,8 +22,6 @@
 use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;
 use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;
 
-use function Tobyz\JsonApiServer\json_api_response;
-
 class Index implements Endpoint, OpenApiPathsProvider
 {
     use HasDescription;
@@ -99,7 +97,7 @@ public function handle(Context $context): ?Response
 
         $document['links']['self'] ??= $context->currentUrl();
 
-        $response = json_api_response($document);
+        $response = $context->createResponse($document);
 
         return $this->applyResponseHooks($response, $context);
     }
diff --git a/src/Endpoint/ResourceAction.php b/src/Endpoint/ResourceAction.php
@@ -18,8 +18,6 @@
 use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;
 use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;
 
-use function Tobyz\JsonApiServer\json_api_response;
-
 class ResourceAction implements Endpoint, OpenApiPathsProvider
 {
     use HasVisibility;
@@ -72,7 +70,7 @@ public function handle(Context $context): ?ResponseInterface
 
         ($this->handler)($model, $context);
 
-        $response = json_api_response($this->buildResourceDocument($model, $context));
+        $response = $context->createResponse($this->buildResourceDocument($model, $context));
 
         return $this->applyResponseHooks($response, $context);
     }
diff --git a/src/Endpoint/Show.php b/src/Endpoint/Show.php
@@ -28,7 +28,6 @@
 use Tobyz\JsonApiServer\Schema\Field\Relationship;
 use Tobyz\JsonApiServer\Schema\Field\ToMany;
 
-use function Tobyz\JsonApiServer\json_api_response;
 use function Tobyz\JsonApiServer\resolve_value;
 
 class Show implements Endpoint, ResourceEndpoint, RelationshipEndpoint, OpenApiPathsProvider
@@ -73,7 +72,7 @@ public function handle(Context $context): ?ResponseInterface
         }
 
         if ($count === 2) {
-            $response = json_api_response($this->buildResourceDocument($model, $context));
+            $response = $context->createResponse($this->buildResourceDocument($model, $context));
 
             return $this->applyResponseHooks($response, $context);
         }
@@ -123,10 +122,10 @@ public function handle(Context $context): ?ResponseInterface
 
             $document['links']['self'] ??= $this->relatedLink($model, $relationshipField, $context);
 
-            return json_api_response($document);
+            return $context->createResponse($document);
         }
 
-        return json_api_response(
+        return $context->createResponse(
             $this->buildRelationshipDocument($relationshipField, $relatedData, $context),
         );
     }
@@ -158,7 +157,7 @@ public function seeOther(callable $callback): static
 
                 $location = $context->api->basePath . '/' . ltrim($result, '/');
 
-                return json_api_response(status: 303)->withHeader('Location', $location);
+                return $context->createResponse([])->withStatus(303)->withHeader('Location', $location);
             }
 
             return $response;
diff --git a/src/Endpoint/Update.php b/src/Endpoint/Update.php
@@ -30,7 +30,6 @@
 use Tobyz\JsonApiServer\Schema\Field\Relationship;
 use Tobyz\JsonApiServer\Schema\Field\ToMany;
 
-use function Tobyz\JsonApiServer\json_api_response;
 use function Tobyz\JsonApiServer\resolve_value;
 
 class Update implements Endpoint, OpenApiPathsProvider
@@ -274,7 +273,7 @@ private function updateResource(
 
         $this->saveFields($context, $data);
 
-        $response = json_api_response($this->buildResourceDocument($model, $context));
+        $response = $context->createResponse($this->buildResourceDocument($model, $context));
 
         return $this->applyResponseHooks($response, $context);
     }
@@ -285,7 +284,7 @@ private function showRelationship(
         Relationship $field,
         Context $context,
     ): ResponseInterface {
-        return json_api_response(
+        return $context->createResponse(
             $this->buildRelationshipDocument(
                 $field,
                 resolve_value($resource->getValue($model, $field, $context)),
diff --git a/src/Extension/Atomic/Atomic.php b/src/Extension/Atomic/Atomic.php
@@ -13,8 +13,6 @@
 use Tobyz\JsonApiServer\Extension\Atomic\Exception\InvalidAtomicOperationsException;
 use Tobyz\JsonApiServer\Extension\Extension;
 
-use function Tobyz\JsonApiServer\json_api_response;
-
 class Atomic extends Extension
 {
     public const URI = 'https://jsonapi.org/ext/atomic';
@@ -69,7 +67,7 @@ public function handle(Context $context): ?Response
             $results[] = json_decode($response->getBody(), true);
         }
 
-        return json_api_response(['atomic:results' => $results]);
+        return $context->createResponse(['atomic:results' => $results]);
     }
 
     private function add(Context $context, array $operation, array &$lids): Response
diff --git a/src/JsonApi.php b/src/JsonApi.php
@@ -4,8 +4,10 @@
 
 use HttpAccept\ContentTypeParser;
 use InvalidArgumentException;
-use Psr\Http\Message\ResponseInterface as Response;
-use Psr\Http\Message\ServerRequestInterface as Request;
+use Nyholm\Psr7\ServerRequest;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Message\ServerServerRequestInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 use Tobyz\JsonApiServer\Exception\ErrorProvider;
 use Tobyz\JsonApiServer\Exception\InternalServerErrorException;
@@ -18,9 +20,12 @@
 use Tobyz\JsonApiServer\Extension\Extension;
 use Tobyz\JsonApiServer\Resource\Collection;
 use Tobyz\JsonApiServer\Resource\Resource;
+use Tobyz\JsonApiServer\Schema\Concerns\HasMeta;
 
 class JsonApi implements RequestHandlerInterface
 {
+    use HasMeta;
+
     public const MEDIA_TYPE = 'application/vnd.api+json';
     public const VERSION = '1.1';
 
@@ -131,7 +136,7 @@ public function errors(array $errors): static
     /**
      * Handle a request.
      */
-    public function handle(Request $request): Response
+    public function handle(ServerRequestInterface $request): ResponseInterface
     {
         $this->validateQueryParameters($request);
 
@@ -172,7 +177,7 @@ public function handle(Request $request): Response
         return $response->withAddedHeader('Vary', 'Accept');
     }
 
-    private function runExtensions(Context $context): ?Response
+    private function runExtensions(Context $context): ?ResponseInterface
     {
         $contentTypeExtensionUris = $this->getContentTypeExtensionUris($context->request);
         $acceptExtensionUris = $context->requestedExtensions();
@@ -195,7 +200,7 @@ private function runExtensions(Context $context): ?Response
         return null;
     }
 
-    private function validateQueryParameters(Request $request): void
+    private function validateQueryParameters(ServerRequestInterface $request): void
     {
         foreach ($request->getQueryParams() as $key => $value) {
             if (
@@ -209,7 +214,7 @@ private function validateQueryParameters(Request $request): void
         }
     }
 
-    private function getContentTypeExtensionUris(Request $request): array
+    private function getContentTypeExtensionUris(ServerRequestInterface $request): array
     {
         if (!($contentType = $request->getHeaderLine('Content-Type'))) {
             return [];
@@ -241,7 +246,7 @@ private function getContentTypeExtensionUris(Request $request): array
     /**
      * Convert an exception into a JSON:API error document response.
      */
-    public function error($e): Response
+    public function error($e): ResponseInterface
     {
         if ($e instanceof JsonApiErrorsException) {
             $errors = $e->errors;
@@ -251,12 +256,13 @@ public function error($e): Response
             }
             $errors = [$e];
         }
+
         $status = $e->getJsonApiStatus();
+        $context = new Context($this, new ServerRequest('GET', '/'));
 
-        return json_api_response(
-            ['errors' => array_map($this->formatError(...), $errors)],
-            $status,
-        );
+        return $context
+            ->createResponse(['errors' => array_map($this->formatError(...), $errors)])
+            ->withStatus($status);
     }
 
     private function formatError(ErrorProvider $exception): array
diff --git a/src/Schema/Concerns/HasMeta.php b/src/Schema/Concerns/HasMeta.php
diff --git a/src/functions.php b/src/functions.php
diff --git a/tests/specification/JsonApiObjectTest.php b/tests/specification/JsonApiObjectTest.php

Original file line number	Diff line number	Diff line change
`@@ -94,5 +94,8 @@ class Context`
`94`	`94`
`95`	`95`	`// Activate a JSON:API profile for the current response`
`96`	`96`	`public function activateProfile(string $uri): static;`
	`97`	`+`
	`98`	`+ // Create a JSON:API response with document data`
	`99`	`+ public function createResponse(array $document): Response;`
`97`	`100`	`}`
`98`	`101`	```
Original file line number	Diff line number	Diff line change
`@@ -21,8 +21,6 @@ use Psr\Http\Message\ResponseInterface;`
`21`	`21`	`use Tobyz\JsonApiServer\Context\Context;`
`22`	`22`	`use Tobyz\JsonApiServer\Extension\Extension;`
`23`	`23`
`24`		`-use function Tobyz\JsonApiServer\json_api_response;`
`25`		`-`
`26`	`24`	`class MyExtension extends Extension`
`27`	`25`	`{`
`28`	`26`	`public function uri(): string`
`@@ -33,7 +31,7 @@ class MyExtension extends Extension`
`33`	`31`	`public function handle(Context $context): ?ResponseInterface`
`34`	`32`	`{`
`35`	`33`	`if ($context->path() === 'my-extension') {`
`36`		`- return json_api_response([`
	`34`	`+ return $context->createResponse([`
`37`	`35`	`'my-extension:greeting' => 'Hello world!',`
`38`	`36`	`]);`
`39`	`37`	`}`
Original file line number	Diff line number	Diff line change
`@@ -16,8 +16,6 @@`
`16`	`16`	`use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;`
`17`	`17`	`use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;`
`18`	`18`
`19`		`-use function Tobyz\JsonApiServer\json_api_response;`
`20`		`-`
`21`	`19`	`class CollectionAction implements Endpoint, OpenApiPathsProvider`
`22`	`20`	`{`
`23`	`21`	`use HasVisibility;`
`@@ -62,7 +60,7 @@ public function handle(Context $context): ?ResponseInterface`
`62`	`60`
`63`	`61`	`($this->handler)($context);`
`64`	`62`
`65`		`- $response = json_api_response($this->buildDocument($context), status: 204);`
	`63`	`+ $response = $context->createResponse($this->buildDocument($context))->withStatus(204);`
`66`	`64`
`67`	`65`	`return $this->applyResponseHooks($response, $context);`
`68`	`66`	`}`
Original file line number	Diff line number	Diff line change
`@@ -13,18 +13,10 @@ private function buildDocument(Context $context): array`
`13`	`13`	`{`
`14`	`14`	`$document = [];`
`15`	`15`
`16`		`- if ($meta = $context->documentMeta->getArrayCopy()) {`
`17`		`- $document['meta'] = $meta;`
`18`		`- }`
`19`		`-`
`20`	`16`	`foreach ($this->serializeMeta($context) as $key => $value) {`
`21`	`17`	`$document['meta'][$key] = $value;`
`22`	`18`	`}`
`23`	`19`
`24`		`- if ($links = $context->documentLinks->getArrayCopy()) {`
`25`		`- $document['links'] = $links;`
`26`		`- }`
`27`		`-`
`28`	`20`	`return $document;`
`29`	`21`	`}`
`30`	`22`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,8 +18,6 @@`
`18`	`18`	`use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;`
`19`	`19`	`use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;`
`20`	`20`
`21`		`-use function Tobyz\JsonApiServer\json_api_response;`
`22`		`-`
`23`	`21`	`class Delete implements Endpoint, OpenApiPathsProvider`
`24`	`22`	`{`
`25`	`23`	`use HasDescription;`
`@@ -64,7 +62,7 @@ public function handle(Context $context): ?ResponseInterface`
`64`	`62`
`65`	`63`	`$resource->delete($model, $context);`
`66`	`64`
`67`		`- $response = json_api_response($this->buildDocument($context), status: 204);`
	`65`	`+ $response = $context->createResponse($this->buildDocument($context))->withStatus(204);`
`68`	`66`
`69`	`67`	`return $this->applyResponseHooks($response, $context);`
`70`	`68`	`}`
Original file line number	Diff line number	Diff line change
`@@ -22,8 +22,6 @@`
`22`	`22`	`use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;`
`23`	`23`	`use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;`
`24`	`24`
`25`		`-use function Tobyz\JsonApiServer\json_api_response;`
`26`		`-`
`27`	`25`	`class Index implements Endpoint, OpenApiPathsProvider`
`28`	`26`	`{`
`29`	`27`	`use HasDescription;`
`@@ -99,7 +97,7 @@ public function handle(Context $context): ?Response`
`99`	`97`
`100`	`98`	`$document['links']['self'] ??= $context->currentUrl();`
`101`	`99`
`102`		`- $response = json_api_response($document);`
	`100`	`+ $response = $context->createResponse($document);`
`103`	`101`
`104`	`102`	`return $this->applyResponseHooks($response, $context);`
`105`	`103`	`}`