Add filter

Add readonly documentation

Author: wol-soft

composer.json

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

docs/source/generic/readonly.rst

@@ -0,0 +1,29 @@
+Readonly values
+===============
+
+By default all classes are immutable. If the GeneratorConfiguration option for immutability is disabled setters for all properties are generated. If single properties should be readonly the keyword `readonly` can be used.
+
+.. code-block:: json
+
+    {
+        "$id": "person",
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "readonly": true
+            },
+            "age": {
+                "type": "integer"
+            }
+        }
+    }
+
+Generated interface (with immutability disabled):
+
+.. code-block:: php
+
+    public function getName(): ?string;
+
+    public function setAge(?int $example): self;
+    public function getAge(): ?int;

docs/source/generic/required.rst

@@ -30,7 +30,7 @@ Behaviour with different inputs:
 
     // property example not provided
     $example = new Example([]);
-    $example->getExample();     // returns "Not provided"
+    $example->getExample();     // returns "Not provided". If no default value has been defined in the schema NULL would be returned
 
     // property example explicitly set to null (allowed as the property isn't required)
     $example = new Example(['example' => null]);
@@ -55,7 +55,7 @@ By setting the property to a required value the property must be always provided
         "required": ["example"]
     }
 
-Generated interface (typehints not nullable any longer):
+Generated interface (type hints not nullable any longer):
 
 .. code-block:: php
 

docs/source/index.rst

@@ -12,3 +12,4 @@ Generates PHP model classes from JSON-Schema files including validation and prov
 .. include:: toc-types.rst
 .. include:: toc-complexTypes.rst
 .. include:: toc-combinedSchemas.rst
+.. include:: toc-nonStandardExtensions.rst

docs/source/nonStandardExtensions/filter.rst

@@ -0,0 +1,85 @@
+Filter
+======
+
+Filter can be used to preprocess values. Filters are applied after the required and type validation. If a filter is applied to a property which has a type which is not supported by the filter an exception will be thrown.
+Filters can be either supplied as a string or as a list of filters:
+
+.. code-block:: json
+
+    {
+        "$id": "person",
+        "type": "object",
+        "properties": {
+            "firstname": {
+                "type": "string",
+                "filter": "trim"
+            },
+            "lastname": {
+                "type": "string",
+                "filter": [
+                    "trim"
+                ]
+            }
+        }
+    }
+
+Builtin filter
+--------------
+
+trim
+^^^^
+
+The trim filter is only valid for string properties.
+
+.. code-block:: json
+
+    {
+        "$id": "person",
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "filter": "trim",
+                "minLength": 2,
+            }
+        }
+    }
+
+Let's have a look how the generated model behaves:
+
+.. code-block:: php
+
+    // valid, the name will be NULL as the name is not required
+    $person = new Person();
+
+    // Throws an exception as the name provides an invalid value after being trimmed.
+    // Exception: 'Value for name must not be shorter than 2'
+    $person = new Person(['name' => '   A   ']);
+
+    // A valid example
+    $person = new Person(['name' => '   Albert ']);
+    $person->getName(); // returns 'Albert'
+    // the raw model data input is not affected by the filter
+    $person->getRawModelDataInput(); // returns ['name' => '   Albert ']
+
+    // If setters are generated the setters also perform validations.
+    // Exception: 'Value for name must not be shorter than 2'
+    $person->setName('  D ');
+
+If the filter trim is used for a property which doesn't require a string value and a non string value is provided an exception will be thrown:
+
+* Filter trim is not compatible with property type __TYPE__ for property __PROPERTY_NAME__
+
+Custom filter
+-------------
+
+You can implement custom filter and use them in your schema files. You must add your custom filter to the generator configuration.
+
+.. code-block:: php
+
+    $generator = new Generator(
+        (new GeneratorConfiguration())
+            ->addFilter(new UppercaseFilter())
+    );
+
+Your filter must implement the interface **PHPModelGenerator\\PropertyProcessor\\Filter\\FilterInterface**. Make sure the given callable array returned by **getFilter** is accessible as well during the generation process as during code execution using the generated model.

docs/source/toc-nonStandardExtensions.rst

@@ -0,0 +1,5 @@
+.. toctree::
+    :caption: Non standard extensions
+    :maxdepth: 1
+
+    nonStandardExtensions/filter

src/Exception/InvalidFilterException.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\Exception;
+
+/**
+ * Class InvalidFilterException
+ *
+ * @package PHPModelGenerator\Exception
+ */
+class InvalidFilterException extends PHPModelGeneratorException
+{
+}

src/Model/GeneratorConfiguration.php

@@ -4,6 +4,9 @@
 
 namespace PHPModelGenerator\Model;
 
+use PHPModelGenerator\Exception\InvalidFilterException;
+use PHPModelGenerator\PropertyProcessor\Filter\FilterInterface;
+use PHPModelGenerator\PropertyProcessor\Filter\TrimFilter;
 use PHPModelGenerator\Utils\ClassNameGenerator;
 use PHPModelGenerator\Utils\ClassNameGeneratorInterface;
 use PHPModelGenerator\Exception\ErrorRegistryException;
