Add custom serializer functionality for transforming filters

Move serialization methods into trait loaded from the production repository

Author: wol-soft

docs/source/nonStandardExtensions/filter.rst

@@ -55,7 +55,7 @@ As the required check is executed before the filter a filter may transform a req
 
 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.
 
-For working models you must define the return type of your filter function as the implementation uses Reflection methods to determine whether a filter transforms a value or keeps the type (like the **trim** filter).
+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.
 
 Builtin filter
 --------------
@@ -163,6 +163,7 @@ 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)
 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
 ================ ============= ===========
 
 Custom filter
@@ -271,3 +272,53 @@ The option will be available if your JSON-Schema uses the object-notation for th
             }
         }
     }
+
+Custom transforming filter
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to provide a custom filter which transforms a value (eg. redirect data into a manually written model) you must implement the **PHPModelGenerator\\PropertyProcessor\\Filter\\TransformingFilterInterface**. This interface adds the **getSerializer** method to your filter. The method is similar to the **getFilter** method. It must return a callable which is available during the render process as well as during code execution. The returned callable must return null or a string and undo a transformation (eg. the serializer method of the builtin **dateTime** filter transforms a DateTime object back into a formatted string). The serializer method will be called with the current value of the property as the first argument and with the (optionally provided) additional options of the filter as the second argument. Your custom transforming filter might look like:
+
+
+.. code-block:: php
+
+    namespace MyApp\Model\Generator\Filter;
+
+    use MyApp\Model\ManuallyWrittenModels\Customer;
+    use PHPModelGenerator\PropertyProcessor\Filter\TransformingFilterInterface;
+
+    class CustomerFilter implements TransformingFilterInterface
+    {
+        // Let's assume you have written a Customer model manually eg. due to advanced validations
+        // and you want to use the Customer model as a part of your generated model
+        public static function instantiateCustomer(?array $data, array $additionalOptions): ?Customer
+        {
+            return $data !== null ? new Customer($data, $additionalOptions) : null;
+        }
+
+        // $customer will contain the current value of the property the filter is applied to
+        // $additionalOptions will contain all additional options from the JSON Schema
+        public static function instantiateCustomer(?Customer $customer, array $additionalOptions): ?string
+        {
+            return $data !== null ? $customer->serialize($additionalOptions) : null;
+        }
+
+        public function getAcceptedTypes(): array
+        {
+            return ['object'];
+        }
+
+        public function getToken(): string
+        {
+            return 'uppercase';
+        }
+
+        public function getFilter(): array
+        {
+            return [self::class, 'instantiateCustomer'];
+        }
+
+        public function getSerializer(): array
+        {
+            return [self::class, 'serializeCustomer'];
+        }
+    }

src/Model/GeneratorConfiguration.php

@@ -7,6 +7,7 @@
 use PHPModelGenerator\Exception\InvalidFilterException;
 use PHPModelGenerator\PropertyProcessor\Filter\DateTimeFilter;
 use PHPModelGenerator\PropertyProcessor\Filter\FilterInterface;
+use PHPModelGenerator\PropertyProcessor\Filter\TransformingFilterInterface;
 use PHPModelGenerator\PropertyProcessor\Filter\TrimFilter;
 use PHPModelGenerator\Utils\ClassNameGenerator;
 use PHPModelGenerator\Utils\ClassNameGeneratorInterface;
@@ -73,6 +74,16 @@ public function addFilter(FilterInterface $filter): self
             throw new InvalidFilterException("Invalid filter callback for filter {$filter->getToken()}");
         }
 
+        if ($filter instanceof TransformingFilterInterface) {
+            if (!(count($filter->getSerializer()) === 2) ||
+                !is_string($filter->getSerializer()[0]) ||
+                !is_string($filter->getSerializer()[1]) ||
+                !is_callable($filter->getSerializer())
+            ) {
+                throw new InvalidFilterException("Invalid serializer callback for filter {$filter->getToken()}");
+            }
+        }
+
         $this->filter[$filter->getToken()] = $filter;
 
         return $this;

