extend custom filter documentation

Author: wol-soft

README.md

@@ -81,6 +81,7 @@ Method | Configuration | Default
 ``` setOutputEnabled(bool $outputEnabled) ``` <br><br>Example:<br> ``` setOutputEnabled(false) ``` | Enable or disable output of the generation process to STDOUT | true
 ``` setErrorRegistryClass(string $exceptionClass) ``` <br><br>Example:<br> ``` setErrorRegistryClass(CustomException::class) ``` | Define a custom exception implementing the ErrorRegistryExceptionInterface to be used. The exception will be thrown if a validation fails and error collection is **enabled** | ErrorRegistryException::class
 ``` setExceptionClass(string $exceptionClass) ``` <br><br>Example:<br> ``` setExceptionClass(CustomException::class) ``` | Define a custom exception to be used. The exception will be thrown if a validation fails and error collection is **disabled** | ValidationException::class
+``` addFilter(FilterInterface $filter) ``` <br><br>Example:<br> ``` addFilter(new CustomFilter()) ``` | Add a custom filter to the generator. Check out the docs for more details. | -
 
 ## Examples ##
 
@@ -127,7 +128,7 @@ Now let's have a look at the behaviour of the generated model:
 ```php
 // Throws an exception as the required name isn't provided.
 // Exception: 'Missing required value for name'
-$person = new Person();
+$person = new Person([]);
 
 // Throws an exception as the name provides an invalid value.
 // Exception: 'Invalid type for name. Requires string, got int'

docs/source/gettingStarted.rst

@@ -87,7 +87,7 @@ Now let's have a look at the behaviour of the generated model:
 
     // Throws an exception as the required name isn't provided.
     // Exception: 'Missing required value for name'
-    $person = new Person();
+    $person = new Person([]);
 
     // Throws an exception as the name provides an invalid value.
     // Exception: 'Invalid type for name. Requires string, got int'
@@ -236,3 +236,12 @@ The output of a generation process may look like:
     Duplicated signature 444fd086d8d1f186145a6f81a3ac3f7a for class Register_Message. Redirecting to Login_Message
     Rendered class MyApp\User\Response\Login
     Rendered class MyApp\User\Response\Register
+
+Custom filter
+^^^^^^^^^^^^^
+
+.. code-block:: php
+
+    addFilter(FilterInterface $customFilter);
+
+Add a custom filter to the generator. For more details see `Filter <nonStandardExtensions/filter.html>`__.

docs/source/nonStandardExtensions/filter.rst

@@ -2,7 +2,7 @@ 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:
+Filters can be either supplied as a string or as a list of filters (multiple filters can be applied to a single property):
 
 .. code-block:: json
 
@@ -40,7 +40,7 @@ The trim filter is only valid for string properties.
             "name": {
                 "type": "string",
                 "filter": "trim",
-                "minLength": 2,
+                "minLength": 2
             }
         }
     }
@@ -50,7 +50,7 @@ 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();
+    $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'
@@ -73,7 +73,7 @@ If the filter trim is used for a property which doesn't require a string value a
 Custom filter
 -------------
 
-You can implement custom filter and use them in your schema files. You must add your custom filter to the generator configuration.
+You can implement custom filter and use them in your schema files. You must add your custom filter to the generator configuration to make them available.
 
 .. code-block:: php
 
@@ -83,3 +83,58 @@ You can implement custom filter and use them in your schema files. You must add
     );
 
 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.
+The callable filter method must be a static method. Internally it will be called via *call_user_func*. A custom filter may look like:
+
+.. code-block:: php
+
+    namespace MyApp\Model\Generator\Filter;
+
+    use PHPModelGenerator\PropertyProcessor\Filter\FilterInterface;
+
+    class UppercaseFilter implements FilterInterface
+    {
+        public static function uppercase(?string $value): ?string
+        {
+            // we want to handle strings and null values with this filter
+            return $value !== null ? strtoupper($value) : null;
+        }
+
+        public function getAcceptedTypes(): array
+        {
+            return ['string'];
+        }
+
+        public function getToken(): string
+        {
+            return 'uppercase';
+        }
+
+        public function getFilter(): array
+        {
+            return [self::class, 'uppercase'];
+        }
+    }
+
+If the custom filter is added to the generator configuration you can now use the filter in your schema and the generator will resolve the function:
+
+
+.. code-block:: json
+
+    {
+        "$id": "person",
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "filter": [
+                    "uppercase",
+                    "trim"
+                ]
+            }
+        }
+    }
+
+.. code-block:: php
+
+    $person = new Person(['name' => '   Albert ']);
+    $person->getName(); // returns 'ALBERT'