[Feature] Add put methods to the resource object class

Author: lindyhopchris

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file. This projec
 Eloquent adapters now have a `filterWithScopes()` method, that maps JSON API filters to
 model scopes and the Eloquent `where*` method names. This is opt-in: i.e. to use, the
 developer must call `filterWithScopes()` within their adapter's `filter()` method.
+- Added `put`, `putAttr` and `putRelation` methods to the `ResourceObject` class.
 
 ## [1.3.1] - 2019-08-19
 

src/Document/ResourceObject.php

@@ -521,6 +521,58 @@ public function replace(string $field, $value): self
         throw new \OutOfBoundsException("Field {$field} is not an attribute or relationship.");
     }
 
+    /**
+     * Set a field.
+     *
+     * Sets the provided value as a relation if it is already defined as a relation.
+     * Otherwise, sets it as an attribute.
+     *
+     * @param string $field
+     * @param mixed|null $value
+     * @return ResourceObject
+     */
+    public function put(string $field, $value): self
+    {
+        if ($this->isRelationship($field)) {
+            return $this->putRelation($field, $value);
+        }
+
+        return $this->putAttr($field, $value);
+    }
+
+    /**
+     * Set an attribute.
+     *
+     * @param string $field
+     * @param mixed|null $value
+     * @return ResourceObject
+     */
+    public function putAttr(string $field, $value): self
+    {
+        $copy = clone $this;
+        $copy->attributes[$field] = $value;
+        $copy->normalize();
+
+        return $copy;
+    }
+
+    /**
+     * Set a relation.
+     *
+     * @param string $field
+     * @param array|null $value
+     * @return ResourceObject
+     */
+    public function putRelation(string $field, ?array $value): self
+    {
+        $copy = clone $this;
+        $copy->relationships[$field] = $copy->relationships[$field] ?? [];
+        $copy->relationships[$field]['data'] = $value;
+        $copy->normalize();
+
+        return $copy;
+    }
+
     /**
      * Convert a validation key to a JSON pointer.
      *
@@ -688,33 +740,4 @@ private function putIdentifier(string $type, ?string $id): self
         return $copy;
     }
 
-    /**
-     * @param string $field
-     * @param $value
-     * @return ResourceObject
-     */
-    private function putAttr(string $field, $value): self
-    {
-        $copy = clone $this;
-        $copy->attributes[$field] = $value;
-        $copy->normalize();
-
-        return $copy;
-    }
-
-    /**
-     * @param string $field
-     * @param array|null $value
-     * @return ResourceObject
-     */
-    private function putRelation(string $field, ?array $value): self
-    {
-        $copy = clone $this;
-        $copy->relationships[$field] = $copy->relationships[$field] ?? [];
-        $copy->relationships[$field]['data'] = $value;
-        $copy->normalize();
-
-        return $copy;
-    }
-
 }

tests/lib/Unit/Document/ResourceObjectTest.php

@@ -74,7 +74,7 @@ protected function setUp(): void
                 ],
             ],
         ];
-        
+
         $this->resource = ResourceObject::create($this->values);
     }
 
@@ -392,6 +392,62 @@ public function testReplaceToMany(): void
         $this->assertSame($expected, $actual->toArray());
     }
 
+    public function testPutAttribute(): void
+    {
+        $expected = $this->values;
+        $expected['attributes']['foobar'] = 'My first post.';
+
+        $this->assertNotSame($this->resource, $actual = $this->resource->put('foobar', 'My first post.'));
+        $this->assertSame($this->values, $this->resource->toArray(), 'original resource is not modified');
+        $this->assertSame($expected, $actual->toArray());
+    }
+
+    public function testPutArrayAttribute(): void
+    {
+        $expected = $this->values;
+        $expected['attributes']['foobar'] = ['baz', 'bat'];
+
+        $this->assertNotSame($this->resource, $actual = $this->resource->put('foobar', ['baz', 'bat']));
+        $this->assertSame($this->values, $this->resource->toArray(), 'original resource is not modified');
+        $this->assertSame($expected, $actual->toArray());
+    }
+
+    public function testPutToOne(): void
+    {
+        $author = ['type' => 'users', 'id' => '999'];
+
+        $expected = $this->values;
+        $expected['relationships']['foobar']['data'] = $author;
+
+        $this->assertNotSame($this->resource, $actual = $this->resource->putRelation('foobar', $author));
+        $this->assertSame($this->values, $this->resource->toArray(), 'original resource is not modified');
+        $this->assertSame($expected, $actual->toArray());
+    }
+
+    public function testPutToOneNull(): void
+    {
+        $expected = $this->values;
+        $expected['relationships']['foobar']['data'] = null;
+
+        $this->assertNotSame($this->resource, $actual = $this->resource->putRelation('foobar', null));
+        $this->assertSame($this->values, $this->resource->toArray(), 'original resource is not modified');
+        $this->assertSame($expected, $actual->toArray());
+    }
+
+    public function testPutToMany(): void
+    {
+        $comments = [
+            ['type' => 'comments', 'id' => '123456'],
+        ];
+
+        $expected = $this->values;
+        $expected['relationships']['foobar']['data'] = $comments;
+
+        $this->assertNotSame($this->resource, $actual = $this->resource->putRelation('foobar', $comments));
+        $this->assertSame($this->values, $this->resource->toArray(), 'original resource is not modified');
+        $this->assertSame($expected, $actual->toArray());
+    }
+
     public function testWithType(): void
     {
         $expected = $this->values;