Merge pull request #4 from wol-soft/implicitNullableConfiguration

Implicit/Explicit null values for optional properties

Author: wol-soft

README.md

@@ -38,7 +38,8 @@ The recommended way to install php-json-schema-model-generator is through [Compo
 $ composer require --dev wol-soft/php-json-schema-model-generator
 $ composer require wol-soft/php-json-schema-model-generator-production
 ```
-To avoid adding all dependencies of the php-json-schema-model-generator to your production dependencies it's recommended to add the library as a dev-dependency and include the [wol-soft/php-json-schema-model-generator-production](https://github.com/wol-soft/php-json-schema-model-generator-production) library. The production 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.
+
+To avoid adding all dependencies of the php-json-schema-model-generator to your production dependencies it's recommended to add the library as a dev-dependency and include the [wol-soft/php-json-schema-model-generator-production](https://github.com/wol-soft/php-json-schema-model-generator-production) library. The production library provides all classes to run the generated code. Generating the classes should either be a step done in the development environment or as a build step of your application (for example you could generate the models in a [composer post-autoload-dump script](https://getcomposer.org/doc/articles/scripts.md#command-events), which is the recommended workflow).
 
 ## Basic usage ##
 
@@ -83,6 +84,7 @@ Method | Configuration | Default
 --- | --- | ---
 ``` 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
 ``` 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
+``` setImplicitNull(bool $allowImplicitNull) ``` <br><br>Example:<br> ``` setImplicitNull(true) ``` | By setting the implicit null option to true all of your object properties which aren't required will implicitly accept null. | false
 ``` 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
 ``` 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
 ``` 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

composer.json

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

docs/source/gettingStarted.rst

@@ -11,7 +11,7 @@ The recommended way to install php-json-model-generator is through `Composer <ht
     composer require --dev wol-soft/php-json-schema-model-generator
     composer require wol-soft/php-json-schema-model-generator-production
 
-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.
+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 or as a build step of your application (for example you could generate the models in a `composer post-autoload-dump script<https://getcomposer.org/doc/articles/scripts.md#command-events>`__, which is the recommended workflow).
 
 Generating classes
 ------------------
@@ -154,6 +154,22 @@ If set to true the generated model classes will be delivered without setter meth
     (new GeneratorConfiguration())
         ->setImmutable(false);
 
+Implicit null
+^^^^^^^^^^^^^
+
+By default the properties are strictly checked against their defined types. Consequently if you want a property to accept null you have to extend the type of your property explicitly (eg. ['string', 'null']).
+
+By setting the implicit null option to true all of your object properties which aren't required will implicitly accept null. All properties which are required and don't explicitly allow null in the type definition will still reject null.
+
+.. code-block:: php
+
+    setImplicitNull(bool $allowImplicitNull);
+
+.. code-block:: php
+
+    (new GeneratorConfiguration())
+        ->setImplicitNull(true);
+
 Collect errors vs. early return
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -209,7 +225,7 @@ Serialization methods
 
     setSerialization(bool $serialization);
 
-If set to true the serialization methods `toArray` and `toJSON` will be added to the public interface of the generated classes. By default no serialization methods are added.
+If set to true the serialization methods `toArray`, `toJSON` and `jsonSerialize` will be added to the public interface of the generated classes. By default no serialization methods are added.
 
 .. code-block:: php
 
@@ -222,9 +238,12 @@ Generated interface:
 
     public function toArray([int $depth = 512]): array;
     public function toJSON([int $options = 0 [, int $depth = 512]]): string;
+    public function jsonSerialize(): array;
 
 The generated class will implement the interface **PHPModelGenerator\\Interfaces\\SerializationInterface** implemented in the php-json-schema-model-generator-production repository. This interface can be used to write additional generic modules to handle the generated models. The $depth parameter defines the maximum amount of nested objects which are serialized. The $options parameter for the toJSON method provides access to the underlying option bitmask of `json_encode <https://www.php.net/manual/de/function.json-encode.php>`_.
 
+Additionally the class will implement the PHP builtin interface **\JsonSerializable** which allows the direct usage of the generated classes in a custom json_encode.
+
 Output generation process
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/source/nonStandardExtensions/filter.rst

@@ -80,7 +80,7 @@ Transforming filter
 
     You may keep it simple and skip this for your first tries and only experiment with non-transforming filters like the trim filter
 
-Filters may change the type of the property. For example the builtin filter **dateTime** creates a DateTime object. Consequently further validations like pattern checks for the string property won't be performed.
+Filters may change the type of the property. For example the builtin filter **dateTime** creates a DateTime object. Consequently further type-related validations like pattern checks for the string property won't be performed. Additionally enum validations will not be executed if an already transformed value is provided.
 
 As the required check is executed before the filter a filter may transform a required value into a null value. Be aware when writing custom filters which transform values to not break your validation rules by adding filters to a property.
 
@@ -90,13 +90,15 @@ If you write a custom transforming filter you must define the return type of you
 
 The return type of the transforming filter will be used to define the type of the property inside the generated model (in the example one section above given above the method **getCreated** will return a DateTime object). Additionally the generated model also accepts the transformed type as input type. So **setCreated** will accept a string and a DateTime object. If an already transformed value is provided the filter which transforms the value will **not** be executed. Also all filters which are defined before the transformation will **not** be executed (eg. a trim filter before a dateTime filter will not be executed if a DateTime object is provided).
 
+If you use a filter on a property which accepts multiple types (eg. explicit null ['string', 'null'] or ['string', 'integer']) the filter must accept each of the types defined on the property.
+
 Builtin filter
 --------------
 
 trim
 ^^^^
 
-The trim filter is only valid for string properties.
+The trim filter is only valid for string and null properties.
 
 .. code-block:: json
 
@@ -140,7 +142,7 @@ If the filter trim is used for a property which doesn't require a string value a
 notEmpty
 ^^^^^^^^
 
-The dateTime filter is only valid for array properties.
+The dateTime filter is only valid for array and null properties.
 
 .. code-block:: json
 
@@ -174,7 +176,7 @@ Let's have a look how the generated model behaves:
 dateTime
 ^^^^^^^^
 
-The dateTime filter is only valid for string properties.
+The dateTime filter is only valid for string and null properties.
 
 .. code-block:: json
 
@@ -274,9 +276,9 @@ The callable filter method must be a static method. Internally it will be called
         public function getAcceptedTypes(): array
         {
             // return an array of types which can be handled by the filter.
-            // valid types are: [integer, number, boolean, string, array] or available classes (FQCN required, eg.
-            // DateTime::class)
-            return ['string'];
+            // valid types are: [integer, number, boolean, string, array, null]
+            // or available classes (FQCN required, eg. DateTime::class)
+            return ['string', 'null'];
         }
 
         public function getToken(): string
@@ -290,6 +292,10 @@ The callable filter method must be a static method. Internally it will be called
         }
     }
 
