Models implement the JsonSerializable interface

Added implicit/explixit null test cases

Author: wol-soft

README.md

@@ -39,7 +39,7 @@ $ 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 or as a build step of your application (for example you could generate the models in a [composer post-update-cmd script](https://getcomposer.org/doc/articles/scripts.md#command-events), which is the recommended workflow).
+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 ##
 

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 or as a build step of your application (for example you could generate the models in a `composer post-update-cmd script<https://getcomposer.org/doc/articles/scripts.md#command-events>`__, which is the recommended workflow).
+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
 ------------------
@@ -225,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
 
@@ -238,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

@@ -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
 
@@ -292,7 +294,7 @@ 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
+    If your filter accepts null values add 'null' to your *getAcceptedTypes* to make sure your filter is compatible with explicit null type.
 
 .. hint::
 

src/Templates/Model.phptpl

@@ -17,7 +17,7 @@ declare(strict_types = 1);
 {% if namespace %} * @package {{ namespace }} {% endif %}
  */
 class {{ class }} implements \PHPModelGenerator\Interfaces\JSONModelInterface
-{% if generatorConfiguration.hasSerializationEnabled() %}, \PHPModelGenerator\Interfaces\SerializationInterface{% endif %}
+{% if generatorConfiguration.hasSerializationEnabled() %}, \PHPModelGenerator\Interfaces\SerializationInterface, \JsonSerializable{% endif %}
 {
     {% if generatorConfiguration.hasSerializationEnabled() %}use \PHPModelGenerator\Traits\SerializableTrait;{% endif %}
 

tests/AbstractPHPModelGeneratorTest.php

@@ -105,10 +105,11 @@ private function copyExternalJSON(): void
     /**
      * Generate a class from a given JSON schema file and return the FQCN
      *
-     * @param string                      $file
+     * @param string $file
      * @param GeneratorConfiguration|null $generatorConfiguration
-     * @param bool                        $originalClassNames
-     * @param string                      $schemaProviderClass
+     * @param bool $originalClassNames
+     * @param bool $implicitNull
+     * @param string $schemaProviderClass
      *
      * @return string
      *
@@ -120,12 +121,14 @@ protected function generateClassFromFile(
         string $file,
         GeneratorConfiguration $generatorConfiguration = null,
         bool $originalClassNames = false,
+        bool $implicitNull = true,
         string $schemaProviderClass = RecursiveDirectoryProvider::class
     ): string {
         return $this->generateClass(
             file_get_contents(__DIR__ . '/Schema/' . $this->getStaticClassName() . '/' . $file),
             $generatorConfiguration,
             $originalClassNames,
+            $implicitNull,
             $schemaProviderClass
         );
     }
@@ -170,14 +173,14 @@ function ($item) use ($escape) {
     /**
      * Generate a class from a given JSON schema string and return the FQCN
      *
-     * @param string                      $jsonSchema
+     * @param string $jsonSchema
      * @param GeneratorConfiguration|null $generatorConfiguration
-     * @param bool                        $originalClassNames
-     * @param string                      $schemaProviderClass
+     * @param bool $originalClassNames
+     * @param bool $implicitNull
+     * @param string $schemaProviderClass
      *
      * @return string
      *
-     * @throws Exception
      * @throws FileSystemException
      * @throws RenderException
      * @throws SchemaException
@@ -186,11 +189,12 @@ protected function generateClass(
         string $jsonSchema,
         GeneratorConfiguration $generatorConfiguration = null,
         bool $originalClassNames = false,
+        bool $implicitNull = true,
         string $schemaProviderClass = RecursiveDirectoryProvider::class
     ): string {
         $generatorConfiguration = ($generatorConfiguration ?? (new GeneratorConfiguration())->setCollectErrors(false))
             ->setPrettyPrint(false)
-            ->setImplicitNull(true)
+            ->setImplicitNull($implicitNull)
             ->setOutputEnabled(false);
 
         if (!$originalClassNames) {
@@ -365,6 +369,14 @@ public function validationMethodDataProvider(): array {
         ];
     }
 
+    public function implicitNullDataProvider(): array
+    {
+        return [
+            'implicit null enabled' => [true],
+            'implicit null disabled' => [false],
+        ];
+    }
+
     /**
      * Get the annotated type for an object property
      *

tests/Basic/BasicSchemaGenerationTest.php

@@ -2,6 +2,7 @@
 
 namespace PHPModelGenerator\Tests\Basic;
 
+use JsonSerializable;
 use PHPModelGenerator\Exception\FileSystemException;
 use PHPModelGenerator\Exception\SchemaException;
 use PHPModelGenerator\Interfaces\JSONModelInterface;
@@ -107,10 +108,12 @@ public function testSerializationFunctionsAreGeneratedWithEnabledSerialization()
         $object = new $className(['property' => 'Hello']);
 
         $this->assertEquals(['property' => 'Hello'], $object->toArray());
+        $this->assertEquals(['property' => 'Hello'], $object->jsonSerialize());
         $this->assertEquals('{"property":"Hello"}', $object->toJSON());
 
         $this->assertTrue($object instanceof SerializationInterface);
         $this->assertTrue($object instanceof JSONModelInterface);
+        $this->assertTrue($object instanceof JsonSerializable);
     }
 
     public function testNestedSerializationFunctions(): void
@@ -131,6 +134,7 @@ public function testNestedSerializationFunctions(): void
         $object = new $className($input);
 
         $this->assertEquals($input, $object->toArray());
+        $this->assertEquals($input, $object->jsonSerialize());
         $this->assertEquals('{"name":"Hannes","address":{"street":"Test-Street","number":null}}', $object->toJSON());
 
         $this->assertEquals(['name' => 'Hannes', 'address' => null], $object->toArray(1));

tests/Basic/ExplicitNullTest.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace PHPModelGenerator\Tests\Basic;
+
+use PHPModelGenerator\Exception\ValidationException;
+use PHPModelGenerator\Tests\AbstractPHPModelGeneratorTest;
+
+/**
+ * Class ExplicitNullTest
+ *
+ * @package PHPModelGenerator\Tests\Basic
+ */
+class ExplicitNullTest extends AbstractPHPModelGeneratorTest
+{
+    public function testNullForOptionalValueWithoutImplicitNullThrowsAnException(): void
+    {
+        $this->expectException(ValidationException::class);
+        $this->expectExceptionMessage('Invalid type for age. Requires int, got NULL');
+
+        $className = $this->generateClassFromFile('ImplicitNull.json', null, false, false);
+
+        new $className(['name' => 'Hannes', 'age' => null]);
+    }
+
+    public function testNullForRequiredValueWithoutImplicitNullThrowsAnException(): void
+    {
+        $this->expectException(ValidationException::class);
+        $this->expectExceptionMessage('Invalid type for name. Requires string, got NULL');
+
+        $className = $this->generateClassFromFile('ImplicitNull.json', null, false, false);
+
+        new $className(['name' => null]);
+    }
+    public function testNullForOptionalValueWithImplicitNullIsValid(): void
+    {
+        $className = $this->generateClassFromFile('ImplicitNull.json');
+
+        $object = new $className(['name' => 'Hannes', 'age' => null]);
+        $this->assertNull($object->getAge());
+    }
+
+    public function testNullForRequiredValueWithImplicitNullThrowsAnException(): void
+    {
+        $this->expectException(ValidationException::class);
+        $this->expectExceptionMessage('Invalid type for name. Requires string, got NULL');
+
+        $className = $this->generateClassFromFile('ImplicitNull.json');
+
+        new $className(['name' => null]);
+    }
+
+    /**
+     * @dataProvider implicitNullDataProvider
+     *
+     * @param bool $implicitNull
+     */
+    public function testNullForOptionalValueWithExplicitNullIsValid(bool $implicitNull): void
+    {
+        $className = $this->generateClassFromFile('ExplicitNull.json', null, false, $implicitNull);
+
+        $object = new $className(['name' => 'Hannes', 'age' => null]);
+        $this->assertSame('Hannes', $object->getName());
+        $this->assertNull($object->getAge());
+    }
+
+    /**
+     * @dataProvider implicitNullDataProvider
+     *
+     * @param bool $implicitNull
+     */
+    public function testNullForRequiredValueWithExplicitNullIsValid(bool $implicitNull): void
+    {
+        $className = $this->generateClassFromFile('ExplicitNull.json', null, false, $implicitNull);
+
+        $object = new $className(['name' => null, 'age' => 31]);
+        $this->assertNull($object->getName());
+        $this->assertSame(31, $object->getAge());
+    }
+}

tests/Basic/FilterTest.php

@@ -639,6 +639,67 @@ public function testFilterChainWithTransformingFilter(): void
         $this->assertSame('2020-12-12T00:00:00+00:00', $object->getFilteredProperty()->format(DateTime::ATOM));
     }
 
+    /**
+     * @dataProvider implicitNullDataProvider
+     *
+     * @param bool $implicitNull
+     */
+    public function testFilterChainWithTransformingFilterOnMultiTypeProperty(bool $implicitNull): void
+    {
+        $className = $this->generateClassFromFile(
+            'FilterChainMultiType.json',
+            (new GeneratorConfiguration())
+                ->setImplicitNull($implicitNull)
+                ->addFilter(
+                    $this->getCustomFilter(
+                        [self::class, 'stripTimeFilter'],
+                        'stripTime',
+                        [DateTime::class]
+                    )
+                ),
+            false
+        );
+
+        $object = new $className(['filteredProperty' => '2020-12-12 12:12:12']);
+
+        $this->assertInstanceOf(DateTime::class, $object->getFilteredProperty());
+        $this->assertSame('2020-12-12T00:00:00+00:00', $object->getFilteredProperty()->format(DateTime::ATOM));
+
+        $object->setFilteredProperty(null);
+        $this->assertNull($object->getFilteredProperty());
+
+        $object->setFilteredProperty(new DateTime('2020-12-12 12:12:12'));
+        $this->assertSame('2020-12-12T00:00:00+00:00', $object->getFilteredProperty()->format(DateTime::ATOM));
+    }
+
+    public function testFilterWhichAppliesToMultiTypePropertyPartiallyThrowsAnException(): void
+    {
+        $this->expectException(SchemaException::class);
+        $this->expectExceptionMessage(
+            'Filter trim is not compatible with property type null for property filteredProperty'
+        );
+
+        $this->generateClassFromFile(
+            'FilterChainMultiType.json',
+            (new GeneratorConfiguration())
+                ->addFilter(
+                    $this->getCustomFilter(
+                        [self::class, 'stripTimeFilter'],
+                        'trim',
+                        ['string']
+                    )
+                )
+                ->addFilter(
+                    $this->getCustomFilter(
+                        [self::class, 'stripTimeFilter'],
+                        'stripTime',
+                        [DateTime::class]
+                    )
+                ),
+            false
+        );
+    }
+
     public static function stripTimeFilter(?DateTime $value): ?DateTime
     {
         return $value !== null ? $value->setTime(0, 0) : null;