Allow serializers to add metadata

README.md

@@ -131,7 +131,7 @@ $document->addPaginationLinks(
  100 // The total number of results
 );
 ```
-Serializers can provide links as well:
+Serializers can provide links and/or meta data as well:
 
 ```php
 use Tobscure\JsonApi\AbstractSerializer;
@@ -143,8 +143,14 @@ class PostSerializer extends AbstractSerializer
  public function getLinks($post) {
  return ['self' => '/posts/' . $post->id];
  }
+
+ public function getMeta($post) {
+ return ['some' => 'metadata for ' . $post->id];
+ }
 }
 
+**Note:** Links and metadata of the resource overrule ones with the same key from the serializer!
+
 ### Parameters
 
 The `Tobscure\JsonApi\Parameters` class allows you to easily parse and validate query parameters in accordance with the specification.

src/AbstractSerializer.php

@@ -54,6 +54,14 @@ public function getLinks($model)
  return [];
  }
 
+ /**
+ * {@inheritdoc}
+ */
+ public function getMeta($model)
+ {
+ return [];
+ }
+
  /**
  * {@inheritdoc}
  *

src/Resource.php

@@ -92,6 +92,18 @@ public function toArray()
  $array['links'] = $links;
  }
 
+ $meta = [];
+ if (! empty($this->meta)) {
+ $meta = $this->meta;
+ }
+ $serializerMeta = $this->serializer->getMeta($this->data);
+ if (! empty($serializerMeta)) {
+ $meta = array_merge($serializerMeta, $meta);
+ }
+ if (! empty($meta)) {
+ $array['meta'] = $meta;
+ }
+
  return $array;
  }
 

src/SerializerInterface.php

@@ -46,6 +46,14 @@ public function getAttributes($model, array $fields = null);
  */
  public function getLinks($model);
 
+ /**
+ * Get the meta.
+ *
+ * @param mixed $model
+ * @return array
+ */
+ public function getMeta($model);
+
  /**
  * Get a relationship.
  *

tests/ResourceTest.php

@@ -23,7 +23,7 @@ public function testToArrayReturnsArray()
  {
  $data = (object) ['id' => '123', 'foo' => 'bar', 'baz' => 'qux'];
 
- $resource = new Resource($data, new PostSerializer4WithLinks);
+ $resource = new Resource($data, new PostSerializer4WithLinksAndMeta);
 
  $this->assertEquals([
  'type' => 'posts',
@@ -35,6 +35,9 @@ public function testToArrayReturnsArray()
  'links' => [
  'self' => '/posts/123'
  ],
+ 'meta' => [
+ 'some-meta' => 'from-serializer-for-123'
+ ]
  ], $resource->toArray());
  }
 
@@ -126,7 +129,7 @@ public function testLinksMergeWithSerializerLinks()
  {
  $post1 = (object) ['id' => '123', 'foo' => 'bar', 'comments' => [1]];
 
- $resource1 = new Resource($post1, new PostSerializer4WithLinks());
+ $resource1 = new Resource($post1, new PostSerializer4WithLinksAndMeta());
  $resource1->addLink('self', 'overridden/by/resource');
  $resource1->addLink('related', '/some/other/comment');
 
@@ -140,6 +143,31 @@ public function testLinksMergeWithSerializerLinks()
  'self' => 'overridden/by/resource',
  'related' => '/some/other/comment'
  ],
+ 'meta' => [
+ 'some-meta' => 'from-serializer-for-123'
+ ]
+ ], $resource1->toArray());
+ }
+
+ public function testMetaMergeWithSerializerLinks()
+ {
+ $post1 = (object) ['id' => '123', 'foo' => 'bar', 'comments' => [1]];
+
+ $resource1 = new Resource($post1, new PostSerializer4WithLinksAndMeta());
+ $resource1->addMeta('some-meta', 'overridden-by-resource');
+
+ $this->assertEquals([
+ 'type' => 'posts',
+ 'id' => '123',
+ 'attributes' => [
+ 'foo' => 'bar'
+ ],
+ 'links' => [
+ 'self' => '/posts/123'
+ ],
+ 'meta' => [
+ 'some-meta' => 'overridden-by-resource'
+ ]
  ], $resource1->toArray());
  }
 }
@@ -167,12 +195,17 @@ public function comments($post)
  return new Relationship(new Collection($post->comments, new CommentSerializer));
  }
 }
-class PostSerializer4WithLinks extends PostSerializer4
+class PostSerializer4WithLinksAndMeta extends PostSerializer4
 {
  public function getLinks($post)
  {
  return ['self' => sprintf('/posts/%s', $post->id)];
  }
+
+ public function getMeta($post)
+ {
+ return ['some-meta' => sprintf('from-serializer-for-%s', $post->id)];
+ }
 }
 
 class CommentSerializer extends AbstractSerializer