improved docs (#49)

Author: f3ath

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Alexey
+Copyright (c) 2017 Alexey Karapetov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -45,8 +45,9 @@ echo json_encode($doc, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
 ```
 
 Please refer to [the tests](./test) for the full API documentation:
-* [Documents](./test/Document/DocumentTest.php)
-    * [Compound Documents](./test/Document/CompoundDocumentTest.php)
+* [Documents](./test/Document/DocumentTest.php). Creating documents with primary data, errors, and meta. 
+Adding links and API version to a document.
+    * [Compound Documents](./test/Document/CompoundDocumentTest.php). Resource linkage.
 * [Errors](./test/Document/ErrorTest.php)
 * [Resources](./test/Document/Resource/ResourceTest.php)
 * [Relationships](./test/Document/Resource/Relationship/RelationshipTest.php)

src/Document/Error.php

@@ -23,6 +23,14 @@ final class Error implements \JsonSerializable
     private $detail;
     private $source;
 
+    /**
+     * @param string $id
+     */
+    public function __construct(string $id = null)
+    {
+        $this->id = $id;
+    }
+
     public function setId(string $id)
     {
         $this->id = $id;

test/BaseTestCase.php

@@ -15,8 +15,8 @@
 
 abstract class BaseTestCase extends TestCase
 {
-    public static function assertEqualsAsJson($expected, $actual, string $message = '')
+    public static function assertEncodesTo(string $expected, $obj, string $message = '')
     {
-        self::assertEquals(json_encode($expected), json_encode($actual), $message);
+        self::assertEquals(json_encode(json_decode($expected)), json_encode($obj), $message);
     }
 }

test/Document/CompoundDocumentTest.php

@@ -40,13 +40,17 @@
  */
 class CompoundDocumentTest extends BaseTestCase
 {
+    /**
+     * In a compound document, all included resources MUST be represented as an array of resource objects
+     * in a top-level included member.
+     */
     public function testIncludedResourcesRepresentedAsArray()
     {
         $apple = new ResourceObject('apples', '1');
         $apple->setAttribute('color', 'red');
         $orange = new ResourceObject('oranges', '1');
         $orange->setAttribute('color', 'orange');
-        $basket = new ResourceObject('basket', '1');
+        $basket = new ResourceObject('baskets', '1');
         $basket->setRelationship(
             'fruits',
             Relationship::fromLinkage(
@@ -56,26 +60,48 @@ public function testIncludedResourcesRepresentedAsArray()
                 )
             )
         );
-        $doc = \JsonApiPhp\JsonApi\Document::fromResource($basket);
+        $doc = Document::fromResource($basket);
         $doc->setIncluded($apple, $orange);
-        $this->assertEquals(
-            [
-                [
-                    'type' => 'apples',
-                    'id' => '1',
-                    'attributes' => [
-                        'color' => 'red',
-                    ],
-                ],
-                [
-                    'type' => 'oranges',
-                    'id' => '1',
-                    'attributes' => [
-                        'color' => 'orange',
-                    ],
-                ],
-            ],
-            $this->convertToArray($doc)['included']
+        $this->assertEncodesTo(
+            '
+            {
+                "data": {
+                    "type": "baskets",
+                    "id": "1",
+                    "relationships": {
+                        "fruits": {
+                            "data": [
+                                {
+                                    "type": "apples",
+                                    "id": "1"
+                                },
+                                {
+                                    "type": "oranges",
+                                    "id": "1"
+                                }
+                            ]
+                        }
+                    }
+                },
+                "included": [
+                    {
+                        "type": "apples",
+                        "id": "1",
+                        "attributes": {
+                            "color": "red"
+                        }
+                    },
+                    {
+                        "type": "oranges",
+                        "id": "1",
+                        "attributes": {
+                            "color": "orange"
+                        }
+                    }
+                ]
+            }
+            ',
+            $doc
         );
     }
 
@@ -90,12 +116,28 @@ public function testFullLinkageIsRequired()
         json_encode($doc);
     }
 
+    /**
+     * A compound document must be explicitly marked as sparse. In this case full linkage is not required.
+     */
     public function testFullLinkageIsNotRequiredIfSparse()
     {
-        $doc = \JsonApiPhp\JsonApi\Document::fromResource(new NullResource);
+        $doc = Document::fromResource(new NullResource);
         $doc->markSparse();
         $doc->setIncluded(new ResourceObject('apples', '1'));
-        $this->assertCanBeBuilt($doc);
+        $this->assertEncodesTo(
+            '
+            {
+                "data": null,
+                "included": [
+                    {
+                        "type": "apples",
+                        "id": "1"
+                    }
+                ]
+            }
+            ',
+            $doc
+        );
     }
 
     public function testIncludedResourceMayBeIdentifiedByPrimaryData()
@@ -104,7 +146,7 @@ public function testIncludedResourceMayBeIdentifiedByPrimaryData()
         $apple->setAttribute('color', 'red');
         $doc = Document::fromResource($apple->toId());
         $doc->setIncluded($apple);
-        $this->assertCanBeBuilt($doc);
+        $this->assertJson(json_encode($doc));
     }
 
     public function testIncludedResourceMayBeIdentifiedByAnotherIncludedResource()
@@ -124,18 +166,8 @@ public function testIncludedResourceMayBeIdentifiedByAnotherIncludedResource()
                 )
             )
         );
-        $doc = \JsonApiPhp\JsonApi\Document::fromResource($basket->toId());
+        $doc = Document::fromResource($basket->toId());
         $doc->setIncluded($apple, $basket);
-        $this->assertCanBeBuilt($doc);
-    }
-
-    private function convertToArray($object): array
-    {
-        return json_decode(json_encode($object), true);
-    }
-
-    private function assertCanBeBuilt($doc)
-    {
-        $this->assertInternalType('string', json_encode($doc));
+        $this->assertJson(json_encode($doc));
     }
 }