Skip to content

Commit 9b1258d

Browse files
Art4Art4
committed
Update docs
1 parent 9c247bf commit 9b1258d

28 files changed

+145
-37
lines changed

‎README.md‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,17 @@ use Art4\JsonApiClient\Helper\Parser;
4545
// The Response body from a JSON API server
4646
$jsonapiString = '{"meta":{"info":"Testing the JsonApiClient library."}}';
4747

48-
// Use this if you have a response after calling a JSON API server
49-
$document = Parser::parseResponseString($jsonapiString);
48+
try {
49+
// Use this if you have a response after calling a JSON API server
50+
$document = Parser::parseResponseString($jsonapiString);
5051

51-
// Or use this if you have a request to your JSON API server
52-
$document = Parser::parseRequestString($jsonapiString);
52+
// Or use this if you have a request to your JSON API server
53+
$document = Parser::parseRequestString($jsonapiString);
54+
} catch (InputException $e) {
55+
// $jsonapiString is not valid JSON
56+
} catch (ValidationException $e) {
57+
// $jsonapiString is not valid JSON API
58+
}
5359
```
5460

5561
Using `Art4\JsonApiClient\Helper\Parser::parseResponseString($jsonapiString)` is a shortcut for directly using the Manager:
@@ -69,13 +75,13 @@ $manager = new ErrorAbortManager(
6975
new Factory()
7076
);
7177

72-
// Use this if you have a response after calling a JSON API server
73-
$input = new ResponseStringInput($jsonapiString);
78+
try {
79+
// Use this if you have a response after calling a JSON API server
80+
$input = new ResponseStringInput($jsonapiString);
7481

75-
// Or use this if you have a request to your JSON API server
76-
$input = new RequestStringInput($jsonapiString);
82+
// Or use this if you have a request to your JSON API server
83+
$input = new RequestStringInput($jsonapiString);
7784

78-
try {
7985
$document = $manager->parse($input);
8086
} catch (InputException $e) {
8187
// $jsonapiString is not valid JSON
@@ -113,13 +119,13 @@ use Art4\JsonApiClient\Helper\Parser;
113119
$wrong_jsonapi = '{"data":{},"meta":{"info":"This is wrong JSON API. `data` has to be `null` or containing at least `type` and `id`."}}';
114120

115121
if ( Parser::isValidResponseString($wrong_jsonapi) ) {
116-
// or use Parser::isValidRequestString($wrong_jsonapi)
122+
// or Parser::isValidRequestString($wrong_jsonapi)
117123
echo 'string is valid.';
118124
} else {
119125
echo 'string is invalid json api!';
120126
}
121127

122-
// echos 'string is invalid json api!'
128+
// echoes 'string is invalid json api!'
123129
```
124130

125131
### Extend the client

‎docs/README.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# Navigation
22

3+
### :rocket:Quickstart
4+
5+
Take a look at the [Parser](helper-parser.md) to quickstart with JsonApiClient.
6+
7+
### Helper Tools:
8+
* [Parser](helper-parser.md)
9+
* [Manager](manager.md)
10+
* [Factory](utils-factory.md)
11+
* [Exceptions](exception-introduction.md)
12+
313
### Objects:
414
* [Introduction](objects-introduction.md)
515
* [Document object](objects-document.md)
@@ -21,12 +31,6 @@
2131
* [Jsonapi object](objects-jsonapi.md)
2232
* [Meta object](objects-meta.md)
2333

24-
### Helper:
25-
* [Manager](manager.md)
26-
* [Factory](utils-factory.md)
27-
* [Parser](helper-parser.md)
28-
* [Exceptions](exception-introduction.md)
29-
3034
### Deprecated Utils:
3135
* [Manager](utils-manager.md)
3236
* [Helper](utils-helper.md)

