Skip to content

Commit ec138f2

Browse files
Art4Art4
committed
Added object structure in docs
1 parent 3223ef7 commit ec138f2

File tree

5 files changed

+333
-5
lines changed

5 files changed

+333
-5
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
77

88
### Added
99

10-
- Documentation (see docs/ folder)
10+
- Documentation, see folder [docs/](docs/README.md)
1111
- Every object has got a `get()` and `has()` method for better value access
1212
- Every object can list his own keys with `keyKeys()`
1313

‎docs/README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
Navigation
22
==========
33

4-
Utils:
4+
### Utils:
55
* [Helper](utils-helper.md)
66

7-
Objects:
8-
* [Document](document.md)
7+
### Objects:
8+
* [Introduction](objects-introduction.md)
9+
* [Document](objects-document.md)

docs/document.md renamed to docs/objects-document.md

File renamed without changes.

‎docs/objects-introduction.md‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
## Objects introduction
2+
[Back to Navigation](README.md)
3+
4+
JSON API Client will parse a JSON API content into a hierarchical object stucture. **Every object has these methods for getting the values:**
5+
6+
- `has($key)`
7+
- `get($key)`
8+
- `getKeys()`
9+
10+
### Check if a value exist
11+
12+
You can check for all possible values using the `has()` method.
13+
14+
```php
15+
$jsonapi_string = '{"meta":{"info":"Testing the JSON API Client."}}';
16+
17+
$document = \Art4\JsonApiClient\Utils\Helper::parse($jsonapi_string);
18+
19+
var_dump($document->has('meta'));
20+
```
21+
22+
This returns:
23+
24+
```php
25+
true
26+
```
27+
28+
### Get the keys of all existing values
29+
30+
You can get the keys of all existing values using the `getKeys()` method. Assume we have the same `$document` like in the last example.
31+
32+
```php
33+
var_dump($document->getKeys());
34+
```
35+
36+
This returns:
37+
38+
```php
39+
array(
40+
0 => 'meta'
41+
)
42+
```
43+
44+
This can be useful to get available values:
45+
46+
```php
47+
foreach($document->getKeys() as $key)
48+
{
49+
$value = $document->get($key);
50+
}
51+
```
52+
53+
### Get the containing data
54+
55+
You can get all (existing) data using the `get()` method.
56+
57+
```php
58+
$meta = $document->get('meta');
59+
60+
// $meta contains a meta object.
61+
```
62+
63+
> **Note:** Using `get()` on a non-existing value will throw an `RuntimeException`. Use `has()` or `getKeys()` to check if a value exists.
64+
65+
## Object Structure
66+
67+
All possible objects and there hierarchical structure are listet below.
68+
69+
### Symbols
70+
71+
| Symbol | Description |
72+
| ------ | ----------- |
73+
| 1 | at least one of these properties is required |
74+
| * | zero, one or more properties |
75+
| + | required |
76+
| - | optional |
77+
| ! | not allowed |
78+
79+
### All objects
80+
81+
1. [Document object](#document-object)
82+
1. [Resource Identifier object](#resource-identifier-object)
83+
1. [Resource object](#resource-object)
84+
1. [Attributes object](#attributes-object)
85+
1. [Relationship Collection object](#relationship-collection-object)
86+
1. [Relationship object](#relationship-object)
87+
1. [Error object](#error-object)
88+
1. [Error Source object](#error-source-object)
89+
1. [Link object](#link-object)
90+
1. [Document Link object](#document-link-object)
91+
1. [Relationship Link object](#relationship-link-object)
92+
1. [Error Link object](#error-link-object)
93+
1. [Pagination Link object](#pagination-link-object)
94+
1. [Jsonapi object](#jsonapi-object)
95+
1. [Meta object](#meta-object)
96+
97+
### Document object
98+
99+
- extends:
100+
- extended by:
101+
- property of:
102+
103+
#### Properties
104+
105+
| Name | Value | Note
106+
--- | ---- | ----- | ----
107+
1 | data | - `null`<br />- [Resource Identifier object](#resource-identifier-object)<br />- [Resource object](#resource-object)<br />- array()<br />- array([Resource Identifier object](#resource-identifier-object))<br />- array([Resource object](#resource-object)) | not allowed, if 'errors' exists
108+
1 | errors | array([Error object](#error-object)) | not allowed, if 'data' exists
109+
1 | meta | [Meta object](#meta-object) |
110+
- | jsonapi | [Jsonapi object](#jsonapi-object) |
111+
- | links | [Document Link object](#document-link-object) |
112+
- | included | array([Resource object](#resource-object)) | not allowed, if 'data' doesn't exist
113+
114+
### Resource Identifier object
115+
116+
- extends:
117+
- extended by: [Resource object](#resource-object)
118+
- property of:
119+
- [Document object](#document-object)
120+
- [Relationship object](#relationship-object)
121+
122+
#### Properties
123+
124+
| Name | Value | Note
125+
--- | ---- | ----- | ----
126+
+ | type | `string` |
127+
+ | id | `string` |
128+
- | meta | [Meta object](#meta-object) |
129+
130+
### Resource object
131+
132+
- extends: [Resource Identifier object](#resource-identifier-object)
133+
- extended by:
134+
- property of: [Document object](#document-object)
135+
136+
#### Properties
137+
138+
| Name | Value | Note
139+
--- | ---- | ----- | ----
140+
- | attributes | [Attributes object](#attributes-object) |
141+
- | relationships | [Relationship Collection object](#relationship-collection-object) |
142+
- | links | [Link object](#link-object) |
143+
144+
### Attributes object
145+
146+
- extends: [Meta object](#meta-object)
147+
- extended by:
148+
- property of: [Resource object](#resource-object)
149+
150+
#### Properties
151+
152+
| Name | Value | Note
153+
--- | ---- | ----- | ----
154+
* | `string` | mixed |
155+
! | type | | already used in [Resource object](#resource-object) |
156+
! | id | | already used in [Resource object](#resource-object) |
157+
! | relationships | | reserved by spec for future use |
158+
! | links | | reserved by spec for future use |
159+
160+
### Relationship Collection object
161+
162+
- extends:
163+
- extended by:
164+
- property of: [Resource object](#resource-object)
165+
166+
#### Properties
167+
168+
| Name | Value | Note
169+
--- | ---- | ----- | ----
170+
* | `string` | [Relationship object](#relationship-object) | not allowed, if already used in parents [Attributes object](#attributes-object) property)
171+
! | type | | already used in [Resource object](#resource-object)
172+
! | id | | already used in [Resource object](#resource-object)
173+
174+
### Relationship object
175+
176+
- extends:
177+
- extended by:
178+
- property of: [Relationship Collection object](#relationship-collection-object)
179+
180+
#### Properties
181+
182+
| Name | Value | Note
183+
--- | ---- | ----- | ----
184+
1 | links | [Relationship Link object](#relationship-link-object) |
185+
1 | data | - `null`<br />- [Resource Identifier object](#resource-identifier-object)<br />- array()<br />- array([Resource Identifier object](#resource-identifier-object)) |
186+
1 | meta | [Meta object](#meta-object) |
187+
188+
### Error object
189+
190+
- extends:
191+
- extended by:
192+
- property of: [Document object](#document-object)
193+
194+
#### Properties
195+
196+
| Name | Value | Note
197+
--- | ---- | ----- | ----
198+
- | id | `string` |
199+
- | links | [Error Link object](#error-link-object) |
200+
- | status | `string` |
201+
- | code | `string` |
202+
- | title | `string` |
203+
- | detail | `string` |
204+
- | source | [Error Source object](#error-source-object) |
205+
- | meta | [Meta object](#meta-object) |
206+
207+
### Error Source object
208+
209+
- extends:
210+
- extended by:
211+
- property of: [Error object](#error-object)
212+
213+
#### Properties
214+
215+
| Name | Value | Note
216+
--- | ---- | ----- | ----
217+
- | pointer | `string` |
218+
- | parameter | `string` |
219+
220+
### Link object
221+
222+
- extends:
223+
- extended by:
224+
- [Document Link object](#document-link-object)
225+
- [Relationship Link object](#relationship-link-object)
226+
- [Error Link object](#error-link-object)
227+
- [Pagination Link object](#pagination-link-object)
228+
- property of:
229+
- [Resource object](#resource-object)
230+
- [Link object](#link-object)
231+
- [Error Link object](#error-link-object)
232+
233+
#### Properties
234+
235+
| Name | Value | Note
236+
--- | ---- | ----- | ----
237+
* | `string` | - `string`<br />- [Link object](#link-object) |
238+
- | href | `string` |
239+
- | meta | [Meta object](#meta-object) |
240+
241+
### Document Link object
242+
243+
- extends: [Link object](#link-object)
244+
- extended by:
245+
- property of: [Document object](#document-object)
246+
247+
#### Properties
248+
249+
| Name | Value | Note
250+
--- | ---- | ----- | ----
251+
- | self | `string` |
252+
- | related | `string` |
253+
- | pagination | [Pagination Link object](#pagination-link-object) |
254+
255+
### Relationship Link object
256+
257+
- extends: [Link object](#link-object)
258+
- extended by:
259+
- property of: [Relationship object](#relationship-object)
260+
261+
#### Properties
262+
263+
| Name | Value | Note
264+
--- | ---- | ----- | ----
265+
1 | self | `string` |
266+
1 | related | `string` |
267+
- | pagination | [Pagination Link object](#pagination-link-object) | Only exists if the parent relationship object represents a to-many relationship
268+
269+
### Error Link object
270+
271+
- extends: [Link object](#link-object)
272+
- extended by:
273+
- property of: [Error object](#error-object)
274+
275+
#### Properties
276+
277+
| Name | Value | Note
278+
--- | ---- | ----- | ----
279+
+ | about | - `string`<br />- [Link object](#link-object) |
280+
281+
### Pagination Link object
282+
283+
- extends: [Link object](#link-object)
284+
- extended by:
285+
- property of:
286+
- [Document Link object](#document-link-object)
287+
- [Relationship Link object](#relationship-link-object)
288+
289+
#### Properties
290+
291+
| Name | Value | Note
292+
--- | ---- | ----- | ----
293+
- | first | - `null`<br />- `string` |
294+
- | last | - `null`<br />- `string` |
295+
- | prev | - `null`<br />- `string` |
296+
- | next | - `null`<br />- `string` |
297+
298+
### Jsonapi object
299+
300+
- extends:
301+
- extended by:
302+
- property of: [Document object](#document-object)
303+
304+
#### Properties
305+
306+
| Name | Value | Note
307+
--- | ---- | ----- | ----
308+
- | version | `string` | Default: `"1.0"`
309+
- | meta | [Meta object](#meta-object) |
310+
311+
### Meta object
312+
313+
- extends:
314+
- extended by: [Attributes object](#attributes-object)
315+
- property of:
316+
- [Document object](#document-object)
317+
- [Resource Identifier object](#resource-identifier-object)
318+
- [Relationship object](#relationship-object)
319+
- [Error object](#error-object)
320+
- [Link object](#link-object)
321+
- [Jsonapi object](#jsonapi-object)
322+
323+
#### Properties
324+
325+
| Name | Value | Note
326+
--- | ---- | ----- | ----
327+
* | `string` | `mixed` |

‎docs/utils-helper.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ $jsonapi_string = '{"meta":{"info":"Testing the JSON API Client."}}';
1515
$document = \Art4\JsonApiClient\Utils\Helper::parse($jsonapi_string);
1616
```
1717

18-
This returns a [Document](document.md) object which provided all contents.
18+
This returns a [Document](objects-document.md) object which provided all contents.
1919

2020
### Validate a JSON API response body
2121

0 commit comments

Comments
 (0)