@@ -34,13 +37,54 @@ class GeneratorConfiguration
     protected $serialization = false;
     /** @var ClassNameGeneratorInterface */
     protected $classNameGenerator;
+    /** @var FilterInterface[] */
+    protected $filter;
 
     /**
      * GeneratorConfiguration constructor.
      */
     public function __construct()
     {
         $this->classNameGenerator = new ClassNameGenerator();
+
+        $this->addFilter(new TrimFilter());
+    }
+
+    /**
+     * Add an additional filter
+     *
+     * @param FilterInterface $filter
+     *
+     * @return $this
+     *
+     * @throws InvalidFilterException
+     */
+    public function addFilter(FilterInterface $filter): self
+    {
+        // TODO: check accepted types
+        if (!(count($filter->getFilter()) === 2) ||
+            !is_string($filter->getFilter()[0]) ||
+            !is_string($filter->getFilter()[1]) ||
+            !is_callable($filter->getFilter())
+        ) {
+            throw new InvalidFilterException("Invalid filter callback for filter {$filter->getToken()}");
+        }
+
+        $this->filter[$filter->getToken()] = $filter;
+
+        return $this;
+    }
+
+    /**
+     * Get a filter by the given token
+     *
+     * @param string $token
+     *
+     * @return FilterInterface|null
+     */
+    public function getFilter(string $token): ?FilterInterface
+    {
+        return $this->filter[$token] ?? null;
     }
 
     /**

src/Model/Validator/FilterValidator.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\Model\Validator;
+
+use PHPModelGenerator\Exception\SchemaException;
+use PHPModelGenerator\Model\Property\PropertyInterface;
+use PHPModelGenerator\PropertyProcessor\Filter\FilterInterface;
+
+class FilterValidator extends PropertyValidator
+{
+    /**
+     * FilterValidator constructor.
+     *
+     * @param FilterInterface $filter
+     * @param PropertyInterface $property
+     *
+     * @throws SchemaException
+     */
+    public function __construct(FilterInterface $filter, PropertyInterface $property)
+    {
+        if (!empty($filter->getAcceptedTypes()) &&
+            $property->getType() &&
+            !in_array($property->getType(), $filter->getAcceptedTypes())
+        ) {
+            throw new SchemaException(
+                sprintf(
+                    'Filter %s is not compatible with property type %s for property %s',
+                    $filter->getToken(),
+                    $property->getType(),
+                    $property->getName()
+                )
+            );
+        }
+
+        parent::__construct(
+            // check if the given value has a type matched by the filter
+            (!empty($filter->getAcceptedTypes())
+                ? '($value !== null && (!is_' . implode('($value) && !is_', $filter->getAcceptedTypes()) . '($value)))'
+                : ''
+            ) . sprintf(
+                ' || (($value = call_user_func([%s::class, "%s"], $value)) && false)',
+                $filter->getFilter()[0],
+                $filter->getFilter()[1]
+            ),
+            sprintf(
+                'Filter %s is not compatible with property type " . gettype($value) . " for property %s',
+                $filter->getToken(),
+                $property->getName()
+            )
+        );
+    }
+}

src/PropertyProcessor/Filter/FilterInterface.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\PropertyProcessor\Filter;
+
+interface FilterInterface
+{
+    /**
+     * 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. If an empty array is returned the filter
+     * will accept all types.
+     *
+     * @return array
+     */
+    public function getAcceptedTypes(): array;
+
+    /**
+     * Return the token for the filter
+     *
+     * @return string
+     */
+    public function getToken(): string;
+
+    /**
+     * Return the filter to apply. Make sure the returned array is a callable which is also callable after the
+     * render process
+     *
+     * @return array
+     */
+    public function getFilter(): array;
+}

src/PropertyProcessor/Filter/FilterProcessor.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PHPModelGenerator\PropertyProcessor\Filter;
+
+use PHPModelGenerator\Exception\SchemaException;
+use PHPModelGenerator\Model\GeneratorConfiguration;
+use PHPModelGenerator\Model\Property\PropertyInterface;
+use PHPModelGenerator\Model\Validator\FilterValidator;
+
+/**
+ * Class FilterProcessor
+ *
+ * @package PHPModelGenerator\PropertyProcessor\Filter
+ */
+class FilterProcessor
+{
+    /**
+     * @param PropertyInterface $property
+     * @param $filterList
+     * @param GeneratorConfiguration $generatorConfiguration
+     *
+     * @throws SchemaException
+     */
+    public function process(
+        PropertyInterface $property,
+        $filterList,
+        GeneratorConfiguration $generatorConfiguration
+    ): void {
+        if (is_string($filterList)) {
+            $filterList = [$filterList];
+        }
+
+        foreach ($filterList as $filterToken) {
+            if (!($filter = $generatorConfiguration->getFilter($filterToken))) {
+                throw new SchemaException("Unsupported filter $filterToken");
+            }
+
+            $property->addValidator(new FilterValidator($filter, $property), 3);
+        }
+    }
+}