Support for adding relationship linkage meta

Author: tobyzerner

CHANGELOG.md

@@ -8,6 +8,15 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- Add `linkageMeta()` method to relationship fields for adding meta to resource
+  identifier objects in linkage
+
+### Changed
+
+- Various performance optimizations to improve serialization speed
+
 ## [1.0.0-beta.6] - 2025-10-02
 
 ### ⚠️ Breaking Changes

docs/relationships.md

@@ -50,10 +50,26 @@ ToOne::make('user')->withoutLinkage();
 ToMany::make('roles')->withLinkage();
 ```
 
-::: danger  
-Be careful when enabling linkage on to-many relationships as pagination is not
-supported.  
-:::
+::: danger Be careful when enabling linkage on to-many relationships as
+pagination is not supported. :::
+
+### Linkage Meta
+
+You can add
+[meta information](https://jsonapi.org/format/#document-resource-object-linkage)
+to resource identifier objects in relationship linkage using the `linkageMeta`
+method. This is useful for including additional data about the relationship
+itself, such as pivot table attributes.
+
+```php
+ToMany::make('roles')
+    ->withLinkage()
+    ->linkageMeta([
+        Attribute::make('assignedAt')->get(
+            fn($role) => $role->pivot->created_at,
+        ),
+    ]);
+```
 
 ## Relationship Mutations
 

src/Schema/Field/Relationship.php

@@ -18,6 +18,7 @@ abstract class Relationship extends Field
     public array $collections;
     public bool $includable = false;
     public bool|Closure $linkage = false;
+    public array $linkageMeta = [];
 
     /**
      * Set the collection(s) that this relationship is to.
@@ -75,6 +76,16 @@ public function withoutLinkage(): static
         return $this->withLinkage(false);
     }
 
+    /**
+     * Define meta fields for resource identifier objects in linkage.
+     */
+    public function linkageMeta(array $fields): static
+    {
+        $this->linkageMeta = array_merge($this->linkageMeta, $fields);
+
+        return $this;
+    }
+
     public function getValue(Context $context): mixed
     {
         if ($context->include === null && !$this->hasLinkage($context)) {
@@ -111,6 +122,36 @@ public function serializeValue($value, Context $context): mixed
 
     abstract protected function serializeData($value, Context $context): array;
 
+    protected function serializeIdentifier($model, Context $context): array
+    {
+        $context = $context->forModel($this->collections, $model);
+
+        $identifier = $context->serializer->addIncluded($context);
+
+        if ($meta = $this->serializeLinkageMeta($context)) {
+            $identifier['meta'] = $meta;
+        }
+
+        return $identifier;
+    }
+
+    protected function serializeLinkageMeta(Context $context): array
+    {
+        $meta = [];
+
+        foreach ($this->linkageMeta as $field) {
+            if (!$field->isVisible($context)) {
+                continue;
+            }
+
+            $value = $field->getValue($context);
+
+            $meta[$field->name] = $field->serializeValue($value, $context);
+        }
+
+        return $meta;
+    }
+
     public function hasLinkage(Context $context): mixed
     {
         if ($this->linkage instanceof Closure) {

src/Schema/Field/ToMany.php

@@ -96,12 +96,7 @@ protected function serializeData($value, Context $context): array
         $context = $context->withField($this);
 
         return [
-            'data' => array_map(
-                fn($model) => $context->serializer->addIncluded(
-                    $context->forModel($this->collections, $model),
-                ),
-                $value,
-            ),
+            'data' => array_map(fn($model) => $this->serializeIdentifier($model, $context), $value),
         ];
     }
 

src/Schema/Field/ToOne.php

@@ -29,13 +29,7 @@ protected function serializeData($value, Context $context): array
             return ['data' => null];
         }
 
-        $context = $context->withField($this);
-
-        return [
-            'data' => $context->serializer->addIncluded(
-                $context->forModel($this->collections, $value),
-            ),
-        ];
+        return ['data' => $this->serializeIdentifier($value, $context)];
     }
 
     public function deserializeValue(mixed $value, Context $context): mixed

tests/specification/MetaTest.php

@@ -87,6 +87,95 @@ public function test_to_many_relationship_meta()
         );
     }
 
+    public function test_to_one_linkage_meta()
+    {
+        $role = (object) ['id' => '1', 'name' => 'admin'];
+
+        $this->api->resource(
+            new MockResource(
+                'users',
+                models: [(object) ['id' => '1', 'role' => $role]],
+                endpoints: [Show::make()],
+                fields: [
+                    ToOne::make('role')
+                        ->get(fn($user) => $user->role)
+                        ->linkageMeta([Attribute::make('active')->get(fn() => true)]),
+                ],
+            ),
+        );
+
+        $this->api->resource(new MockResource('roles', models: [$role]));
+
+        $response = $this->api->handle($this->buildRequest('GET', '/users/1'));
+
+        $this->assertJsonApiDocumentSubset(
+            [
+                'data' => [
+                    'relationships' => [
+                        'role' => [
+                            'data' => [
+                                'type' => 'roles',
+                                'id' => '1',
+                                'meta' => ['active' => true],
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+            $response->getBody(),
+        );
+    }
+
+    public function test_to_many_linkage_meta()
+    {
+        $role1 = (object) ['id' => '1', 'name' => 'admin', 'assignedAt' => '2024-01-01'];
+        $role2 = (object) ['id' => '2', 'name' => 'editor', 'assignedAt' => '2024-01-02'];
+
+        $this->api->resource(
+            new MockResource(
+                'users',
+                models: [(object) ['id' => '1', 'roles' => [$role1, $role2]]],
+                endpoints: [Show::make()],
+                fields: [
+                    ToMany::make('roles')
+                        ->get(fn($user) => $user->roles)
+                        ->withLinkage()
+                        ->linkageMeta([
+                            Attribute::make('assignedAt')->get(fn($role) => $role->assignedAt),
+                        ]),
+                ],
+            ),
+        );
+
+        $this->api->resource(new MockResource('roles', models: [$role1, $role2]));
+
+        $response = $this->api->handle($this->buildRequest('GET', '/users/1'));
+
+        $this->assertJsonApiDocumentSubset(
+            [
+                'data' => [
+                    'relationships' => [
+                        'roles' => [
+                            'data' => [
+                                [
+                                    'type' => 'roles',
+                                    'id' => '1',
+                                    'meta' => ['assignedAt' => '2024-01-01'],
+                                ],
+                                [
+                                    'type' => 'roles',
+                                    'id' => '2',
+                                    'meta' => ['assignedAt' => '2024-01-02'],
+                                ],
+                            ],
+                        ],
+                    ],
+                ],
+            ],
+            $response->getBody(),
+        );
+    }
+
     public function test_show_endpoint_meta()
     {
         $this->api->resource(