src/Model/Property/Serializer/TransformingFilterSerializer.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\Model\Property\Serializer;
+
+use PHPMicroTemplate\Exception\FileSystemException;
+use PHPMicroTemplate\Exception\SyntaxErrorException;
+use PHPMicroTemplate\Exception\UndefinedSymbolException;
+use PHPMicroTemplate\Render;
+use PHPModelGenerator\Model\GeneratorConfiguration;
+use PHPModelGenerator\PropertyProcessor\Filter\TransformingFilterInterface;
+use PHPModelGenerator\Utils\RenderHelper;
+
+/**
+ * Class TransformingFilterSerializer
+ *
+ * @package PHPModelGenerator\Model\Property\Serializer
+ */
+class TransformingFilterSerializer
+{
+    /** @var string */
+    protected $propertyName;
+    /** @var TransformingFilterInterface */
+    protected $filter;
+    /** @var array */
+    private $filterOptions;
+
+    /**
+     * TransformingFilterSerializer constructor.
+     *
+     * @param string $propertyName
+     * @param TransformingFilterInterface $filter
+     * @param array $filterOptions
+     */
+    public function __construct(
+        string $propertyName,
+        TransformingFilterInterface $filter,
+        array $filterOptions
+    ) {
+        $this->propertyName = $propertyName;
+        $this->filter = $filter;
+        $this->filterOptions = $filterOptions;
+    }
+
+    /**
+     * @param GeneratorConfiguration $generatorConfiguration
+     *
+     * @return string
+     *
+     * @throws FileSystemException
+     * @throws SyntaxErrorException
+     * @throws UndefinedSymbolException
+     */
+    public function getSerializer(GeneratorConfiguration $generatorConfiguration): string
+    {
+        return (new Render(join(DIRECTORY_SEPARATOR, [__DIR__, '..', '..', '..', 'Templates']) . DIRECTORY_SEPARATOR))
+            ->renderTemplate(
+                DIRECTORY_SEPARATOR . 'Serializer' . DIRECTORY_SEPARATOR . 'TransformingFilterSerializer.phptpl',
+                [
+                    'viewHelper' => new RenderHelper($generatorConfiguration),
+                    'property' => $this->propertyName,
+                    'serializerClass' => $this->filter->getSerializer()[0],
+                    'serializerMethod' => $this->filter->getSerializer()[1],
+                    'serializerOptions' => var_export($this->filterOptions, true),
+                ]
+            );
+    }
+}

src/Model/RenderJob.php

@@ -132,6 +132,7 @@ protected function renderClass(GeneratorConfiguration $generatorConfiguration):
                     'class'                  => $this->className,
                     'baseValidators'         => $this->schema->getBaseValidators(),
                     'properties'             => $this->schema->getProperties(),
+                    'customSerializer'       => $this->schema->getCustomSerializer(),
                     'generatorConfiguration' => $generatorConfiguration,
                     'viewHelper'             => new RenderHelper($generatorConfiguration),
                     'initialClass'           => $this->initialClass,

src/Model/Schema.php

@@ -5,6 +5,7 @@
 namespace PHPModelGenerator\Model;
 
 use PHPModelGenerator\Model\Property\PropertyInterface;
+use PHPModelGenerator\Model\Property\Serializer\TransformingFilterSerializer;
 use PHPModelGenerator\Model\SchemaDefinition\SchemaDefinitionDictionary;
 use PHPModelGenerator\Model\Validator\PropertyValidatorInterface;
 use PHPModelGenerator\Model\Validator\SchemaDependencyValidator;
@@ -31,6 +32,8 @@ class Schema
     protected $usedClasses = [];
     /** @var SchemaNamespaceTransferDecorator[] */
     protected $namespaceTransferDecorators = [];
+    /** @var TransformingFilterSerializer[] */
+    protected $customSerializer = [];
 
     /** @var SchemaDefinitionDictionary */
     protected $schemaDefinitionDictionary;
@@ -191,4 +194,24 @@ public function getUsedClasses(array $visitedSchema = []): array
 
         return $usedClasses;
     }
+
+    /**
+     * @param TransformingFilterSerializer $serializer
+     *
+     * @return $this
+     */
+    public function addCustomSerializer(TransformingFilterSerializer $serializer): self
+    {
+        $this->customSerializer[] = $serializer;
+
+        return $this;
+    }
+
+    /**
+     * @return TransformingFilterSerializer[]
+     */
+    public function getCustomSerializer(): array
+    {
+        return $this->customSerializer;
+    }
 }

src/PropertyProcessor/Filter/DateTimeFilter.php

@@ -13,37 +13,37 @@
  *
  * @package PHPModelGenerator\PropertyProcessor\Filter
  */
