Add documentation for composed schemas

wol-soft · wol-soft · commit 4efc08db2fe9 · 2020-02-17T14:41:26.000+01:00
diff --git a/.travis.yml b/.travis.yml
@@ -9,7 +9,7 @@ env:
 php:
   - 7.2
   - 7.3
-  - 7.4snapshot
+  - 7.4
 
 install:
   # Install coveralls.phar
diff --git a/composer.json b/composer.json
@@ -19,7 +19,7 @@
         "ext-mbstring": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^8.4"
+        "phpunit/phpunit": "^9.0"
     },
     "autoload": {
         "psr-4": {
diff --git a/docs/source/combinedSchemas/allOf.rst b/docs/source/combinedSchemas/allOf.rst
@@ -0,0 +1,60 @@
+All Of
+======
+
+The `allOf` keyword can be used to combine multiple subschemas. The provided value must be valid against each of the subschemas.
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "properties": {
+            "example": {
+                "allOf": [
+                    {
+                        "type": "number",
+                        "multipleOf": 5
+                    },
+                    {
+                        "type": "number",
+                        "multipleOf": 3
+                    }
+                ]
+            }
+        }
+    }
+
+Valid values are eg. 15, 30, 45. Invalid values are eg. 1, 2, 3, 4, 5 or any non numeric values.
+
+Generated interface:
+
+.. code-block:: php
+
+    public function setExample(float $example): self;
+    public function getExample(): float;
+
+
+Possible exception (if a string is provided):
+
+.. code-block:: none
+
+    Invalid value for example declined by composition constraint.
+      Requires to match 2 composition elements but matched 0 elements.
+      - Composition element #1: Failed
+        * Invalid type for example. Requires float, got string
+      - Composition element #2: Failed
+        * Invalid type for example. Requires float, got string
+
+Possible exception (if eg. 5 is provided, which matches only one subschema):
+
+.. code-block:: none
+
+    Invalid value for example declined by composition constraint.
+      Requires to match one composition element but matched 2 elements.
+      - Composition element #1: Valid
+      - Composition element #2: Failed
+        * Value for example must be a multiple of 3
+
+.. hint::
+
+    When combining multiple nested objects with an `allOf` composition a `merged property <mergedProperty.html>`__ will be generated
diff --git a/docs/source/combinedSchemas/anyOf.rst b/docs/source/combinedSchemas/anyOf.rst
@@ -0,0 +1,50 @@
+Any Of
+======
+
+The `anyOf` keyword can be used to combine multiple subschemas. The provided value must be valid against at least one of the subschemas.
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "properties": {
+            "example": {
+                "anyOf": [
+                    {
+                        "type": "number",
+                        "multipleOf": 5
+                    },
+                    {
+                        "type": "number",
+                        "multipleOf": 3
+                    }
+                ]
+            }
+        }
+    }
+
+Valid values are eg. 3, 5, 6, 9, 10, 12, 15. Invalid values are eg. 1, 2, 4, 7, 8, 11 or any non numeric values.
+
+Generated interface:
+
+.. code-block:: php
+
+    public function setExample(float $example): self;
+    public function getExample(): float;
+
+
+Possible exception (if a string is provided):
+
+.. code-block:: none
+
+    Invalid value for example declined by composition constraint.
+      Requires to match at least one composition element.
+      - Composition element #1: Failed
+        * Invalid type for example. Requires float, got string
+      - Composition element #2: Failed
+        * Invalid type for example. Requires float, got string
+
+.. hint::
+
+    When combining multiple nested objects with an `anyOf` composition a `merged property <mergedProperty.html>`__ will be generated
diff --git a/docs/source/combinedSchemas/if.rst b/docs/source/combinedSchemas/if.rst
@@ -0,0 +1,4 @@
+If
+==
+
+Currently not fully supported
diff --git a/docs/source/combinedSchemas/mergedProperty.rst b/docs/source/combinedSchemas/mergedProperty.rst
@@ -0,0 +1,60 @@
+Merged Property
+===============
+
+If multiple subschemas are combined with `oneOf`, `anyOf` or `allOf` and the subschemas contain multiple nested objects all properties of the nested objects will be merged together in a single object.
+For example we combine two objects with `allOf`:
+
+.. code-block:: json
+
+    {
+        "$id": "company",
+        "type": "object",
+        "properties": {
+            "ceo": {
+                "$id": "CEO",
+                "allOf": [
+                    {
+                        "type": "object",
+                        "properties": {
+                            "name": {
+                                "type": "string"
+                            }
+                        }
+                    },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "age": {
+                                "type": "integer"
+                            }
+                        }
+                    }
+                ]
+            }
+        }
+    }
+
+This schema will generate four classes. The main class will be `Company`, two classes to validate the subschemas combined with the `allOf` independent and one merged class containing all properties of the CEO (name and age in this example).
+As the subschemas don't contain IDs they will be named with uniqIds (compare the `naming of classes <../complexTypes/object.html#naming>`__):
+
+* Company.php
+* Company_Ceo5e4a82e39edc3.php
+* Company_Ceo5e4a82e39fe37.php
+* Company_Merged_CEO.php
+
+If the allOf doesn't contain an $id field the merged class will also contain an uniqId. So if you want to use the class with a reproducible class name you must set the $id field.
+The classes Company_Ceo5e4a82e39edc3 and Company_Ceo5e4a82e39fe37 are only used for internal validation and can't be accessed via the generated interface of Company.
+
+Generated interface:
+
+.. code-block:: php
+
+    # class Company
+    public function setCeo(?Company_Merged_CEO $example): self;
+    public function getCeo(): ?Company_Merged_CEO;
+
+    # class Company_Merged_CEO
+    public function getName(): ?string
+    public function setName(?string $name): self
+    public function getAge(): ?int
+    public function setAge(?int $name): self
diff --git a/docs/source/combinedSchemas/not.rst b/docs/source/combinedSchemas/not.rst
@@ -0,0 +1,34 @@
+Not
+===
+
+Used to validate a provided schema or property doesn't match the given schema. In our example object the value for the property example may contain anything except a boolean value to be valid.
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "properties": {
+            "example": {
+                "not": {
+                    "type": "boolean"
+                }
+            }
+        }
+    }
+
+Generated interface:
+
+.. code-block:: php
+
+    public function setExample($example): self;
+    public function getExample();
+
+
+Possible exceptions:
+
+.. code-block:: none
+
+    Invalid value for property declined by composition constraint.
+      Requires to match none composition element but matched 1 elements.
+      - Composition element #1: Valid
diff --git a/docs/source/combinedSchemas/oneOf.rst b/docs/source/combinedSchemas/oneOf.rst
@@ -0,0 +1,60 @@
+One Of
+======
+
+The `oneOf` keyword can be used to combine multiple subschemas. The provided value must be valid against exactly one of the subschemas.
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "properties": {
+            "example": {
+                "oneOf": [
+                    {
+                        "type": "number",
+                        "multipleOf": 5
+                    },
+                    {
+                        "type": "number",
+                        "multipleOf": 3
+                    }
+                ]
+            }
+        }
+    }
+
+Valid values are eg. 3, 5, 6, 9, 10, 12. Invalid values are eg. 1, 2, 4, 7, 8, 11 or any non numeric values.
+
+Generated interface:
+
+.. code-block:: php
+
+    public function setExample(float $example): self;
+    public function getExample(): float;
+
+
+Possible exception (if a string is provided):
+
+.. code-block:: none
+
+    Invalid value for example declined by composition constraint.
+      Requires to match one composition element but matched 0 elements.
+      - Composition element #1: Failed
+        * Invalid type for example. Requires float, got string
+      - Composition element #2: Failed
+        * Invalid type for example. Requires float, got string
+
+
+Possible exception (if eg. 15 is provided, which matches both subschemas):
+
+.. code-block:: none
+
+    Invalid value for example declined by composition constraint.
+      Requires to match one composition element but matched 2 elements.
+      - Composition element #1: Valid
+      - Composition element #2: Valid
+
+.. hint::
+
+    When combining multiple nested objects with an `oneOf` composition a `merged property <mergedProperty.html>`__ will be generated
diff --git a/docs/source/generic/references.rst b/docs/source/generic/references.rst
@@ -1,7 +1,3 @@
-.. |br| raw:: html
-
-    <br>
-
 References
 ==========
 