‎docs/exception-introduction.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,31 @@ try {
1313
}
1414
```
1515

16+
## InputException
17+
18+
The `Art4\JsonApiClient\Exception\InputException` will be thrown if the input for `Art4\JsonApiClient\Input\RequestStringInput` or `Art4\JsonApiClient\Input\ResponseStringInput` is not a string or not valid JSON.
19+
20+
```php
21+
use Art4\JsonApiClient\Exception\InputException;
22+
use Art4\JsonApiClient\Input\RequestStringInput;
23+
24+
// If input is not a string
25+
try {
26+
$input = new RequestStringInput([]); // input must be a string, not array
27+
} catch (InputException $e) {
28+
echo $e->getMessage(); // "$string must be a string, "array" given."
29+
}
30+
31+
// If input is invalid JSON
32+
$input = new RequestStringInput('This is invalid JSON'); // input must be valid JSON
33+
34+
try {
35+
$object = $input->getAsObject();
36+
} catch (InputException $e) {
37+
echo $e->getMessage(); // "Unable to parse JSON data: Syntax error, malformed JSON"
38+
}
39+
```
40+
1641
## ValidationException
1742

1843
The `Art4\JsonApiClient\Exception\ValidationException` will be thrown if the response from the JSON API server doesn't follow the JSON API specification.

‎docs/helper-parser.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ The `Art4\JsonApiClient\Helper\Parser` provides some useful methods to deal with
55

66
### Parse a JSON API response body
77

8-
Assuming you have get a response from a JSON API server. Use `parseResponsestring()` to work with the data.
8+
Assuming you have get a response from a JSON API server. Use `parseResponseString()` to work with the data.
99

1010
```php
1111
use Art4\JsonApiClient\Helper\Parser;
@@ -19,7 +19,8 @@ $document = Parser::parseResponseString($jsonapiString);
1919

2020
`$document` will be a [Document](objects-document.md) object which provided all contents.
2121

