Skip to content

Commit f9e1304

Browse files
Art4Art4
committed
Add docs for Serializer
1 parent 9b1258d commit f9e1304

File tree

5 files changed

+77
-83
lines changed

5 files changed

+77
-83
lines changed

‎README.md‎

Lines changed: 3 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ $ composer require art4/json-api-client
3535

3636
See the [documentation](docs/README.md).
3737

38-
### Using as reader
38+
### Using as parser
3939

4040
```php
4141
use Art4\JsonApiClient\Exception\InputException;
@@ -58,41 +58,9 @@ try {
5858
}
5959
```
6060

61-
Using `Art4\JsonApiClient\Helper\Parser::parseResponseString($jsonapiString)` is a shortcut for directly using the Manager:
61+
**Note**: Using `Art4\JsonApiClient\Helper\Parser` is just a shortcut for directly using the [Manager](docs/manager.md).
6262

63-
```php
64-
use Art4\JsonApiClient\Exception\InputException;
65-
use Art4\JsonApiClient\Exception\ValidationException;
66-
use Art4\JsonApiClient\Input\RequestStringInput;
67-
use Art4\JsonApiClient\Input\ResponseStringInput;
68-
use Art4\JsonApiClient\Manager\ErrorAbortManager;
69-
use Art4\JsonApiClient\V1\Factory;
70-
71-
// The Response body from a JSON API server
72-
$jsonapiString = '{"meta":{"info":"Testing the JsonApiClient library."}}';
73-
74-
$manager = new ErrorAbortManager(
75-
new Factory()
76-
);
77-
78-
try {
79-
// Use this if you have a response after calling a JSON API server
80-
$input = new ResponseStringInput($jsonapiString);
81-
82-
// Or use this if you have a request to your JSON API server
83-
$input = new RequestStringInput($jsonapiString);
84-
85-
$document = $manager->parse($input);
86-
} catch (InputException $e) {
87-
// $jsonapiString is not valid JSON
88-
} catch (ValidationException $e) {
89-
// $jsonapiString is not valid JSON API
90-
}
91-
92-
// do something with $document
93-
```
94-
95-
`$document` implements the `Art4\JsonApiClient\Accessable` interface to access the parsed data. It has `has($key)`, `get($key)` and `getKeys()` methods.
63+
`$document` implements the `Art4\JsonApiClient\Accessable` interface to access the parsed data. It has the methods `has($key)`, `get($key)` and `getKeys()`.
9664

9765
```php
9866
// Note that has() and get() have support for dot-notated keys

‎docs/helper-parser.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ $document = Parser::parseResponseString($jsonapiString);
2020
`$document` will be a [Document](objects-document.md) object which provided all contents.
2121

2222
> **Note:** If `$jsonapiString` contains not valid JSON a [InputException](exception-introduction.md#inputexception) will be thrown.
23+
>
2324
> **Note:** If `$jsonapiString` contains not valid JSON API a [ValidationException](exception-introduction.md#validationexception) will be thrown.
2425
>
2526
> See more about Exceptions in the [Exception section](exception-introduction.md).
@@ -43,6 +44,7 @@ $document = Parser::parseRequestString($jsonapiString);
4344
This returns a [Document](objects-document.md) object which provided all contents.
4445

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

‎docs/manager.md‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ The `Art4\JsonApiClient\Manager` needs a `Art4\JsonApiClient\Input\Input` instan
1010
Assuming you have get a response from a JSON API server. Use `parse()` to work with the data.
1111

1212
```php
13+
use Art4\JsonApiClient\Exception\InputException;
14+
use Art4\JsonApiClient\Exception\ValidationException;
1315
use Art4\JsonApiClient\Input\ResponseStringInput;
1416
use Art4\JsonApiClient\Manager\ErrorAbortManager;
1517
use Art4\JsonApiClient\V1\Factory;
@@ -19,19 +21,27 @@ $jsonapiString = '{"meta":{"info":"Testing the JsonApiClient library."}}';
1921

2022
$manager = new ErrorAbortManager(new Factory());
2123