-class DateTimeFilter implements FilterInterface
+class DateTimeFilter implements TransformingFilterInterface
 {
     /**
-     * Return a list of accepted data types for the filter (eg. ['string', 'int']). If the filter is applied to a
-     * value which doesn't match an accepted type an exception will be thrown
-     *
-     * @return array
+     * @inheritDoc
      */
     public function getAcceptedTypes(): array
     {
         return ['string'];
     }
 
     /**
-     * Return the token for the filter
-     *
-     * @return string
+     * @inheritDoc
      */
     public function getToken(): string
     {
         return 'dateTime';
     }
 
     /**
-     * Return the filter to apply. Make sure the returned array is a callable which is also callable after the
-     * render process
-     *
-     * @return array
+     * @inheritDoc
      */
     public function getFilter(): array
     {
         return [DateTime::class, 'filter'];
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSerializer(): array
+    {
+        return [DateTime::class, 'serialize'];
+    }
 }

src/PropertyProcessor/Filter/FilterProcessor.php

@@ -7,6 +7,7 @@
 use PHPModelGenerator\Exception\SchemaException;
 use PHPModelGenerator\Model\GeneratorConfiguration;
 use PHPModelGenerator\Model\Property\PropertyInterface;
+use PHPModelGenerator\Model\Property\Serializer\TransformingFilterSerializer;
 use PHPModelGenerator\Model\Schema;
 use PHPModelGenerator\Model\Validator;
 use PHPModelGenerator\Model\Validator\FilterValidator;
@@ -63,7 +64,7 @@ public function process(
         }
 
         // check if the last applied filter has changed the type of the property
-        if ($filter) {
+        if ($filter instanceof TransformingFilterInterface) {
             $typeAfterFilter = (new ReflectionMethod($filter->getFilter()[0], $filter->getFilter()[1]))
                 ->getReturnType();
 
@@ -74,6 +75,10 @@ public function process(
                 $this->extendTypeCheckValidatorToAllowTransformedValue($property, $schema, $typeAfterFilter);
 
                 $property->setType($property->getType(), $typeAfterFilter->getName());
+
+                $schema->addCustomSerializer(
+                    new TransformingFilterSerializer($property->getAttribute(), $filter, $filterOptions)
+                );
             }
         }
     }

src/PropertyProcessor/Filter/TransformingFilterInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\PropertyProcessor\Filter;
+
+interface TransformingFilterInterface extends FilterInterface
+{
+    /**
+     * Return the serializer to apply to transformed values.
+     * Make sure the returned array is a callable which is also callable after the render process
+     *
+     * @return array
+     */
+    public function getSerializer(): array;
+}

src/Templates/Model.phptpl

@@ -19,6 +19,8 @@ declare(strict_types = 1);
 class {{ class }} implements \PHPModelGenerator\Interfaces\JSONModelInterface
 {% if generatorConfiguration.hasSerializationEnabled() %}, \PHPModelGenerator\Interfaces\SerializationInterface{% endif %}
 {
+    {% if generatorConfiguration.hasSerializationEnabled() %}use \PHPModelGenerator\Traits\SerializableTrait;{% endif %}
+
     {% foreach properties as property %}
         /** @var {{ property.getTypeHint(true) }}{% if not property.isRequired() %}|null{% endif %}{% if property.getDescription() %} {{ property.getDescription() }}{% endif %} */
         protected ${{ property.getAttribute() }}{% if not viewHelper.isNull(property.getDefaultValue()) %} = {{ property.getDefaultValue() }}{% endif %};
@@ -171,75 +173,8 @@ class {{ class }} implements \PHPModelGenerator\Interfaces\JSONModelInterface
     {% endforeach %}
 
     {% if generatorConfiguration.hasSerializationEnabled() %}
-        /**
-         * Get an array representation of the current state
-         *
-         * @param int $depth the maximum level of object nesting. Must be greater than 0
-         *
-         * @return array|false
-         */
-        public function toArray(int $depth = 512)
-        {
-            if ($depth < 1) {
-                return false;
-            }
-
-            $depth--;
-            $modelData = [];
-
-            foreach (get_object_vars($this) as $key => $value) {
-                if (in_array($key, ['rawModelDataInput', 'errorRegistry'])) {
-                    continue;
-                }
-
-                if (is_array($value)) {
-                    $subData = [];
-                    foreach ($value as $subKey => $element) {
-                        $subData[$subKey] = $this->evaluateAttribute($element, $depth);
-                    }
-                    $modelData[$key] = $subData;
-                } else {
-                    $modelData[$key] = $this->evaluateAttribute($value, $depth);
-                }
-            }
-
-            return $modelData;
-        }
-
-        private function evaluateAttribute($attribute, int $depth)
-        {
-            if (!is_object($attribute)) {
-                return $attribute;
-            }
-
-            if ($depth === 0 && method_exists($attribute, '__toString')) {
-                return (string) $attribute;
-            }
-
-            return (0 >= $depth)
-                ? null
-                : (
-                    method_exists($attribute, 'toArray')
-                        ? $attribute->toArray($depth - 1)
-                        : get_object_vars($attribute)
-                );
-        }
-
-        /**
-         * Get a JSON representation of the current state
-         *
-         * @param int $options Bitmask for json_encode
-         * @param int $depth   the maximum level of object nesting. Must be greater than 0
-         *
-         * @return string|false
-         */
-        public function toJSON(int $options = 0, int $depth = 512)
-        {
-            if ($depth < 1) {
-                return false;
-            }
-
-            return json_encode($this->toArray($depth), $options, $depth);
-        }
+        {% foreach customSerializer as serializer %}
+            {{ serializer.getSerializer(generatorConfiguration) }}
+        {% endforeach %}
     {% endif %}
 }