Merge pull request #47 from swisnl/feature/meta-and-links

Meta and links

Author: JaZo

CHANGELOG.md

@@ -9,6 +9,34 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Added
 
 * Added `take` method to `Repository` to allow fetching resources without id.
+* Added links and meta to `ItemInterface`.
+N.B. This is a breaking change if you implement the `ItemInterface` yourself instead of using the supplied `Item`.
+* Added `Jsonapi` class.
+* Added links and meta to `OneRelationInterface` and `ManyRelationInterface`.
+N.B. This is a breaking change if you implement (one of) these interfaces yourself instead of using the supplied relations.
+* Added `Link` and `Links` classes.
+* Added links to `Error`.
+
+### Changed
+
+* `Error::getMeta()` now returns a `Meta` instance instead of an `ErrorMeta` instance. The `Meta` class does not have the `has` and `get` methods, but uses magic overloading methods (e.g. `__get` and `__set`) just like `Item`.
+N.B. This is a breaking change if you use meta on errors.
+* `DocumentInterface::getLinks()` now returns a `Links` instance instead of a plain array. If no links are present, it returns `null`. All implementations have been updated to reflect these changes.
+N.B. This is a minor breaking change if you use links on documents.
+* `DocumentInterface::getMeta()` now returns a `Meta` instance instead of a plain array. If no meta is present, it returns `null`. All implementations have been updated to reflect these changes.
+N.B. This is a minor breaking change if you use meta on documents.
+* `DocumentInterface::getJsonapi()` now returns a `Jsonapi` instance instead of a plain array. If no jsonapi is present, it returns `null`. All implementations have been updated to reflect these changes.
+* Parameters for `ItemInterface::setRelation()` have changed to include optional `Links` and `Meta` objects.
+* `JsonApi\ErrorsParser`, `JsonApi\Hydrator` and `JsonApi\Parser` have an extra dependency in their constructor.
+N.B. Make sure to add this dependency if you've overwritten `ServiceProvider::registerParser` or construct the `JsonApi\Parser` yourself.
+
+### Removed
+
+* Removed `ErrorMeta` class in favor of generic `Meta` class.
+
+### Fixed
+
+* Fixed parsing of [JSON:API object](https://jsonapi.org/format/#document-jsonapi-object) in document.
 
 ## [0.14.0] - 2019-01-23
 

README.MD

@@ -149,6 +149,56 @@ class BlogItem extends Item
 This package uses [Laravel Collections](https://laravel.com/docs/collections) as a wrapper for item arrays.
 
 
+## Links
+
+All objects that can have links use an instance of `Links` to store their links.
+These are in turn an instance of `Link`.
+
+### Example
+
+Given the following JSON:
+``` json
+{
+    "data": [],
+    "links": {
+        "self": "http://example.com/test"
+    }
+}
+```
+
+You can get the links this way:
+``` php
+/** @var $document \Swis\JsonApi\Client\Document */
+$links = $document->getLinks();
+echo $links->self->getHref(); // http://example.com/test
+```
+
+
+## Meta
+
+All objects that can have meta information use an instance of `Meta` to store their metadata.
+This is a simple array-like object with key-value pairs.
+
+### Example
+
+Given the following JSON:
+``` json
+{
+    "data": [],
+    "meta": {
+        "foo": "bar"
+    }
+}
+```
+
+You can get the meta this way:
+``` php
+/** @var $document \Swis\JsonApi\Client\Document */
+$meta = $document->getMeta();
+echo $meta->foo; // bar
+```
+
+
 ## TypeMapper
 
 All custom models must be registered with the `TypeMapper`.

src/Document.php

@@ -5,24 +5,18 @@
 use Swis\JsonApi\Client\Errors\ErrorCollection;
 use Swis\JsonApi\Client\Interfaces\DataInterface;
 use Swis\JsonApi\Client\Interfaces\DocumentInterface;
+use Swis\JsonApi\Client\Traits\HasLinks;
+use Swis\JsonApi\Client\Traits\HasMeta;
 
 class Document implements DocumentInterface
 {
+    use HasLinks, HasMeta;
+
     /**
      * @var \Swis\JsonApi\Client\Interfaces\DataInterface
      */
     protected $data;
 
-    /**
-     * @var array
-     */
-    protected $meta = [];
-
-    /**
-     * @var array
-     */
-    protected $links = [];
-
     /**
      * @var \Swis\JsonApi\Client\Errors\ErrorCollection
      */
@@ -34,48 +28,16 @@ class Document implements DocumentInterface
     protected $included;
 
     /**
-     * @var array
+     * @var \Swis\JsonApi\Client\Jsonapi|null
      */
-    protected $jsonapi = [];
+    protected $jsonapi;
 
     public function __construct()
     {
         $this->errors = new ErrorCollection();
         $this->included = new Collection();
     }
 
-    /**
-     * @return array
-     */
-    public function getMeta(): array
-    {
-        return $this->meta;
-    }
-
-    /**
-     * @param array $meta
-     */
-    public function setMeta(array $meta)
-    {
-        $this->meta = $meta;
-    }
-
-    /**
-     * @return array
-     */
-    public function getLinks(): array
-    {
-        return $this->links;
-    }
-
-    /**
-     * @param array $links
-     */
-    public function setLinks(array $links)
-    {
-        $this->links = $links;
-    }
-
     /**
      * @return \Swis\JsonApi\Client\Errors\ErrorCollection
      */
@@ -129,17 +91,17 @@ public function setIncluded(Collection $included)
     }
 
     /**
-     * @return array
+     * @return \Swis\JsonApi\Client\Jsonapi|null
      */
-    public function getJsonapi(): array
+    public function getJsonapi()
     {
         return $this->jsonapi;
     }
 
     /**
-     * @param array $jsonapi
+     * @param \Swis\JsonApi\Client\Jsonapi|null $jsonapi
      */
-    public function setJsonapi(array $jsonapi)
+    public function setJsonapi(Jsonapi $jsonapi = null)
     {
         $this->jsonapi = $jsonapi;
     }
@@ -186,8 +148,8 @@ public function toArray(): array
     {
         $document = [];
 
-        if (!empty($this->getLinks())) {
-            $document['links'] = $this->links;
+        if ($this->getLinks() !== null) {
+            $document['links'] = $this->getLinks()->toArray();
         }
 
         if (!empty($this->getData())) {
@@ -198,16 +160,16 @@ public function toArray(): array
             $document['included'] = $this->getIncluded()->toJsonApiArray();
         }
 
-        if (!empty($this->getMeta())) {
-            $document['meta'] = $this->meta;
+        if ($this->getMeta() !== null) {
+            $document['meta'] = $this->getMeta()->toArray();
         }
 
         if ($this->hasErrors()) {
             $document['errors'] = $this->errors->toArray();
         }
 
-        if (!empty($this->getJsonapi())) {
-            $document['jsonapi'] = $this->jsonapi;
+        if ($this->getJsonapi() !== null) {
+            $document['jsonapi'] = $this->getJsonapi()->toArray();
         }
 
         return $document;

src/Errors/Error.php

@@ -2,8 +2,15 @@
 
 namespace Swis\JsonApi\Client\Errors;
 
+use Swis\JsonApi\Client\Links;
+use Swis\JsonApi\Client\Meta;
+use Swis\JsonApi\Client\Traits\HasLinks;
+use Swis\JsonApi\Client\Traits\HasMeta;
+
 class Error
 {
+    use HasLinks, HasMeta;
+
     /**
      * @var string|null
      */
@@ -34,30 +41,28 @@ class Error
      */
     protected $source;
 
-    /**
-     * @var \Swis\JsonApi\Client\Errors\ErrorMeta|null
-     */
-    protected $meta;
-
     /**
      * @param string|null                                  $id
+     * @param \Swis\JsonApi\Client\Links|null              $links
      * @param string|null                                  $status
      * @param string|null                                  $code
      * @param string|null                                  $title
      * @param string|null                                  $detail
      * @param \Swis\JsonApi\Client\Errors\ErrorSource|null $source
-     * @param \Swis\JsonApi\Client\Errors\ErrorMeta|null   $meta
+     * @param \Swis\JsonApi\Client\Meta|null               $meta
      */
     public function __construct(
         string $id = null,
+        Links $links = null,
         string $status = null,
         string $code = null,
         string $title = null,
         string $detail = null,
         ErrorSource $source = null,
-        ErrorMeta $meta = null
+        Meta $meta = null
     ) {
         $this->id = $id;
+        $this->links = $links;
         $this->status = $status;
         $this->code = $code;
         $this->title = $title;
@@ -113,12 +118,4 @@ public function getSource()
     {
         return $this->source;
     }
-
-    /**
-     * @return \Swis\JsonApi\Client\Errors\ErrorMeta|null
-     */
-    public function getMeta()
-    {
-        return $this->meta;
-    }
 }

src/Errors/ErrorMeta.php

@@ -23,22 +23,22 @@ public function getErrors(): ErrorCollection;
     public function hasErrors(): bool;
 
     /**
-     * @return mixed
+     * @return \Swis\JsonApi\Client\Meta|null
      */
-    public function getMeta(): array;
+    public function getMeta();
 
     /**
-     * @return mixed
+     * @return \Swis\JsonApi\Client\Links|null
      */
-    public function getLinks(): array;
+    public function getLinks();
 
     /**
      * @return mixed
      */
     public function getIncluded(): Collection;
 
     /**
-     * @return mixed
+     * @return \Swis\JsonApi\Client\Jsonapi|null
      */
     public function getJsonapi();