You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Better error messages for invalid types and composed properties.
Error messages for invalid properties now include the required type (a list of possible types for MultiTypeProcessor) and the actually given type.
Error messages for composed values now include how many of the composition elements must be matched and how many are matched. Additionally appends a list of all composition elements to the exception message which shows the elements which were matched and those who failed (only available if the error collection mode is enabled). Failing elements additionally include the exact reason for failing (the collected exception messages from the nested validation)
To avoid adding all dependencies of the php-json-model-generator to your production dependencies it's recommended to add the library as a dev-dependency and include the php-json-model-generator-exception library. The exception library provides all classes to run the generated code. Generating the classes should either be a step done in the development environment (if you decide to commit the models) or as a build step of your application.
37
38
38
-
## Examples ##
39
+
## Basic usage ##
39
40
40
41
The base object for generating models is the *Generator*. After you have created a Generator you can use the object to generate your model classes without any further configuration:
41
42
@@ -59,11 +60,12 @@ $generator
59
60
```
60
61
61
62
The generator will check the given source directory recursive and convert all found *.json files to models. All JSON-Schema files inside the source directory must provide a schema of an object.
63
+
62
64
## Configuring using the GeneratorConfiguration ##
63
65
64
66
The *GeneratorConfiguration* object offers the following methods to configure the generator in a fluid interface:
65
67
66
-
Method | Configuration | Example
68
+
Method | Configuration | Default
67
69
--- | --- | ---
68
70
``` setNamespacePrefix(string $prefix) ``` <br><br>Example:<br> ``` setNamespacePrefix('\MyApp\Model') ``` | Configures a namespace prefix for all generated classes. The namespaces will be extended with the directory structure of the source directory. | Empty string so no namespace prefix will be used
69
71
``` setImmutable(bool $immutable) ``` <br><br>Example:<br> ``` setImmutable(false) ``` | If set to true the generated model classes will be delivered without setter methods for the object properties. | true
@@ -73,6 +75,74 @@ Method | Configuration | Example
73
75
``` setErrorRegistryClass(string $exceptionClass) ``` <br><br>Example:<br> ``` setErrorRegistryClass(CustomException::class) ``` | Define a custom exception implementing the ErrorRegistryExceptionInterface to decouple the generated code from the library (if you want to declare the library as a dev-dependency). The exception will be thrown if a validation fails error collection is **enabled** | ErrorRegistryException::class
74
76
``` setExceptionClass(bool $prettyPrint) ``` <br><br>Example:<br> ``` setExceptionClass(CustomException::class) ``` | Define a custom exception to decouple the generated code from the library (if you want to declare the library as a dev-dependency). The exception will be thrown if a validation fails error collection is **disabled** | ValidationException::class
75
77
78
+
## Examples ##
79
+
80
+
The directory `./tests/manual` contains some easy examples which show the usage. After installing the dependencies of the library via `composer update` you can execute `php ./tests/manual/test.php` to generate the examples and play around with some JSON-Schema files to explore the library.
81
+
82
+
Let's have a look into an easy example. We create a simple model for a person with a name and an optional age. Our resulting JSON-Schema:
83
+
```json
84
+
{
85
+
"id": "Person",
86
+
"type": "object",
87
+
"properties": {
88
+
"name": {
89
+
"type": "string"
90
+
},
91
+
"age": {
92
+
"type": "integer"
93
+
}
94
+
},
95
+
"required": [
96
+
"name"
97
+
]
98
+
}
99
+
```
100
+
101
+
After generating a class with this JSON-Schema our class with the name `Person` will provide the following interface:
102
+
```php
103
+
// the constructor takes an array with data which is validated and applied to the model
104
+
public function __construct(array $modelData);
105
+
106
+
// the method getRawModelDataInput always delivers the raw input which was provided on instantiation
107
+
public function getRawModelDataInput(): array;
108
+
109
+
// getters to fetch the validated properties. Age is nullable as it's not required
110
+
public function getName(): string;
111
+
public function getAge(): ?int;
112
+
113
+
// setters to change the values of the model after instantiation (only generated if immutability is disabled)
114
+
public function setName(string $name): Person;
115
+
public function setAge(int ?$age): Person;
116
+
```
117
+
118
+
Now let's have a look at the behaviour of the generated model:
119
+
```php
120
+
// Throws an exception as the required name isn't provided.
121
+
// Exception: 'Missing required value for name'
122
+
$person = new Person();
123
+
124
+
// Throws an exception as the name provides an invalid value.
125
+
// Exception: 'Invalid type for name. Requires string, got int'
126
+
$person = new Person(['name' => 12]);
127
+
128
+
// A valid example as the age isn't required
129
+
$person = new Person(['name' => 'Albert']);
130
+
$person->getName(); // returns 'Albert'
131
+
$person->getAge(); // returns NULL
132
+
```
133
+
134
+
More complex exception messages eg. from a [allOf](https://json-schema.org/understanding-json-schema/reference/combining.html#allof) composition may look like:
135
+
```
136
+
Invalid value for Animal declined by composition constraint.
137
+
Requires to match one composition element but matched 0 elements.
138
+
- Composition element #1: Failed
139
+
* Value for age must not be smaller than 0
140
+
- Composition element #2: Valid
141
+
- Composition element #3: Failed
142
+
* Value for legs must not be smaller than 2
143
+
* Value for legs must be a multiple of 2
144
+
```
145
+
76
146
## How the heck does this work? ##
77
147
78
148
The class generation process basically splits up into three to four steps:
@@ -84,8 +154,10 @@ The class generation process basically splits up into three to four steps:
84
154
85
155
## Tests ##
86
156
157
+
The library is tested via [PHPUnit](https://phpunit.de/).
158
+
87
159
After installing the dependencies of the library via `composer update` you can execute the tests with `./vendor/bin/phpunit` (Linux) or `vendor\bin\phpunit.bat` (Windows). The test names are optimized for the usage of the `--testdox` output. Most tests are atomic integration tests which will set up a JSON-Schema file and generate a class from the schema and test the behaviour of the generated class afterwards.
88
160
89
161
During the execution the tests will create a directory PHPModelGeneratorTest in tmp where JSON-Schema files and PHP classes will be written to.
90
162
91
-
If a test which creates a PHP class from a JSON-Schema fails the JSON-Schema and the generated class(es) will be dumped to `./Failed-classes`
163
+
If a test which creates a PHP class from a JSON-Schema fails the JSON-Schema and the generated class(es) will be dumped to the directory `./Failed-classes`
0 commit comments