Add Create/Update::saved() hook

Author: tobyzerner

CHANGELOG.md

@@ -77,6 +77,8 @@ and this project adheres to
       `Header` schema class
     - Add `Endpoint::response()` method for defining custom response callbacks
     - Add `Endpoint::schema()` method for defining custom schema
+    - Add `Create::saved()` and `Update::saved()` to register callbacks after
+      the model/fields are saved, but before the response is serialized
 - Add ability to customize error objects
     - Add specific exception classes for all errors
     - Add `JsonApi::errors(array $overrides)` method to register error object

docs/create.md

@@ -95,3 +95,14 @@ For Laravel applications with Eloquent-backed resources, you can extend the
 interface for you. Learn more on the
 [Laravel Integration](laravel.md#eloquent-resources) page.  
 :::
+
+## Post-processing
+
+Run logic after every field has been persisted but before the response document
+is built by chaining `saved`:
+
+```php
+Create::make()->saved(function ($model, Context $context) {
+    // e.g. dispatch an event or tweak the model before serialization
+});
+```

docs/update.md

@@ -97,6 +97,17 @@ interface for you. Learn more on the
 [Laravel Integration](laravel.md#eloquent-resources) page.  
 :::
 
+## Post-processing
+
+If you need to perform work after every field has been saved but before the
+response document is produced, register a `saved` callback:
+
+```php
+Update::make()->saved(function ($model, Context $context) {
+    // e.g. refresh aggregates or mutate the context prior to serialization
+});
+```
+
 ## Modifying To-Many Relationships
 
 By default, the JSON:API `POST` and `DELETE` relationship routes behave like a

src/Endpoint/Concerns/HasSavedCallbacks.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Tobyz\JsonApiServer\Endpoint\Concerns;
+
+use Closure;
+use Tobyz\JsonApiServer\Context;
+
+trait HasSavedCallbacks
+{
+    /**
+     * @var Closure[]
+     */
+    protected array $savedCallbacks = [];
+
+    /**
+     * Register a callback to run after the resource has been persisted but before the response is built.
+     */
+    public function saved(Closure $callback): static
+    {
+        $this->savedCallbacks[] = $callback;
+
+        return $this;
+    }
+
+    protected function runSavedCallbacks(Context $context): Context
+    {
+        foreach ($this->savedCallbacks as $callback) {
+            $result = isset($context->model)
+                ? $callback($context->model, $context)
+                : $callback($context);
+
+            if ($result instanceof Context) {
+                $context = $result;
+            }
+        }
+
+        return $context;
+    }
+}

src/Endpoint/Create.php

@@ -6,6 +6,7 @@
 use Psr\Http\Message\ResponseInterface;
 use RuntimeException;
 use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\Endpoint\Concerns\HasSavedCallbacks;
 use Tobyz\JsonApiServer\Endpoint\Concerns\HasParameters;
 use Tobyz\JsonApiServer\Endpoint\Concerns\HasResponse;
 use Tobyz\JsonApiServer\Endpoint\Concerns\MutatesResource;
@@ -27,6 +28,7 @@ class Create implements Endpoint, ProvidesRootSchema
 {
     use HasVisibility;
     use HasParameters;
+    use HasSavedCallbacks;
     use HasResponse;
     use HasSchema;
     use MutatesResource;
@@ -111,6 +113,8 @@ public function handle(Context $context): ?ResponseInterface
 
         $this->saveFields($context, true);
 
+        $context = $this->runSavedCallbacks($context);
+
         $response = $this->createResponse(
             $document = $this->serializeResourceDocument($model, $context),
             $context,

src/Endpoint/Update.php

@@ -71,6 +71,13 @@ public function response(Closure $callback): static
         return $this;
     }
 
+    public function saved(Closure $callback): static
+    {
+        $this->updateResource->saved($callback);
+
+        return $this;
+    }
+
     public function headers(array $headers): static
     {
         $this->updateResource->headers($headers);

src/Endpoint/UpdateResource.php

@@ -5,6 +5,7 @@
 use Psr\Http\Message\ResponseInterface;
 use RuntimeException;
 use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\Endpoint\Concerns\HasSavedCallbacks;
 use Tobyz\JsonApiServer\Endpoint\Concerns\HasParameters;
 use Tobyz\JsonApiServer\Endpoint\Concerns\HasResponse;
 use Tobyz\JsonApiServer\Endpoint\Concerns\MutatesResource;
@@ -22,6 +23,7 @@
 class UpdateResource implements Endpoint, ProvidesRootSchema, ProvidesResourceLinks
 {
     use HasParameters;
+    use HasSavedCallbacks;
     use HasResponse;
     use HasSchema;
     use ResolvesModel;
@@ -68,6 +70,8 @@ public function handle(Context $context): ?ResponseInterface
 
         $this->saveFields($context);
 
+        $context = $this->runSavedCallbacks($context);
+
         return $this->createResponse(
             $this->serializeResourceDocument($context->model, $context),
             $context,

tests/feature/EndpointResponseTest.php

@@ -11,6 +11,7 @@
 use Tobyz\JsonApiServer\Endpoint\Show;
 use Tobyz\JsonApiServer\Endpoint\Update;
 use Tobyz\JsonApiServer\JsonApi;
+use Tobyz\JsonApiServer\Schema\Field\Attribute;
 use Tobyz\JsonApiServer\Schema\Header;
 use Tobyz\JsonApiServer\Schema\Type\Integer;
 use Tobyz\Tests\JsonApiServer\AbstractTestCase;
@@ -91,4 +92,65 @@ public function test_response_callback(
 
         $this->assertEquals('executed', $response->getHeaderLine('X-Callback'));
     }
+
+    public function test_create_after_callback_runs_before_response()
+    {
+        $api = new JsonApi();
+
+        $endpoint = Create::make()->saved(function ($model): void {
+            $model->after = 'executed';
+        });
+
+        $api->resource(
+            new MockResource(
+                'users',
+                endpoints: [$endpoint],
+                fields: [
+                    Attribute::make('after')->get(fn($model, $context) => $model->after ?? null),
+                ],
+            ),
+        );
+
+        $response = $api->handle(
+            $this->buildRequest('POST', '/users')->withParsedBody([
+                'data' => ['type' => 'users'],
+            ]),
+        );
+
+        $this->assertJsonApiDocumentSubset(
+            ['data' => ['attributes' => ['after' => 'executed']]],
+            $response->getBody(),
+        );
+    }
+
+    public function test_update_after_callback_runs_before_response()
+    {
+        $api = new JsonApi();
+
+        $endpoint = Update::make()->saved(function ($model): void {
+            $model->after = 'executed';
+        });
+
+        $api->resource(
+            new MockResource(
+                'users',
+                models: [(object) ['id' => '1']],
+                endpoints: [$endpoint],
+                fields: [
+                    Attribute::make('after')->get(fn($model, $context) => $model->after ?? null),
+                ],
+            ),
+        );
+
+        $response = $api->handle(
+            $this->buildRequest('PATCH', '/users/1')->withParsedBody([
+                'data' => ['type' => 'users', 'id' => '1'],
+            ]),
+        );
+
+        $this->assertJsonApiDocumentSubset(
+            ['data' => ['attributes' => ['after' => 'executed']]],
+            $response->getBody(),
+        );
+    }
 }