22-
> **Note:** If `$jsonapiString` contains not valid JSON or JSON API a [InputException](exception-introduction.md) or [ValidationException](exception-introduction.md#exceptionvalidationexception) will be thrown.
22+
> **Note:** If `$jsonapiString` contains not valid JSON a [InputException](exception-introduction.md#inputexception) will be thrown.
23+
> **Note:** If `$jsonapiString` contains not valid JSON API a [ValidationException](exception-introduction.md#validationexception) will be thrown.
2324
>
2425
> See more about Exceptions in the [Exception section](exception-introduction.md).
2526
@@ -41,7 +42,8 @@ $document = Parser::parseRequestString($jsonapiString);
4142

4243
This returns a [Document](objects-document.md) object which provided all contents.
4344

44-
> **Note:** If `$jsonapiString` contains not valid JSON or JSON API a [InputException](exception-introduction.md) or [ValidationException](exception-introduction.md#exceptionvalidationexception) will be thrown.
45+
> **Note:** If `$jsonapiString` contains not valid JSON a [InputException](exception-introduction.md#inputexception) will be thrown.
46+
> **Note:** If `$jsonapiString` contains not valid JSON API a [ValidationException](exception-introduction.md#validationexception) will be thrown.
4547
>
4648
> See more about Exceptions in the [Exception section](exception-introduction.md).
4749

‎docs/manager.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ $document = $manager->parse(new ResponseStringInput($jsonapiString));
2424

2525
This returns a [Document](objects-document.md) object which provided all contents.
2626

27-
> **Note:** If `$jsonapiString` contains not valid JSON or JSON API a [ValidationException](exception-introduction.md#exceptionvalidationexception) will be thrown.
27+
> **Note:** If `$jsonapiString` contains not valid JSON a [InputException](exception-introduction.md#inputexception) will be thrown.
28+
> **Note:** If `$jsonapiString` contains not valid JSON API a [ValidationException](exception-introduction.md#validationexception) will be thrown.
2829
2930
### Parse a JSON API string for creating a new resource
3031

@@ -46,7 +47,8 @@ $document = $manager->parse(new RequestStringInput($jsonapiString));
4647

4748
This returns a [Document](objects-document.md) object which provided all contents.
4849

49-
> **Note:** If `$jsonapiString` contains not valid JSON or JSON API a [ValidationException](exception-introduction.md#exceptionvalidationexception) will be thrown.
50+
> **Note:** If `$jsonapiString` contains not valid JSON a [InputException](exception-introduction.md#inputexception) will be thrown.
51+
> **Note:** If `$jsonapiString` contains not valid JSON API a [ValidationException](exception-introduction.md#validationexception) will be thrown.
5052
5153
### Working with a factory
5254

‎docs/objects-attributes.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,17 @@
55

66
The `Attributes` object represents the [attributes object](http://jsonapi.org/format/#document-resource-object-attributes) of a resource object.
77

8+
This object implements the [Accessable interface](objects-introduction.md#value-access).
9+
810
Property of:
911
- [Resource Item object](objects-resource-item.md)
1012

1113
### Properties
1214

1315
_[Symbols definition](objects-introduction.md#symbols)_
1416

17+
You can use the [Accessable interface](objects-introduction.md#value-access) to access this properties.
18+
1519
| | Key | Value | Note |
1620
| --- | --- | ----- | ---- |
1721
| * | `string` | `mixed` | |

‎docs/objects-document-link.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,17 @@
55

66
The `DocumentLink` represents a [links object inside the top level document](http://jsonapi.org/format/#document-top-level).
77

8+
This object implements the [Accessable interface](objects-introduction.md#value-access).
9+
810
Property of:
911
- [Document object](objects-document.md)
1012

1113
### Properties
1214

1315
_[Symbols definition](objects-introduction.md#symbols)_
1416

17+
You can use the [Accessable interface](objects-introduction.md#value-access) to access this properties.
18+
1519
| | Key | Value | Note |
1620
| --- | --- | ----- | ---- |
1721
| ? | self | `string` |

‎docs/objects-document.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,16 @@
55

66
The `Document` object represents the [Top Level](http://jsonapi.org/format/#document-top-level) of a JSON API response. You can create it using [Helper\Parser](helper-parser.md).
77

8+
This object implements the [Accessable interface](objects-introduction.md#value-access).
9+
810
Property of: _none_
911

1012
### Properties
1113

1214
_[Symbols definition](objects-introduction.md#symbols)_
1315

16+
You can use the [Accessable interface](objects-introduction.md#value-access) to access this properties.
17+
1418
| | Key | Value | Note |
1519
| --- | --- | ----- | ---- |
1620
| # | data | - [Resource Null object](objects-resource-null.md)<br />- [Resource Identifier object](objects-resource-identifier.md)<br />- [Resource Item object](objects-resource-item.md)<br />- [Resource Collection object](objects-resource-collection.md) | not allowed, if 'errors' exists |
@@ -89,4 +93,4 @@ $links = $document->get('links');
8993
$included = $document->get('included');
9094
```
9195

92-
> **Note:** Using `get()` on a non-existing value will throw an [AccessException](exception-introduction.md#exceptionaccessexception). Use `has()` or `getKeys()` to check if a value exists.
96+
> **Note:** Using `get()` on a non-existing value will throw an [AccessException](exception-introduction.md#accessexception). Use `has()` or `getKeys()` to check if a value exists.

‎docs/objects-error-collection.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,17 @@
55

66
The `ErrorCollection` represents [an array of error objects](http://jsonapi.org/format/#error-objects).
77

8+
This object implements the [Accessable interface](objects-introduction.md#value-access).
9+
810
Property of:
911
- [Document object](objects-document.md)
1012

1113
### Properties
1214

1315
_[Symbols definition](objects-introduction.md#symbols)_
1416

17+
You can use the [Accessable interface](objects-introduction.md#value-access) to access this properties.
18+
1519
| | Key | Value | Note |
1620
| --- | --- | ----- | ---- |
1721
| + | `integer` | [Error object](objects-error.md) | |

‎docs/objects-error-link.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,17 @@
55

66
The `ErrorLink` represents a [links object inside an error object](http://jsonapi.org/format/#error-objects).
77

8+
This object implements the [Accessable interface](objects-introduction.md#value-access).
9+
810
Property of:
911
- [Error object](objects-error.md)
1012

1113
### Properties
1214

1315
_[Symbols definition](objects-introduction.md#symbols)_
1416

17+
You can use the [Accessable interface](objects-introduction.md#value-access) to access this properties.
18+
1519
| | Key | Value | Note |
1620
| --- | --- | ----- | ---- |
1721
| 1 | about | - `string`<br />- [Link object](objects-link.md) | |

0 commit comments

Comments
 (0)