22-
$document = $manager->parse(new ResponseStringInput($jsonapiString));
24+
try {
25+
// Use this if you have a response after calling a JSON API server
26+
$input = new ResponseStringInput($jsonapiString);
27+
28+
$document = $manager->parse($input);
29+
} catch (InputException $e) {
30+
// $jsonapiString is not valid JSON
31+
} catch (ValidationException $e) {
32+
// $jsonapiString is not valid JSON API
33+
}
2334
```
2435

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

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.
29-
3038
### Parse a JSON API string for creating a new resource
3139

3240
Assuming you have get a request for creating a new resource. In this case the `id` in the resource item can be missed and you have to tell the Manager about this case.
3341

3442
```php
43+
use Art4\JsonApiClient\Exception\InputException;
44+
use Art4\JsonApiClient\Exception\ValidationException;
3545
use Art4\JsonApiClient\Input\RequestStringInput;
3646
use Art4\JsonApiClient\Manager\ErrorAbortManager;
3747
use Art4\JsonApiClient\V1\Factory;
@@ -41,15 +51,20 @@ $jsonapiString = '{"data":{"type":"posts","attributes":{"title":"Post Title"}}}'
4151

4252
$manager = new ErrorAbortManager(new Factory());
4353

44-
// Note that here the *Request*StringInput class is used
45-
$document = $manager->parse(new RequestStringInput($jsonapiString));
54+
try {
55+
// Note that here the *Request*StringInput class is used
56+
$input = new RequestStringInput($jsonapiString);
57+
58+
$document = $manager->parse($input);
59+
} catch (InputException $e) {
60+
// $jsonapiString is not valid JSON
61+
} catch (ValidationException $e) {
62+
// $jsonapiString is not valid JSON API
63+
}
4664
```
4765

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

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.
52-
5368
### Working with a factory
5469

5570
You can set a custom [Factory](utils->factory.md) to the manager through the constructor.

‎docs/objects-introduction.md‎

Lines changed: 1 addition & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -131,45 +131,7 @@ string(28) "Testing the JsonApiClient library."
131131

132132
### Get the containing data as array
133133

134-
You can get all data as an array using a Serializer. JsonApiClient comes with an `ArraySerializer`.
135-
136-
```php
137-
use Art4\JsonApiClient\Serializer\ArraySerializer;
138-
139-
$serializer = new ArraySerializer();
140-
$array = $serializer->serialize($document);
141-
142-
var_dump($array);
143-
```
144-
145-
This returns:
146-
147-
```php
148-
array(1) {
149-
["meta"] => object(Art4\JsonApiClient\V1\Meta)#9 (2) { ... }
150-
}
151-
```
152-
153-
If you want a full array without any objects, set the `recursive` configuration into the `ArraySerializer` to parse all objects recursively into arrays.
154-
155-
```php
156-
use Art4\JsonApiClient\Serializer\ArraySerializer;
157-
158-
$serializer = new ArraySerializer(['recursive' => true]);
159-
$array = $serializer->serialize($document);
160-
161-
var_dump($array);
162-
```
163-
164-
This returns:
165-
166-
```php
167-
array(1) {
168-
["meta"] => array(1) {
169-
["info"] => string(28) "Testing the JsonApiClient library."
170-
}
171-
}
172-
```
134+
You can get all data as an array using the [ArraySerializer](serializer.md#arrayserializer).
173135

174136
### Need more?
175137

‎docs/serializer.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Serializer
2+
3+
JsonApiClient provides Serializer to convert a parsed JSON API document into other formats. Till now JsonApiClient comes only with an `ArraySerializer`.
4+
5+
## ArraySerializer
6+
7+
You can get all data as an array using the `ArraySerializer`.
8+
9+
### Get the containing data as array
10+
11+
```php
12+
use Art4\JsonApiClient\Serializer\ArraySerializer;
13+
14+
$serializer = new ArraySerializer();
15+
$array = $serializer->serialize($document);
16+
17+
var_dump($array);
18+
```
19+
20+
This returns:
21+
22+
```php
23+
array(1) {
24+
["meta"] => object(Art4\JsonApiClient\V1\Meta)#9 (2) { ... }
25+
}
26+
```
27+
28+
If you want a full array without any objects, set the `recursive` configuration into the `ArraySerializer` to parse all objects recursively into arrays.
29+
30+
```php
31+
use Art4\JsonApiClient\Serializer\ArraySerializer;
32+
33+
$serializer = new ArraySerializer(['recursive' => true]);
34+
$array = $serializer->serialize($document);
35+
36+
var_dump($array);
37+
```
38+
39+
This returns:
40+
41+
```php
42+
array(1) {
43+
["meta"] => array(1) {
44+
["info"] => string(28) "Testing the JsonApiClient library."
45+
}
46+
}
47+
```

0 commit comments

Comments
 (0)