@@ -10,7 +6,7 @@ References can be used to re-use parts/objects of JSON-Schema definitions.
 Supported reference types
 -------------------------
 
-* internal (in a single file) reference by id (example: `"$ref": "IdOfMyObject"`)
+* internal (in a single file) reference by id (example: `"$ref": "#IdOfMyObject"`)
 * internal (in a single file) reference by path (example: `"$ref": "#/definitions/myObject"`)
 * relative reference based on the location on the file system to a complete file (example: `"$ref": "./../modules/myObject.json"`)
 * relative reference based on the location on the file system to an object by id (example: `"$ref": "./../modules/myObject.json#IdOfMyObject"`)
@@ -29,7 +25,7 @@ An example for properties referring to a definition inside the same schema:
     {
         "definitions": {
             "person": {
-                "$id": "person",
+                "$id": "#person",
                 "type": "object",
                 "properties": {
                     "name": {
@@ -42,7 +38,7 @@ An example for properties referring to a definition inside the same schema:
         "type": "object",
         "properties": {
             "leader": {
-                "$ref": "#/definitions/person"
+                "$ref": "#person"
             }
             "members": {
                 "type": "array",
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,3 +11,4 @@ Generates PHP model classes from JSON-Schema files including validation and prov
 .. include:: toc-generic.rst
 .. include:: toc-types.rst
 .. include:: toc-complexTypes.rst
+.. include:: toc-combinedSchemas.rst
diff --git a/docs/source/toc-combinedSchemas.rst b/docs/source/toc-combinedSchemas.rst
@@ -0,0 +1,10 @@
+.. toctree::
+    :caption: Combined Schemas
+    :maxdepth: 1
+
+    combinedSchemas/allOf
+    combinedSchemas/anyOf
+    combinedSchemas/oneOf
+    combinedSchemas/not
+    combinedSchemas/if
+    combinedSchemas/mergedProperty
diff --git a/src/Model/Schema.php b/src/Model/Schema.php
@@ -4,10 +4,8 @@
 
 namespace PHPModelGenerator\Model;
 
-use PHPModelGenerator\Model\Property\Property;
 use PHPModelGenerator\Model\Property\PropertyInterface;
 use PHPModelGenerator\Model\SchemaDefinition\SchemaDefinitionDictionary;
-use PHPModelGenerator\Model\Validator\PropertyValidator;
 use PHPModelGenerator\Model\Validator\PropertyValidatorInterface;
 use PHPModelGenerator\PropertyProcessor\Decorator\SchemaNamespaceTransferDecorator;
 
@@ -22,10 +20,10 @@ class Schema
     protected $className;
     /** @var string */
     protected $classPath;
-    /** @var Property[] The properties which are part of the class */
+    /** @var PropertyInterface[] The properties which are part of the class */
     protected $properties = [];
-    /** @var PropertyValidator[] A Collection of validators which must be applied
-     *                           before adding properties to the model
+    /** @var PropertyValidatorInterface[] A Collection of validators which must be applied
+     *                                    before adding properties to the model
      */
     protected $baseValidators = [];
     /** @var array */
@@ -89,7 +87,7 @@ public function addProperty(PropertyInterface $property): self
     }
 
     /**
-     * @return PropertyValidator[]
+     * @return PropertyValidatorInterface[]
      */
     public function getBaseValidators(): array
     {
diff --git a/src/Model/SchemaDefinition/SchemaDefinitionDictionary.php b/src/Model/SchemaDefinition/SchemaDefinitionDictionary.php
@@ -168,13 +168,13 @@ protected function parseExternalFile(
 
         $jsonSchema = file_get_contents($jsonSchemaFilePath);
 
-        if (!$jsonSchema || !($jsonSchema = json_decode($jsonSchema, true))) {
+        if (!$jsonSchema || !($decodedJsonSchema = json_decode($jsonSchema, true))) {
             throw new SchemaException("Invalid JSON-Schema file $jsonSchemaFilePath");
         }
 
         // set up a dummy schema to fetch the definitions from the external file
         $schema = new Schema('ExternalSchema_' . uniqid(), '', new self(dirname($jsonSchemaFilePath)));
-        $schema->getSchemaDictionary()->setUpDefinitionDictionary($jsonSchema, $schemaProcessor, $schema);
+        $schema->getSchemaDictionary()->setUpDefinitionDictionary($decodedJsonSchema, $schemaProcessor, $schema);
         $this->parsedExternalFileSchemas[$jsonSchemaFile] = $schema;
 
         return $schema->getSchemaDictionary()->getDefinition($externalKey, $schemaProcessor, $path);
diff --git a/src/PropertyProcessor/ComposedValue/AbstractComposedValueProcessor.php b/src/PropertyProcessor/ComposedValue/AbstractComposedValueProcessor.php
diff --git a/src/PropertyProcessor/Decorator/TypeHint/CompositionTypeHintDecorator.php b/src/PropertyProcessor/Decorator/TypeHint/CompositionTypeHintDecorator.php
diff --git a/src/PropertyProcessor/Property/ObjectProcessor.php b/src/PropertyProcessor/Property/ObjectProcessor.php
diff --git a/src/SchemaProcessor/SchemaProcessor.php b/src/SchemaProcessor/SchemaProcessor.php

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +If
 +==
++
 +Currently not fully supported