Merge branch 'release/1.0.0-beta.1' into main

Author: lindyhopchris

CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file. This project adheres to
 [Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
 
+## [1.0.0-beta.1] - 2021-03-30
+
+### Changed
+
+- Updated the encoder to implement changes made to the encoder interface. This removes the `withIdentifiers()` method
+  and replaces it with the `withToOne()` and `withToMany()` methods.
+
+### Fixed
+
+- When encoding relationships, do not yield a relationship value that is empty (no data, links or meta).
+
 ## [1.0.0-alpha.4] - 2021-02-27
 
 ### Changed

composer.json

@@ -26,7 +26,7 @@
         "php": "^7.4|^8.0",
         "ext-json": "*",
         "illuminate/support": "^8.0",
-        "laravel-json-api/core": "^1.0.0-alpha.4",
+        "laravel-json-api/core": "^1.0.0-beta.1",
         "laravel-json-api/neomerx-json-api": "^4.0.2"
     },
     "require-dev": {

src/Encoder.php

@@ -125,11 +125,9 @@ public function withFieldSets($fieldSets): self
      */
     public function withResource(?object $resource): DocumentContract
     {
-        if (is_object($resource) && !$resource instanceof JsonApiResource) {
-            $resource = $this->resources->create($resource);
-        }
-
-        return $this->createCompoundDocument($resource);
+        return $this->createCompoundDocument(
+            $resource ? $this->toResource($resource) : null
+        );
     }
 
     /**
@@ -145,19 +143,25 @@ public function withResources(iterable $resources): DocumentContract
     /**
      * @inheritDoc
      */
-    public function withIdentifiers(object $resource, string $fieldName, $identifiers): DocumentContract
+    public function withToOne(object $resource, string $fieldName, ?object $related): DocumentContract
     {
-        $document = new RelationshipDocument(
-            $this->createNeomerxEncoder(),
-            $this->mapper,
+        return $this->createRelationshipDocument(
             $resource,
             $fieldName,
-            $identifiers
+            $related ? $this->toResource($related) : null,
         );
+    }
 
-        $document->withJsonApi($this->version);
-
-        return $document;
+    /**
+     * @inheritDoc
+     */
+    public function withToMany(object $resource, string $fieldName, iterable $related): DocumentContract
+    {
+        return $this->createRelationshipDocument(
+            $resource,
+            $fieldName,
+            $this->resources->cursor($related),
+        );
     }
 
     /**
@@ -172,6 +176,31 @@ private function createCompoundDocument($data): DocumentContract
         return $document;
     }
 
+    /**
+     * @param object $resource
+     * @param string $fieldName
+     * @param $identifiers
+     * @return RelationshipDocument
+     */
+    private function createRelationshipDocument(
+        object $resource,
+        string $fieldName,
+        $identifiers
+    ): RelationshipDocument
+    {
+        $document = new RelationshipDocument(
+            $this->createNeomerxEncoder(),
+            $this->mapper,
+            $this->toResource($resource),
+            $fieldName,
+            $identifiers
+        );
+
+        $document->withJsonApi($this->version);
+
+        return $document;
+    }
+
     /**
      * Create a new encoder instance.
      *
@@ -198,4 +227,17 @@ private function createNeomerxEncoder(): ExtendedEncoder
 
         return $encoder;
     }
+
+    /**
+     * @param object $object
+     * @return JsonApiResource
+     */
+    private function toResource(object $object): JsonApiResource
+    {
+        if ($object instanceof JsonApiResource) {
+            return $object;
+        }
+
+        return $this->resources->create($object);
+    }
 }

src/RelationshipDocument.php

@@ -19,15 +19,16 @@
 
 namespace LaravelJsonApi\Encoder\Neomerx;
 
+use LaravelJsonApi\Core\Resources\JsonApiResource;
 use LaravelJsonApi\Encoder\Neomerx\Encoder\Encoder as ExtendedEncoder;
 
 class RelationshipDocument extends Document
 {
 
     /**
-     * @var object
+     * @var JsonApiResource
      */
-    private object $resource;
+    private JsonApiResource $resource;
 
     /**
      * @var string
@@ -44,14 +45,14 @@ class RelationshipDocument extends Document
      *
      * @param ExtendedEncoder $encoder
      * @param Mapper $mapper
-     * @param object $resource
+     * @param JsonApiResource $resource
      * @param string $fieldName
      * @param object|iterable|null $data
      */
     public function __construct(
         ExtendedEncoder $encoder,
         Mapper $mapper,
-        object $resource,
+        JsonApiResource $resource,
         string $fieldName,
         $data
     ) {

src/Schema/Relation.php

@@ -22,7 +22,6 @@
 use LaravelJsonApi\Contracts\Resources\Container;
 use LaravelJsonApi\Contracts\Resources\JsonApiRelation;
 use LaravelJsonApi\Core\Document\ResourceIdentifier;
-use LaravelJsonApi\Core\Json\Hash;
 use LaravelJsonApi\Core\Resources\JsonApiResource;
 use LaravelJsonApi\Encoder\Neomerx\Mapper;
 use Neomerx\JsonApi\Contracts\Schema\ContextInterface;
@@ -63,11 +62,6 @@ final class Relation
      */
     private ContextInterface $context;
 
-    /**
-     * @var string
-     */
-    private string $fieldName;
-
     /**
      * Relation constructor.
      *
@@ -76,22 +70,19 @@ final class Relation
      * @param JsonApiRelation $object
      * @param SchemaFields $fields
      * @param ContextInterface $context
-     * @param string $fieldName
      */
     public function __construct(
         Container $container,
         Mapper $mapper,
         JsonApiRelation $object,
         SchemaFields $fields,
-        ContextInterface $context,
-        string $fieldName
+        ContextInterface $context
     ) {
         $this->container = $container;
         $this->mapper = $mapper;
         $this->relation = $object;
         $this->fields = $fields;
         $this->context = $context;
-        $this->fieldName = $fieldName;
     }
 
     /**
@@ -119,7 +110,7 @@ public function toArray(): array
     {
         $relation = [];
         $links = $this->relation->links();
-        $meta = new Hash($this->relation->meta() ?: []);
+        $meta = $this->relation->meta();
 
         if ($this->willShowData()) {
             $relation[SchemaInterface::RELATIONSHIP_DATA] = $this->data();
@@ -131,7 +122,7 @@ public function toArray(): array
             );
         }
 
-        if ($meta->isNotEmpty()) {
+        if (!empty($meta)) {
             $relation[SchemaInterface::RELATIONSHIP_META] = $meta;
         }
 
@@ -149,7 +140,7 @@ private function willShowData(): bool
 
         return $this->fields->isRelationshipRequested(
             $this->context->getPosition()->getPath(),
-            $this->fieldName
+            $this->relation->fieldName(),
         );
     }
 

src/Schema/Relationships.php

@@ -107,18 +107,39 @@ public function getIterator()
             $fieldName = $relation->fieldName();
 
             if ($this->fields->isFieldRequested($this->resource->type(), $fieldName)) {
-                yield $fieldName => (new Relation(
-                    $this->container,
-                    $this->mapper,
-                    $relation,
-                    $this->fields,
-                    $this->context,
-                    $fieldName
-                ))->toArray();
+                $value = $this->convert($relation)->toArray();
+
+                /**
+                 * The value could be empty, in which case we should not yield it otherwise
+                 * the Neomerx encoder ends up encoding the relationship as an empty array.
+                 * An example of when this might be legitimately empty is when the relationship
+                 * is meta-only, but the meta value is controlled by the client (for example our
+                 * countable implementation) and the client hasn't requested it.
+                 */
+                if (!empty($value)) {
+                    yield $fieldName => $value;
+                }
             }
         }
     }
 
+    /**
+     * Convert a JSON:API relation to an schema relation.
+     *
+     * @param JsonApiRelation $relation
+     * @return Relation
+     */
+    private function convert(JsonApiRelation $relation): Relation
+    {
+        return new Relation(
+            $this->container,
+            $this->mapper,
+            $relation,
+            $this->fields,
+            $this->context,
+        );
+    }
+
     /**
      * @return iterable
      */