Make sure filters are executed in the correct order

Implement transformed value pass through for filters which are executed before a transforming filter if an already transformed value is provided
Add some provider documentation

Author: wol-soft

README.md

@@ -50,6 +50,14 @@ The base object for generating models is the *Generator*. After you have created
 (new Generator())
     ->generateModels(new RecursiveDirectoryProvider(__DIR__ . '/schema'), __DIR__ . '/result');
 ```
+The first parameter of the *generateModels* method must be a class implementing the *SchemaProviderInterface*. The provider fetches the JSON schema files and provides them for the generator. The following providers are available:
+
+Provider | Description
+--- | ---
+RecursiveDirectoryProvider | Fetches all *.json files from the given source directory. Each file must contain a JSON Schema object definition on the top level
+OpenAPIv3Provider | Fetches all objects defined in the `#/components/schemas section` of an Open API v3 spec file
+
+The second parameter must point to an existing and empty directory (you may use the `generateModelDirectory` helper method to create your destination directory). This directory will contain the generated PHP classes after the generator is finished.
 
 As an optional parameter you can set up a *GeneratorConfiguration* object to configure your Generator and/or use the method *generateModelDirectory* to generate your model directory (will generate the directory if it doesn't exist; if it exists, all contained files and folders will be removed for a clean generation process):
 

docs/source/gettingStarted.rst

@@ -32,7 +32,7 @@ RecursiveDirectoryProvider  Fetches all *.json files from the given source direc
 OpenAPIv3Provider           Fetches all objects defined in the #/components/schemas section of an Open API v3 spec file
 =========================== ===========
 
-The second parameter must point to an existing and empty directory. This directory will contain the generated PHP classes after the generator is finished.
+The second parameter must point to an existing and empty directory (you may use the *generateModelDirectory* helper method to create your destination directory). This directory will contain the generated PHP classes after the generator is finished.
 
 As an optional parameter you can set up a *GeneratorConfiguration* object to configure your Generator and/or use the method *generateModelDirectory* to generate your model directory (will generate the directory if it doesn't exist; if it exists, all contained files and folders will be removed for a clean generation process):
 

docs/source/nonStandardExtensions/filter.rst

@@ -23,6 +23,8 @@ Filters can be either supplied as a string or as a list of filters (multiple fil
         }
     }
 
+If multiple filters are applied to a single property they will be executed in the order of their definition inside the JSON Schema.
+
 If a list is used filters may include additional option parameters. In this case a single filter must be provided as an object with the key **filter** defining the filter:
 
 .. code-block:: json
@@ -47,17 +49,19 @@ Transforming filter
 
 .. warning::
 
-    Read this section carefully and understand it if you want to use filters which transform the type of the property
+    Read this section carefully and understand it if you want to use filters which transform the type of the property without breaking your bones
+
+    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.
 
 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.
 
-The return type of the last applied 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.
+Only one transforming filter per property is allowed. may be positioned anywhere in the filter chain of a single property. If multiple filters are applied and a transforming filter is among them you have to make sure the property types are compatible.
 
 If you write a custom transforming filter you must define the return type of your filter function as the implementation uses Reflection methods to determine to which type a value is transformed by a filter.
 
-Only one transforming filter per property is allowed. may be positioned anywhere in the filter chain of a single property. If multiple filters are applied and a transforming filter is among them you have to make sure the property types are compatible.
+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).
 
 Builtin filter
 --------------
@@ -159,15 +163,15 @@ Let's have a look how the generated model behaves:
 Additional options
 ~~~~~~~~~~~~~~~~~~
 
-================        ============= ===========
+======================= ============= ===========
 Option                  Default value Description
