Merge pull request #8 from wol-soft/ReworkExceptions

Rework exceptions

Author: wol-soft

README.md

@@ -90,7 +90,6 @@ Method | Configuration | Default
 ``` 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
 ``` setOutputEnabled(bool $outputEnabled) ``` <br><br>Example:<br> ``` setOutputEnabled(false) ``` | Enable or disable output of the generation process to STDOUT | true
 ``` 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
-``` 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
 ``` addFilter(FilterInterface $filter) ``` <br><br>Example:<br> ``` addFilter(new CustomFilter()) ``` | Add a custom filter to the generator. Check out the docs for more details. | -
 
 ## Examples ##

composer.json

@@ -12,7 +12,7 @@
     ],
     "require": {
         "symplify/easy-coding-standard": "^7.2.3",
-        "wol-soft/php-json-schema-model-generator-production": "^0.11.0",
+        "wol-soft/php-json-schema-model-generator-production": "^0.12.0",
         "wol-soft/php-micro-template": "^1.3.1",
 
         "php": ">=7.2",

docs/source/combinedSchemas/allOf.rst

@@ -34,12 +34,12 @@ Generated interface:
     public function getExample(): float;
 
 
-Possible exception (if a string is provided):
+Possible exception (eg. 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.
+      Requires to match all composition elements but matched 0 elements.
       - Composition element #1: Failed
         * Invalid type for example. Requires float, got string
       - Composition element #2: Failed
@@ -55,6 +55,19 @@ Possible exception (if eg. 5 is provided, which matches only one subschema):
       - Composition element #2: Failed
         * Value for example must be a multiple of 3
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\AllOfException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a two-dimensional array which contains all validation exceptions grouped by composition elements
+    public function getCompositionErrorCollection(): array
+    // get the amount of succeeded composition elements
+    public function getSucceededCompositionElements(): int
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 .. hint::
 
     When combining multiple nested objects with an `allOf` composition a `merged property <mergedProperty.html>`__ will be generated

docs/source/combinedSchemas/anyOf.rst

@@ -45,6 +45,19 @@ Possible exception (if a string is provided):
       - Composition element #2: Failed
         * Invalid type for example. Requires float, got string
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\AnyOfException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a two-dimensional array which contains all validation exceptions grouped by composition elements
+    public function getCompositionErrorCollection(): array
+    // get the amount of succeeded composition elements
+    public function getSucceededCompositionElements(): int
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 .. hint::
 
     When combining multiple nested objects with an `anyOf` composition a `merged property <mergedProperty.html>`__ will be generated

docs/source/combinedSchemas/not.rst

@@ -32,3 +32,16 @@ Possible exceptions:
     Invalid value for property declined by composition constraint.
       Requires to match none composition element but matched 1 elements.
       - Composition element #1: Valid
+
+The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\NotException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a two-dimensional array which contains all validation exceptions grouped by composition elements
+    public function getCompositionErrorCollection(): array
+    // get the amount of succeeded composition elements
+    public function getSucceededCompositionElements(): int
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()

docs/source/combinedSchemas/oneOf.rst

@@ -55,6 +55,19 @@ Possible exception (if eg. 15 is provided, which matches both subschemas):
       - Composition element #1: Valid
       - Composition element #2: Valid
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\OneOfException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a two-dimensional array which contains all validation exceptions grouped by composition elements
+    public function getCompositionErrorCollection(): array
+    // get the amount of succeeded composition elements
+    public function getSucceededCompositionElements(): int
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 .. hint::
 
     When combining multiple nested objects with an `oneOf` composition a `merged property <mergedProperty.html>`__ will be generated

docs/source/complexTypes/array.rst

@@ -31,6 +31,17 @@ Possible exceptions:
 
 * Invalid type for example. Requires array, got __TYPE__
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Generic\\InvalidTypeException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a string if the property expects exactly one type, an array if the property accepts multiple types
+    public function getExpectedType()
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 Items
 ^^^^^
 
@@ -56,10 +67,21 @@ With a schema like this all items must contain a string with at least two charac
 
 .. code-block:: none
 
-    Invalid item in array example:
+    Invalid items in array example:
       - invalid item #3
         * Invalid type for item of array example. Requires string, got double
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Arrays\\InvalidItemException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a two-dimensional array which contains all validation exceptions grouped by item index
+    public function getInvalidItems(): array
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 A more complex array may contain a nested object.
 
 .. code-block:: json
@@ -160,6 +182,17 @@ If invalid tuples are provided a detailed exception will be thrown containing al
       - invalid tuple #1
         * Invalid type for name. Requires string, got boolean
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Arrays\\InvalidTupleException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a two-dimensional array which contains all validation exceptions grouped by item index
+    public function getInvalidTuples()
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 .. hint::
 
     Incomplete tuples are valid. Consequently an empty array provided for the schema shown above would pass the validation. Keep this in mind when designing tuple constraints. To force the given data to provide all tuples use tuple items combined with the `minItems` array size validation.
@@ -202,6 +235,19 @@ Possible exceptions:
 
 * Tuple array example contains not allowed additional items. Expected 2 items, got 3
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Arrays\\AdditionalTupleItemsException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // Get the expected tuple amount
+    public function getExpectedAmount(): int
+    // Get the amount of items provided
+    public function getAmount(): int
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 If invalid additional items are provided a detailed exception will be thrown containing all violations:
 
 .. code-block:: none
@@ -212,6 +258,17 @@ If invalid additional items are provided a detailed exception will be thrown con
       - invalid additional item '5'
         * Invalid type for additional item. Requires object, got int
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Arrays\\InvalidAdditionalTupleItemsException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a two-dimensional array which contains all validation exceptions grouped by item index
+    public function getNestedExceptions(): array
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 Contains
 --------
 
@@ -236,6 +293,15 @@ Possible exceptions:
 
 * No item in array example matches contains constraint
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Arrays\\ContainsException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 Size validation
 ---------------
 
@@ -260,6 +326,19 @@ Possible exceptions:
 * Array example must not contain less than 2 items
 * Array example must not contain more than 5 items
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Arrays\\MaxItemsException* or a *PHPModelGenerator\\Exception\\Arrays\\MinItemsException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // for a MaxItemsException: get the maximum amount of allowed items
+    public function getMaxItems(): int
+    // for a MinItemsException: get the minimum amount of required items
+    public function getMinItems(): int
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 Uniqueness
 ----------
 
@@ -281,3 +360,12 @@ The items of an array can be forced to be unique with the `uniqueItems` keyword.
 Possible exceptions:
 
 * Items of array example are not unique
+
+The thrown exception will be an *PHPModelGenerator\\Exception\\Arrays\\UniqueItemsException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()

docs/source/complexTypes/enum.rst

@@ -55,3 +55,14 @@ Generated interface (no typehints are generated as it's an untyped enum):
 Possible exceptions:
 
 * Invalid value for example declined by enum constraint
+
+The thrown exception will be an *PHPModelGenerator\\Exception\\Generic\\EnumException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // get all values which are allowed by the enum
+    public function getAllowedValues(): array
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()

docs/source/complexTypes/multiType.rst

@@ -26,6 +26,17 @@ Possible exceptions:
 
 * Invalid type for property. Requires [float, string], got __TYPE__
 
+The thrown exception will be a *PHPModelGenerator\\Exception\\Generic\\InvalidTypeException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // returns a string if the property expects exactly one type, an array if the property accepts multiple types
+    public function getExpectedType()
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
 Additional validators
 ---------------------
 
@@ -54,6 +65,6 @@ For example if an array **["Hello", 123, "Goodbye"]** is given the validation wi
 
 .. code-block:: none
 
-    Invalid item in array example:
+    Invalid items in array example:
       - invalid item #1
         * Invalid type for item of array example. Requires string, got integer