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
Generates PHP model classes from JSON-Schema files including validation and providing a fluent auto completion for the generated classes.
@@ -26,6 +27,7 @@ Simple example from a PHP application: you define and document an API with swagg
26
27
## Requirements ##
27
28
28
29
- Requires at least PHP 7.2
30
+
- Requires the PHP extensions ext-json and ext-mbstring
29
31
30
32
## Installation ##
31
33
@@ -38,6 +40,8 @@ To avoid adding all dependencies of the php-json-model-generator to your product
38
40
39
41
## Basic usage ##
40
42
43
+
Check out the [docs](https://php-json-schema-model-generator.readthedocs.io/en/latest/) for more details.
44
+
41
45
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:
``` 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
71
75
``` 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
72
76
``` setCollectErrors(bool $collectErrors) ``` <br><br>Example:<br> ``` setCollectErrors(false) ``` | By default the complete input is validated and in case of failing validations all error messages will be thrown in a single exception. If set to false the first failing validation will throw an exception. | true
73
-
``` setPrettyPrint(bool $prettyPrint) ``` <br><br>Example:<br> ``` setPrettyPrint(false) ``` | If set to false, the generated model classes won't follow coding gudelines (but the generation is faster). If enabled the package [Symplify/EasyCodingStandard](https://github.com/Symplify/EasyCodingStandard) will be used to clean up the generated code. | true
77
+
``` setPrettyPrint(bool $prettyPrint) ``` <br><br>Example:<br> ``` setPrettyPrint(true) ``` | If set to false, the generated model classes won't follow coding guidelines (but the generation is faster). If enabled the package [Symplify/EasyCodingStandard](https://github.com/Symplify/EasyCodingStandard) will be used to clean up the generated code. By default pretty printing is disabled. | false
74
78
``` setSerialization(bool $serialization) ``` <br><br>Example:<br> ``` setSerialization(true) ``` | If set to true the serialization methods `toArray` and `toJSON` will be added to the public interface of the generated classes. | false
75
-
``` setOutputEnabled(bool $prettyPrint) ``` <br><br>Example:<br> ``` setOutputEnabled(false) ``` | Enable or disable output of the generation process to STDOUT | true
76
-
``` 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
77
-
``` 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
79
+
``` setOutputEnabled(bool $outputEnabled) ``` <br><br>Example:<br> ``` setOutputEnabled(false) ``` | Enable or disable output of the generation process to STDOUT | true
80
+
``` setErrorRegistryClass(string $exceptionClass) ``` <br><br>Example:<br> ``` setErrorRegistryClass(CustomException::class) ``` | Define a custom exception implementing the ErrorRegistryExceptionInterface to be used. The exception will be thrown if a validation fails and error collection is **enabled** | ErrorRegistryException::class
81
+
``` setExceptionClass(string $exceptionClass) ``` <br><br>Example:<br> ``` setExceptionClass(CustomException::class) ``` | Define a custom exception to be used. The exception will be thrown if a validation fails and error collection is **disabled** | ValidationException::class
There are two types of arrays in JSON-Schema definitions: lists and tuples. Both types are supported by the model generator.
5
+
6
+
Lists
7
+
-----
8
+
9
+
A simple array without further restrictions can be defined using `array`.
10
+
11
+
.. code-block:: json
12
+
13
+
{
14
+
"id": "example",
15
+
"type": "object",
16
+
"properties": {
17
+
"example": {
18
+
"type": "array"
19
+
}
20
+
}
21
+
}
22
+
23
+
Generated interface:
24
+
25
+
.. code-block:: php
26
+
27
+
public function setExample(?array $example): self;
28
+
public function getExample(): ?array;
29
+
30
+
Possible exceptions:
31
+
32
+
* Invalid type for example. Requires array, got __TYPE__
33
+
34
+
Items
35
+
^^^^^
36
+
37
+
The items of a list can be restricted with a nested schema. All items of the schema must match the defined schema.
38
+
39
+
.. code-block:: json
40
+
41
+
{
42
+
"id": "example",
43
+
"type": "object",
44
+
"properties": {
45
+
"example": {
46
+
"type": "array",
47
+
"items": {
48
+
"type": "string",
49
+
"minLength": 2
50
+
}
51
+
}
52
+
}
53
+
}
54
+
55
+
With a schema like this all items must contain a string with at least two characters. Possible exceptions:
56
+
57
+
* Invalid item in array example
58
+
59
+
A more complex array may contain a nested object.
60
+
61
+
.. code-block:: json
62
+
63
+
{
64
+
"id": "example",
65
+
"type": "family",
66
+
"properties": {
67
+
"members": {
68
+
"type": "array",
69
+
"items": {
70
+
"type": "object",
71
+
"id": "member",
72
+
"properties": {
73
+
"name": {
74
+
"type": "string"
75
+
},
76
+
"age": {
77
+
"type": "integer",
78
+
"minimum": 0
79
+
}
80
+
},
81
+
"required": [
82
+
"name"
83
+
]
84
+
}
85
+
}
86
+
}
87
+
}
88
+
89
+
In this case the model generator will generate two classes: **Family** and **Member**. Generated interfaces:
90
+
91
+
.. code-block:: php
92
+
93
+
// class Family
94
+
public function setMembers(?array $members): self;
95
+
public function getMembers(): ?array;
96
+
97
+
// class Member
98
+
public function setName(string $name): self;
99
+
public function getName(): string;
100
+
101
+
public function setAge(?int $age): self;
102
+
public function getAge(): ?int;
103
+
104
+
The *getMembers* function of the class *Family* is typehinted with *@returns Member[]*. Consequently auto completion is available when developing something like:
105
+
106
+
.. code-block:: php
107
+
108
+
$family = new Family($inputArray);
109
+
110
+
foreach ($family->getMembers() as $member) {
111
+
// auto completion with available methods on $member
112
+
$member->getName();
113
+
}
114
+
115
+
Tuples
116
+
------
117
+
118
+
TODO: documentation
119
+
120
+
Contains
121
+
--------
122
+
123
+
The contains check uses a schema which must match at least one of the items provided in the input data to pass the validation. Simple checks like 'must contain a string' are possible as well as checks like 'must contain an object with a specific structure'.
124
+
125
+
.. code-block:: json
126
+
127
+
{
128
+
"id": "example",
129
+
"type": "object",
130
+
"properties": {
131
+
"example": {
132
+
"type": "array",
133
+
"contains": {
134
+
"type": "string"
135
+
}
136
+
}
137
+
}
138
+
}
139
+
140
+
Possible exceptions:
141
+
142
+
* No item in array example matches contains constraint
143
+
144
+
Size validation
145
+
---------------
146
+
147
+
To limit the size of an array use the `minItems` and `maxItems` keywords.
148
+
149
+
.. code-block:: json
150
+
151
+
{
152
+
"id": "example",
153
+
"type": "object",
154
+
"properties": {
155
+
"example": {
156
+
"type": "array",
157
+
"minItems": 2,
158
+
"maxItems": 5
159
+
}
160
+
}
161
+
}
162
+
163
+
Possible exceptions:
164
+
165
+
* Array example must not contain less than 2 items
166
+
* Array example must not contain more than 5 items
167
+
168
+
Uniqueness
169
+
----------
170
+
171
+
The items of an array can be forced to be unique with the `uniqueItems` keyword.
0 commit comments