Add validation to filter options (closes #62)

Author: wol-soft

composer.json

@@ -11,7 +11,7 @@
         }
     ],
     "require": {
-        "wol-soft/php-json-schema-model-generator-production": "^0.17.0",
+        "wol-soft/php-json-schema-model-generator-production": "^0.18.0",
         "wol-soft/php-micro-template": "^1.3.2",
 
         "php": ">=7.2",

docs/source/nonStandardExtensions/filter.rst

@@ -392,6 +392,19 @@ The option will be available if your JSON-Schema uses the object-notation for th
         }
     }
 
+Validating filter options
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your filter accepts additional filter options you may want to validate the provided options during the model generation process to avoid runtime errors.
+To achieve a validation of the options your custom filter must implement the **PHPModelGenerator\\Filter\\ValidateOptionsInterface**.
+This interface adds the following method to your implementation:
+
+.. code-block:: php
+    public function validateOptions(array $options): void;
+
+The options provided in the schema which utilizes the filter are passed to the method during the model generation.
+If invalid options are detected just throw an exception which will result in a **SchemaException**.
+
 Custom transforming filter
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

src/PropertyProcessor/Filter/FilterProcessor.php

@@ -4,8 +4,10 @@
 
 namespace PHPModelGenerator\PropertyProcessor\Filter;
 
+use Exception;
 use PHPModelGenerator\Exception\SchemaException;
 use PHPModelGenerator\Filter\TransformingFilterInterface;
+use PHPModelGenerator\Filter\ValidateOptionsInterface;
 use PHPModelGenerator\Model\GeneratorConfiguration;
 use PHPModelGenerator\Model\Property\PropertyInterface;
 use PHPModelGenerator\Model\Property\PropertyType;
@@ -70,6 +72,22 @@ public function process(
                 );
             }
 
+            if ($filter instanceof ValidateOptionsInterface) {
+                try {
+                    $filter->validateOptions($filterOptions);
+                } catch (Exception $exception) {
+                    throw new SchemaException(
+                        sprintf(
+                            'Invalid filter options on filter %s on property %s in file %s: %s',
+                            $filterToken,
+                            $property->getName(),
+                            $property->getJsonSchema()->getFile(),
+                            $exception->getMessage()
+                        )
+                    );
+                }
+            }
+
             $property->addValidator(
                 new FilterValidator($generatorConfiguration, $filter, $property, $filterOptions, $transformingFilter),
                 $filterPriority++

tests/Basic/FilterTest.php

@@ -11,6 +11,7 @@
 use PHPModelGenerator\Filter\FilterInterface;
 use PHPModelGenerator\Filter\TransformingFilterInterface;
 use PHPModelGenerator\Filter\Trim;
+use PHPModelGenerator\Filter\ValidateOptionsInterface;
 use PHPModelGenerator\Model\GeneratorConfiguration;
 use PHPModelGenerator\PropertyProcessor\Filter\DateTimeFilter;
 use PHPModelGenerator\PropertyProcessor\Filter\TrimFilter;
@@ -290,6 +291,97 @@ public function customFilterDataProvider(): array
         ];
     }
 
+    /**
+     * @dataProvider invalidEncodingFilterConfigurationsDataProvider
+     */
+    public function testInvalidCustomFilterOptionValidation(string $configuration, string $expectedErrorMessage): void
+    {
+        $this->expectException(SchemaException::class);
+        $this->expectExceptionMessageMatches(
+            "/Invalid filter options on filter encode on property .*\: $expectedErrorMessage/"
+        );
+
+        $this->generateClassFromFileTemplate(
+            'Encode.json',
+            [$configuration],
+            (new GeneratorConfiguration())->setImmutable(false)->addFilter($this->getEncodeFilter()),
+            false
+        );
+    }
+
+    public function invalidEncodingFilterConfigurationsDataProvider(): array
+    {
+        return [
+            'simple notation without options' => ['"encode"', 'Missing charset configuration'],
+            'object notation without charset configuration' => ['{"filter": "encode"}', 'Missing charset configuration'],
+            'Invalid charset configuration' => ['{"filter": "encode", "charset": 1}', 'Unsupported charset'],
+            'Invalid charset configuration 2' => ['{"filter": "encode", "charset": "UTF-16"}', 'Unsupported charset'],
+        ];
+    }
+
+    /**
+     * @dataProvider validEncodingsDataProvider
+     */
+    public function testValidCustomFilterOptionValidation(string $encoding, string $input, string $output): void
+    {
+        $classname = $this->generateClassFromFileTemplate(
+            'Encode.json',
+            [sprintf('{"filter": "encode", "charset": "%s"}', $encoding)],
+            (new GeneratorConfiguration())->setImmutable(false)->addFilter($this->getEncodeFilter()),
+            false
+        );
+
+        $object = new $classname(['property' => $input]);
+
+        $this->assertSame($encoding, mb_detect_encoding($object->getProperty()));
+        $this->assertSame($output, $object->getProperty());
+    }
+
+    public function validEncodingsDataProvider(): array
+    {
+        return [
+            'ASCII to ASCII' => ['ASCII', 'Hello World', 'Hello World'],
+            'UTF-8 to ASCII' => ['ASCII', 'áéó', '???'],
+            'UTF-8 to UTF-8' => ['UTF-8', 'áéó', 'áéó'],
+        ];
+    }
+
+    private function getEncodeFilter()
+    {
+        return new class () implements FilterInterface, ValidateOptionsInterface {
+            public function getAcceptedTypes(): array
+            {
+                return ['string'];
+            }
+
+            public function getToken(): string
+            {
+                return 'encode';
+            }
+
+            public function getFilter(): array
+            {
+                return [FilterTest::class, 'encode'];
+            }
+
+            public function validateOptions(array $options): void
+            {
+                if (!isset($options['charset'])) {
+                    throw new Exception('Missing charset configuration');
+                }
+
+                if (!in_array($options['charset'], ['UTF-8', 'ASCII'])) {
+                    throw new Exception('Unsupported charset');
+                }
+            }
+        };
+    }
+
+    public static function encode(string $value, array $options): string
+    {
+        return mb_convert_encoding($value, $options['charset'], 'auto');
+    }
+
     /**
      * @dataProvider multipleFilterDataProvider
      *

tests/Schema/FilterTest/Encode.json

@@ -0,0 +1,9 @@
+{
+  "type": "object",
+  "properties": {
+    "property": {
+      "type": "string",
+      "filter": %s
+    }
+  }
+}