+.. hint::
+
+    If your filter accepts null values add 'null' to your *getAcceptedTypes* to make sure your filter is compatible with explicit null type.
+
 .. hint::
 
     If a filter with the token of your custom filter already exists the existing filter will be overwritten when adding the filter to the generator configuration. By overwriting filters you may change the behaviour of builtin filters by replacing them with your custom implementation.
@@ -387,12 +393,12 @@ The custom serializer method will be called if the model utilizing the custom fi
 
         public function getAcceptedTypes(): array
         {
-            return ['object'];
+            return ['string', 'null'];
         }
 
         public function getToken(): string
         {
-            return 'uppercase';
+            return 'customer';
         }
 
         public function getFilter(): array

docs/source/types/null.rst

@@ -25,3 +25,5 @@ Generated interface (as null is no explicit type no typehints are generated):
 Possible exceptions:
 
 * Invalid type for property. Requires null, got __TYPE__
+
+The main use case for the **null** type is a property with `multiple types <complexTypes/multiType.html>`__ accepting for example a string and null values when using explicit null types.

src/Model/GeneratorConfiguration.php

@@ -27,6 +27,8 @@ class GeneratorConfiguration
     /** @var bool */
     protected $immutable = false;
     /** @var bool */
+    protected $allowImplicitNull = false;
+    /** @var bool */
     protected $prettyPrint = false;
     /** @var bool */
     protected $outputEnabled = true;
