Add tests and documentation for format validators

Author: wol-soft

composer.json

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

docs/source/types/string.rst

@@ -78,7 +78,7 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\String\\MinLengthE
 Pattern validation
 ------------------
 
-To add a pattern validation to the property use `pattern` keyword.
+To add a pattern validation to the property use the `pattern` keyword.
 
 .. warning::
 
@@ -115,4 +115,66 @@ The thrown exception will be a *PHPModelGenerator\\Exception\\String\\PatternExc
 Format
 ------
 
-String formats are currently not supported.
+To add a format validation to the property use the `format` keyword.
+
+.. code-block:: json
+
+    {
+        "$id": "example",
+        "type": "object",
+        "properties": {
+            "example": {
+                "type": "string",
+                "format": "myFormat"
+            }
+        }
+    }
+
+Possible exceptions:
+
+* Value for property must match the format __FORMAT__
+
+The thrown exception will be a *PHPModelGenerator\\Exception\\String\\FormatException* which provides the following methods to get further error details:
+
+.. code-block:: php
+
+    // get the expected format
+    public function getExpectedFormat(): string
+    // get the name of the property which failed
+    public function getPropertyName(): string
+    // get the value provided to the property
+    public function getProvidedValue()
+
+Builtin formats
+^^^^^^^^^^^^^^^
+
+Currently no builtin formats are available.
+
+Custom formats
+^^^^^^^^^^^^^^
+
+You can implement custom format validators and use them in your schema files. You must add your custom format to the generator configuration to make them available.
+
+.. code-block:: php
+
+    $generator = new Generator(
+        (new GeneratorConfiguration())
+            ->addFormat(new MyCustomFormat())
+    );
+
+Your format validator must implement the interface **PHPModelGenerator\\Format\\FormatValidatorInterface**.
+
+If your custom format is representable by a regular expression you can bypass implementing an own class and simply add a **FormatValidatorFromRegEx** (for example a string which must contain only numbers):
+
+.. code-block:: php
+
+    $generator = new Generator(
+        (new GeneratorConfiguration())
+            ->addFormat(new FormatValidatorFromRegEx('/^\d*$/'))
+    );
+
+.. hint::
+
+    Pull requests for common usable format validators are always welcome.
+    A new format validator must be added in the *GeneratorConfiguration* method *initFormatValidator*.
+    If the format validator requires a class implementation and can't be added via the *FormatValidatorFromRegEx* the class must be added to the *wol-soft/php-json-schema-model-generator-production* repository.

tests/Objects/StringPropertyTest.php

@@ -2,9 +2,11 @@
 
 namespace PHPModelGenerator\Tests\Objects;
 
+use PHPModelGenerator\Exception\ErrorRegistryException;
 use PHPModelGenerator\Exception\FileSystemException;
 use PHPModelGenerator\Exception\RenderException;
 use PHPModelGenerator\Exception\SchemaException;
+use PHPModelGenerator\Format\FormatValidatorFromRegEx;
 use PHPModelGenerator\Model\GeneratorConfiguration;
 use PHPModelGenerator\Tests\AbstractPHPModelGeneratorTest;
 use stdClass;
@@ -249,11 +251,50 @@ public function invalidPatternProvider(): array
         );
     }
 
-    public function testStringFormatCheckThrowsNotSupportedException(): void
+    public function testUnknownFormatThrowsAnException(): void
     {
         $this->expectException(SchemaException::class);
-        $this->expectExceptionMessage('Format is currently not supported');
+        $this->expectExceptionMessage('Unsupported format onyNumbers');
 
         $this->generateClassFromFile('StringPropertyFormat.json');
     }
+
+    public function testStringFormatCheckIsValid(): void
+    {
+        $className = $this->generateClassFromFile(
+            'StringPropertyFormat.json',
+            (new GeneratorConfiguration())->addFormat('onyNumbers', new FormatValidatorFromRegEx('/^\d+$/'))
+        );
+
+        $object = new $className(['property' => '12345']);
+        $this->assertSame('12345', $object->getProperty());
+    }
+
+    /**
+     * @dataProvider invalidStringFormatDataProvider
+     *
+     * @param string $value
+     */
+    public function testInvalidStringFormatCheck(string $value): void
+    {
+        $this->expectException(ErrorRegistryException::class);
+        $this->expectExceptionMessage('Value for property must match the format onyNumbers');
+
+        $className = $this->generateClassFromFile(
+            'StringPropertyFormat.json',
+            (new GeneratorConfiguration())->addFormat('onyNumbers', new FormatValidatorFromRegEx('/^\d+$/'))
+        );
+
+        new $className(['property' => $value]);
+    }
+
+    public function invalidStringFormatDataProvider(): array
+    {
+        return [
+            'empty string' => [''],
+            'spaces' => ['    '],
+            'only non numeric chars' => ['abc'],
+            'mixed string' => ['1234a'],
+        ];
+    }
 }

tests/Schema/StringPropertyTest/StringPropertyFormat.json

@@ -3,7 +3,7 @@
   "properties": {
     "property": {
       "type": "string",
-      "format": "email"
+      "format": "onyNumbers"
     }
   }
 }