Skip to content

Commit caa16e4

Browse files
f3athf3ath
authored
improved docs (#49)
1 parent 8b98f7d commit caa16e4

11 files changed

+346
-237
lines changed

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2017 Alexey
3+
Copyright (c) 2017 Alexey Karapetov
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,9 @@ echo json_encode($doc, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
4545
```
4646

4747
Please refer to [the tests](./test) for the full API documentation:
48-
* [Documents](./test/Document/DocumentTest.php)
49-
* [Compound Documents](./test/Document/CompoundDocumentTest.php)
48+
* [Documents](./test/Document/DocumentTest.php). Creating documents with primary data, errors, and meta.
49+
Adding links and API version to a document.
50+
* [Compound Documents](./test/Document/CompoundDocumentTest.php). Resource linkage.
5051
* [Errors](./test/Document/ErrorTest.php)
5152
* [Resources](./test/Document/Resource/ResourceTest.php)
5253
* [Relationships](./test/Document/Resource/Relationship/RelationshipTest.php)

‎src/Document/Error.php

+8
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,14 @@ final class Error implements \JsonSerializable
2323
private $detail;
2424
private $source;
2525

26+
/**
27+
* @param string $id
28+
*/
29+
public function __construct(string $id = null)
30+
{
31+
$this->id = $id;
32+
}
33+
2634
public function setId(string $id)
2735
{
2836
$this->id = $id;

‎test/BaseTestCase.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@
1515

1616
abstract class BaseTestCase extends TestCase
1717
{
18-
public static function assertEqualsAsJson($expected, $actual, string $message = '')
18+
public static function assertEncodesTo(string $expected, $obj, string $message = '')
1919
{
20-
self::assertEquals(json_encode($expected), json_encode($actual), $message);
20+
self::assertEquals(json_encode(json_decode($expected)), json_encode($obj), $message);
2121
}
2222
}

‎test/Document/CompoundDocumentTest.php

+67-35
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,17 @@
4040
*/
4141
class CompoundDocumentTest extends BaseTestCase
4242
{
43+
/**
44+
* In a compound document, all included resources MUST be represented as an array of resource objects
45+
* in a top-level included member.
46+
*/
4347
public function testIncludedResourcesRepresentedAsArray()
4448
{
4549
$apple = new ResourceObject('apples', '1');
4650
$apple->setAttribute('color', 'red');
4751
$orange = new ResourceObject('oranges', '1');
4852
$orange->setAttribute('color', 'orange');
49-
$basket = new ResourceObject('basket', '1');
53+
$basket = new ResourceObject('baskets', '1');
5054
$basket->setRelationship(
5155
'fruits',
5256
Relationship::fromLinkage(
@@ -56,26 +60,48 @@ public function testIncludedResourcesRepresentedAsArray()
5660
)
5761
)
5862
);
59-
$doc = \JsonApiPhp\JsonApi\Document::fromResource($basket);
63+
$doc = Document::fromResource($basket);
6064
$doc->setIncluded($apple, $orange);
61-
$this->assertEquals(
62-
[
63-
[
64-
'type' => 'apples',
65-
'id' => '1',
66-
'attributes' => [
67-
'color' => 'red',
68-
],
69-
],
70-
[
71-
'type' => 'oranges',
72-
'id' => '1',
73-
'attributes' => [
74-
'color' => 'orange',
75-
],
76-
],
77-
],
78-
$this->convertToArray($doc)['included']
65+
$this->assertEncodesTo(
66+
'
67+
{
68+
"data": {
69+
"type": "baskets",
70+
"id": "1",
71+
"relationships": {
72+
"fruits": {
73+
"data": [
74+
{
75+
"type": "apples",
76+
"id": "1"
77+
},
78+
{
79+
"type": "oranges",
80+
"id": "1"
81+
}
82+
]
83+
}
84+
}
85+
},
86+
"included": [
87+
{
88+
"type": "apples",
89+
"id": "1",
90+
"attributes": {
91+
"color": "red"
92+
}
93+
},
94+
{
95+
"type": "oranges",
96+
"id": "1",
97+
"attributes": {
98+
"color": "orange"
99+
}
100+
}
101+
]
102+
}
103+
',
104+
$doc
79105
);
80106
}
81107

@@ -90,12 +116,28 @@ public function testFullLinkageIsRequired()
90116
json_encode($doc);
91117
}
92118

119+
/**
120+
* A compound document must be explicitly marked as sparse. In this case full linkage is not required.
121+
*/
93122
public function testFullLinkageIsNotRequiredIfSparse()
94123
{
95-
$doc = \JsonApiPhp\JsonApi\Document::fromResource(new NullResource);
124+
$doc = Document::fromResource(new NullResource);
96125
$doc->markSparse();
97126
$doc->setIncluded(new ResourceObject('apples', '1'));
98-
$this->assertCanBeBuilt($doc);
127+
$this->assertEncodesTo(
128+
'
129+
{
130+
"data": null,
131+
"included": [
132+
{
133+
"type": "apples",
134+
"id": "1"
135+
}
136+
]
137+
}
138+
',
139+
$doc
140+
);
99141
}
100142

101143
public function testIncludedResourceMayBeIdentifiedByPrimaryData()
@@ -104,7 +146,7 @@ public function testIncludedResourceMayBeIdentifiedByPrimaryData()
104146
$apple->setAttribute('color', 'red');
105147
$doc = Document::fromResource($apple->toId());
106148
$doc->setIncluded($apple);
107-
$this->assertCanBeBuilt($doc);
149+
$this->assertJson(json_encode($doc));
108150
}
109151

110152
public function testIncludedResourceMayBeIdentifiedByAnotherIncludedResource()
@@ -124,18 +166,8 @@ public function testIncludedResourceMayBeIdentifiedByAnotherIncludedResource()
124166
)
125167
)
126168
);
127-
$doc = \JsonApiPhp\JsonApi\Document::fromResource($basket->toId());
169+
$doc = Document::fromResource($basket->toId());
128170
$doc->setIncluded($apple, $basket);
129-
$this->assertCanBeBuilt($doc);
130-
}
131-
132-
private function convertToArray($object): array
133-
{
134-
return json_decode(json_encode($object), true);
135-
}
136-
137-
private function assertCanBeBuilt($doc)
138-
{
139-
$this->assertInternalType('string', json_encode($doc));
171+
$this->assertJson(json_encode($doc));
140172
}
141173
}

0 commit comments

Comments
 (0)