@@ -86,7 +88,7 @@ public function addFilter(FilterInterface $filter): self
         }
 
         foreach ($filter->getAcceptedTypes() as $acceptedType) {
-            if (!in_array($acceptedType, ['integer', 'number', 'boolean', 'string', 'array']) &&
+            if (!in_array($acceptedType, ['integer', 'number', 'boolean', 'string', 'array', 'null']) &&
                 !class_exists($acceptedType)
             ) {
                 throw new InvalidFilterException('Filter accepts invalid types');
@@ -285,4 +287,24 @@ public function setExceptionClass(string $exceptionClass): self
 
         return $this;
     }
+
+    /**
+     * @return bool
+     */
+    public function isImplicitNullAllowed(): bool
+    {
+        return $this->allowImplicitNull;
+    }
+
+    /**
+     * @param bool $allowImplicitNull
+     *
+     * @return GeneratorConfiguration
+     */
+    public function setImplicitNull(bool $allowImplicitNull): self
+    {
+        $this->allowImplicitNull = $allowImplicitNull;
+
+        return $this;
+    }
 }

src/Model/Validator/EnumValidator.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\Model\Validator;
+
+use PHPModelGenerator\Model\Property\PropertyInterface;
+
+/**
+ * Class EnumValidator
+ *
+ * @package PHPModelGenerator\Model\Validator
+ */
+class EnumValidator extends PropertyValidator
+{
+    /**
+     * EnumValidator constructor.
+     *
+     * @param PropertyInterface $property
+     * @param array $allowedValues
+     */
+    public function __construct(PropertyInterface $property, array $allowedValues)
+    {
+
+        parent::__construct(
+            '!in_array($value, ' .
+                preg_replace('(\d+\s=>)', '', var_export($allowedValues, true)) .
+            ', true)',
+            "Invalid value for {$property->getName()} declined by enum constraint"
+        );
+    }
+}

src/Model/Validator/FilterValidator.php

@@ -56,11 +56,7 @@ public function __construct(
                 'typeCheck' => !empty($filter->getAcceptedTypes())
                     ? '($value !== null && (' .
                         implode(' && ', array_map(function (string $type) use ($property): string {
-                            return (new ReflectionTypeCheckValidator(
-                                in_array($type, ['int', 'float', 'string', 'bool', 'array', 'object']),
-                                $type,
-                                $property
-                            ))->getCheck();
+                            return ReflectionTypeCheckValidator::fromType($type, $property)->getCheck();
                         }, $this->mapDataTypes($filter->getAcceptedTypes()))) .
                         '))'
                     : '',
@@ -179,9 +175,7 @@ private function mapDataTypes(array $acceptedTypes): array
             switch ($jsonSchemaType) {
                 case 'integer': return 'int';
                 case 'number': return 'float';
-                case 'string': return 'string';
                 case 'boolean': return 'bool';
-                case 'array': return 'array';
 
                 default: return $jsonSchemaType;
             }

src/Model/Validator/MultiTypeCheckValidator.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\Model\Validator;
+
+use PHPModelGenerator\Model\Property\PropertyInterface;
+
+/**
+ * Class MultiTypeCheckValidator
+ *
+ * @package PHPModelGenerator\Model\Validator
+ */
+class MultiTypeCheckValidator extends PropertyValidator implements TypeCheckInterface
+{
+    /** @var string[] */
+    protected $types;
+
+    /**
+     * MultiTypeCheckValidator constructor.
+     *
+     * @param string[]          $types
+     * @param PropertyInterface $property
+     * @param bool              $allowImplicitNull
+     */
+    public function __construct(array $types, PropertyInterface $property, bool $allowImplicitNull)
+    {
+        $this->types = $types;
+
+        // if null is explicitly allowed we don't need an implicit null pass through
+        if (in_array('null', $types)) {
+            $allowImplicitNull = false;
+        }
+
+        parent::__construct(
+            join(
+                ' && ',
+                array_map(
+                    function (string $allowedType) use ($property) : string {
+                        return ReflectionTypeCheckValidator::fromType($allowedType, $property)->getCheck();
+                    },
+                    $types
+                )
+            ) . ($allowImplicitNull ? ' && $value !== null' : ''),
+            sprintf(
+                'Invalid type for %s. Requires [%s], got " . gettype($value) . "',
+                $property->getName(),
+                implode(', ', $types)
+            )
+
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getTypes(): array
+    {
+        return $this->types;
+    }
+}

src/Model/Validator/PassThroughTypeCheckValidator.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\Model\Validator;
+
+use PHPModelGenerator\Model\Property\PropertyInterface;
+use ReflectionType;
+
+/**
+ * Class PassThroughTypeCheckValidator
+ *
+ * @package PHPModelGenerator\Model\Validator
+ */
+class PassThroughTypeCheckValidator extends PropertyValidator implements TypeCheckInterface
+{
+    /** @var string[] */
+    protected $types;
+
+    /**
+     * PassThroughTypeCheckValidator constructor.
+     *
+     * @param ReflectionType $passThroughType
+     * @param PropertyInterface $property
+     * @param TypeCheckValidator $typeCheckValidator
+     */
+    public function __construct(
+        ReflectionType $passThroughType,
+        PropertyInterface $property,
+        TypeCheckValidator $typeCheckValidator
+    ) {
+        $this->types = array_merge($typeCheckValidator->getTypes(), [$passThroughType->getName()]);
+
+        parent::__construct(
+            sprintf(
+                '%s && %s',
+                ReflectionTypeCheckValidator::fromReflectionType($passThroughType, $property)->getCheck(),
+                $typeCheckValidator->getCheck()
+            ),
+            sprintf(
+                'Invalid type for %s. Requires [%s, %s], got " . gettype($value) . "',
+                $property->getName(),
+                $passThroughType->getName(),
+                $property->getType()
+            )
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getTypes(): array
+    {
+        return $this->types;
+    }
+}