-================        ============= ===========
+======================= ============= ===========
 convertNullToNow        false         If null is provided a DateTime object with the current time will be created (works only if the property isn't required as null would be denied otherwise before the filter is executed)
 convertEmptyValueToNull false         If an empty string is provided and this option is set to true the property will contain null after the filter has been applied
 denyEmptyValue          false         An empty string value will be denied (by default an empty string value will result in a DateTime object with the current time)
 createFromFormat        null          Provide a pattern which is used to parse the provided value (DateTime object will be created via DateTime::createFromFormat if a format is provided)
 outputFormat            DATE_ISO8601  The output format if serialization is enabled and toArray or toJSON is called on a transformed property. If a createFromFormat is defined but no outputFormat the createFromFormat value will override the default value
-================        ============= ===========
+======================= ============= ===========
 
 .. hint::
 

src/Model/Property/Property.php

@@ -36,7 +36,7 @@ class Property implements PropertyInterface
     protected $defaultValue;
 
     /** @var Validator[] */
-    protected $validator = [];
+    protected $validators = [];
     /** @var Schema */
     protected $schema;
     /** @var PropertyDecoratorInterface[] */
@@ -150,7 +150,7 @@ public function getDescription(): string
      */
     public function addValidator(PropertyValidatorInterface $validator, int $priority = 99): PropertyInterface
     {
-        $this->validator[] = new Validator($validator, $priority);
+        $this->validators[] = new Validator($validator, $priority);
 
         return $this;
     }
@@ -160,15 +160,15 @@ public function addValidator(PropertyValidatorInterface $validator, int $priorit
      */
     public function getValidators(): array
     {
-        return $this->validator;
+        return $this->validators;
     }
 
     /**
      * @inheritdoc
      */
     public function filterValidators(callable $filter): PropertyInterface
     {
-        $this->validator = array_filter($this->validator, $filter);
+        $this->validators = array_filter($this->validators, $filter);
 
         return $this;
     }
@@ -179,7 +179,7 @@ public function filterValidators(callable $filter): PropertyInterface
     public function getOrderedValidators(): array
     {
         usort(
-            $this->validator,
+            $this->validators,
             function (Validator $validator, Validator $comparedValidator) {
                 if ($validator->getPriority() == $comparedValidator->getPriority()) {
                     return 0;
@@ -192,7 +192,7 @@ function (Validator $validator, Validator $comparedValidator) {
             function (Validator $validator) {
                 return $validator->getValidator();
             },
-            $this->validator
+            $this->validators
         );
     }
 

src/Model/Property/PropertyInterface.php

@@ -67,6 +67,16 @@ public function getDescription(): string;
     /**
      * Add a validator for the property
      *
+     * The priority is used to order the validators applied to a property.
+     * The validators with the lowest priority number will be executed first.
+     *
+     * Priority 1:   Required checks
+     * Priority 2:   Type Checks
+     * Priority 3:   Enum Checks
+     * Priority 10+: Filter validators
+     * Priority 99:  Default priority used for casual validators
+     * Priority 100: Validators for compositions
+     *
      * @param PropertyValidatorInterface $validator
      * @param int $priority
      *

src/Model/Validator/FilterValidator.php

@@ -27,17 +27,14 @@ class FilterValidator extends PropertyTemplateValidator
      * @param GeneratorConfiguration $generatorConfiguration
      * @param FilterInterface $filter
      * @param PropertyInterface $property
-     * @param Schema $schema
      * @param array $filterOptions
      *
-     * @throws ReflectionException
      * @throws SchemaException
      */
     public function __construct(
         GeneratorConfiguration $generatorConfiguration,
         FilterInterface $filter,
         PropertyInterface $property,
-        Schema $schema,
         array $filterOptions = []
     ) {
         if (!empty($filter->getAcceptedTypes()) &&
@@ -62,7 +59,7 @@ public function __construct(
             ),
             DIRECTORY_SEPARATOR . 'Validator' . DIRECTORY_SEPARATOR . 'Filter.phptpl',
             [
-                'skipTransformedValuesCheck' => $this->getTransformedCheck($filter, $property, $schema),
+                'skipTransformedValuesCheck' => false,
                 // check if the given value has a type matched by the filter
                 'typeCheck' => !empty($filter->getAcceptedTypes())
                     ? '($value !== null && (!is_' .
@@ -83,33 +80,35 @@ public function __construct(
     }
 
     /**
-     * Check if the return type of the provided filter transforms the value. If the value is transformed by the filter
-     * make sure the filter is only executed if a non-transformed value is provided.
+     * Make sure the filter is only executed if a non-transformed value is provided.
      * This is required as a setter (eg. for a string property which is modified by the DateTime filter into a DateTime
      * object) also accepts a transformed value (in this case a DateTime object).
+     * If transformed values are provided neither filters defined before the transforming filter in the filter chain nor
+     * the transforming filter must be executed as they are only compatible with the original value
      *
-     * @param FilterInterface $filter
+     * @param TransformingFilterInterface $filter
      * @param PropertyInterface $property
      * @param Schema $schema
      *
-     * @return string
+     * @return self
      *
      * @throws ReflectionException
      */
-    private function getTransformedCheck(FilterInterface $filter, PropertyInterface $property, Schema $schema): string
-    {
-        if ($filter instanceof TransformingFilterInterface) {
-            $typeAfterFilter = (new ReflectionMethod($filter->getFilter()[0], $filter->getFilter()[1]))
-                ->getReturnType();
+    public function addTransformedCheck(
+        TransformingFilterInterface $filter,
+        PropertyInterface $property,
+        Schema $schema
+    ): self {
+        $typeAfterFilter = (new ReflectionMethod($filter->getFilter()[0], $filter->getFilter()[1]))->getReturnType();
 
-            if ($typeAfterFilter &&
-                $typeAfterFilter->getName() &&
-                !in_array($typeAfterFilter->getName(), $filter->getAcceptedTypes())
-            ) {
-                return (new ReflectionTypeCheckValidator($typeAfterFilter, $property, $schema))->getCheck();
-            }
+        if ($typeAfterFilter &&
+            $typeAfterFilter->getName() &&
+            !in_array($typeAfterFilter->getName(), $filter->getAcceptedTypes())
+        ) {
+            $this->templateValues['skipTransformedValuesCheck'] =
+                (new ReflectionTypeCheckValidator($typeAfterFilter, $property, $schema))->getCheck();
         }
 
-        return '';
+        return $this;
     }
-}
+}

src/PropertyProcessor/Filter/FilterProcessor.php

@@ -45,6 +45,8 @@ public function process(
         }
 
         $hasTransformingFilter = false;
+        // apply a different priority to each filter to make sure the order is kept
+        $filterPriority = 10;
 
         foreach ($filterList as $filterToken) {
             $filterOptions = [];
@@ -58,8 +60,8 @@ public function process(
             }
 
             $property->addValidator(
-                new FilterValidator($generatorConfiguration, $filter, $property, $schema, $filterOptions),
-                3
+                new FilterValidator($generatorConfiguration, $filter, $property, $filterOptions),
+                $filterPriority++
             );
 
             if ($filter instanceof TransformingFilterInterface) {
@@ -78,6 +80,7 @@ public function process(
                     $typeAfterFilter->getName() &&
                     $property->getType() !== $typeAfterFilter->getName()
                 ) {
+                    $this->addTransformedValuePassThrough($property, $schema, $filter);
                     $this->extendTypeCheckValidatorToAllowTransformedValue($property, $schema, $typeAfterFilter);
 
                     $property->setType($property->getType(), $typeAfterFilter->getName());
@@ -90,6 +93,32 @@ public function process(
         }
     }
 
+    /**
+     * Apply a check to each FilterValidator which is already associated with the given property to pass through values
+     * which are already transformed.
+     * By adding the pass through eg. a trim filter executed before a dateTime transforming filter will not be executed
+     * if a DateTime object is provided for the property
+     *
+     * @param PropertyInterface $property
+     * @param Schema $schema
+     * @param TransformingFilterInterface $filter
+     *
+     * @throws ReflectionException
+     */
+    private function addTransformedValuePassThrough(
+        PropertyInterface $property,
+        Schema $schema,
+        TransformingFilterInterface $filter
+    ): void {
+        foreach ($property->getValidators() as $validator) {
+            $validator = $validator->getValidator();
+
+            if ($validator instanceof FilterValidator) {
+                $validator->addTransformedCheck($filter, $property, $schema);
+            }
+        }
+    }
+
     /**
      * Extend a type check of the given property so the type check also allows the type of $typeAfterFilter. This is
      * used to allow also already transformed values as valid input values

tests/Basic/FilterTest.php

@@ -3,6 +3,7 @@
 namespace PHPModelGenerator\Tests\Basic;
 
 use DateTime;
+use Exception;
 use PHPModelGenerator\Exception\ErrorRegistryException;
 use PHPModelGenerator\Exception\InvalidFilterException;
 use PHPModelGenerator\Exception\SchemaException;
@@ -11,6 +12,8 @@
 use PHPModelGenerator\Model\GeneratorConfiguration;
 use PHPModelGenerator\PropertyProcessor\Filter\DateTimeFilter;
 use PHPModelGenerator\PropertyProcessor\Filter\FilterInterface;
+use PHPModelGenerator\PropertyProcessor\Filter\TransformingFilterInterface;
+use PHPModelGenerator\PropertyProcessor\Filter\TrimFilter;
 use PHPModelGenerator\Tests\AbstractPHPModelGeneratorTest;
 
 /**
@@ -306,6 +309,42 @@ public function multipleFilterDataProvider(): array
         ];
     }
 
+    /**
+     * @dataProvider invalidCustomFilterDataProvider
+     *
+     * @param array $customInvalidFilter
+     */
+    public function testAddFilterWithInvalidSerializerThrowsAnException(array $customInvalidFilter): void
+    {
+        $this->expectException(InvalidFilterException::class);
+        $this->expectExceptionMessage('Invalid serializer callback for filter customTransformingFilter');
+
+        (new GeneratorConfiguration())->addFilter($this->getCustomTransformingFilter($customInvalidFilter));
+    }
+
+    protected function getCustomTransformingFilter(
+        array $customSerializer
+    ): TransformingFilterInterface {
+        return new class ($customSerializer) extends TrimFilter implements TransformingFilterInterface {
+            private $customSerializer;
+
+            public function __construct(array $customSerializer)
+            {
+                $this->customSerializer = $customSerializer;
+            }
+
+            public function getToken(): string
+            {
+                return 'customTransformingFilter';
+            }
+
+            public function getSerializer(): array
+            {
+                return $this->customSerializer;
+            }
+        };
+    }
+
     /**
      * @dataProvider validDateTimeFilterDataProvider
      */
@@ -420,4 +459,44 @@ public function getToken(): string
             )
         );
     }
+
+    public function testFilterBeforeTransformingFilterIsExecutedIfNonTransformedValueIsProvided(): void
+    {
+        $this->expectException(ErrorRegistryException::class);
+        $this->expectExceptionMessage(
+            'Invalid value for property filteredProperty denied by filter exceptionFilter: ' .
+            'Exception filter called with 12.12.2020'
+        );
+
+        $className = $this->generateClassFromFile(
+            'FilterPassThrough.json',
+            (new GeneratorConfiguration())->addFilter(
+                $this->getCustomFilter([self::class, 'exceptionFilter'], 'exceptionFilter')
+            )
+        );
+
+        new $className(['filteredProperty' => '12.12.2020']);
+    }
+
+    public function testFilterBeforeTransformingFilterIsSkippedIfTransformedValueIsProvided(): void
+    {
+        $className = $this->generateClassFromFile(
+            'FilterPassThrough.json',
+            (new GeneratorConfiguration())->addFilter(
+                $this->getCustomFilter([self::class, 'exceptionFilter'], 'exceptionFilter')
+            )
+        );
+
+        $object = new $className(['filteredProperty' => new DateTime('2020-12-10')]);
+
+        $this->assertSame(
+            (new DateTime('2020-12-10'))->format(DATE_ATOM),
+            $object->getFilteredProperty()->format(DATE_ATOM)
+        );
+    }
+
+    public static function exceptionFilter(string $value): void
+    {
+        throw new Exception("Exception filter called with $value");
+    }
 }