Merge pull request #1 from safe-k/feature/implicit-struct

Support implicit struct array validation

Author: seifkamal

README.md

@@ -61,7 +61,7 @@ $directory = [
 try {
     validate($directory, struct('Directory', [
          'path' => 'is_dir',
-         'file' => optional('is_file', __DIR__ . '/directory-validation.php'),
+         'file' => optional('is_file', __DIR__ . '/README.md'),
          'content' => arrayOf(struct('Paragraph', [
              'header' => 'is_string',
              'line' => not('is_null'),
@@ -75,11 +75,40 @@ try {
 echo "Path: {$directory['path']}" . PHP_EOL;
 echo "File: {$directory['file']}" . PHP_EOL;
 // Prints:
-// Path: /Users/seifkamal/src/struct-array/examples
-// File: /Users/seifkamal/src/struct-array/examples/directory-validation.php
+// Path: /Users/seifkamal/src/struct-array
+// File: /Users/seifkamal/src/struct-array/README.md
 ```
 
-Here's the same one using static class methods:
+You can also just use an array directly, without creating a `Struct`:
+
+```php
+<?php
+
+use function SK\StructArray\{
+    arrayOf, optional, not, validate
+};
+
+$directory = [...];
+
+validate($directory, [
+    'path' => 'is_dir',
+    'file' => optional('is_file', __DIR__ . '/README.md'),
+    'content' => arrayOf([
+        'header' => 'is_string',
+        'line' => not('is_null'),
+    ]),
+]);
+```
+
+This is tailored for quick usage, and therefore assumes the defined interface is non-exhaustive
+(ie. the array submitted for validation is allowed to have keys that aren't defined here). It also
+means error messages will be more generic, ie you'll see:
+> Struct failed validation. ...
+
+instead of:
+> Directory failed validation. ...
+
+Here's another example directly using the static class methods:
 
 ```php
 <?php
@@ -105,7 +134,7 @@ $paragraphStruct = Struct::of('Paragraph', [
 ]);
 $directoryStruct = Struct::of('Directory', [
      'path' => 'is_dir',
-     'file' => Type::optional('is_file', __DIR__ . '/directory-validation.php'),
+     'file' => Type::optional('is_file', __DIR__ . '/README.md'),
      'content' => Type::arrayOf($paragraphStruct),
 ]);
 
@@ -119,8 +148,8 @@ try {
 echo "Path: {$directory['path']}" . PHP_EOL;
 echo "File: {$directory['file']}" . PHP_EOL;
 // Prints:
-// Path: /Users/seifkamal/src/struct-array/examples
-// File: /Users/seifkamal/src/struct-array/examples/directory-validation.php
+// Path: /Users/seifkamal/src/struct-array
+// File: /Users/seifkamal/src/struct-array/README.md
 ```
 
 For more, see the [examples directory](examples).

docs/use-case.md

@@ -214,7 +214,7 @@ class StatsController {
 - Easy to read
 - Easy to scale
 - Automatic, customisable error messaging; Here's an example:
-> Struct 'Event' failed validation: Invalid value for property 'date'
+> Event failed validation. Invalid value for property: 'date'
 - All possible parameters and their validation rules are documented in code, in the method itself
 - Extensible - `Struct`s are essentially arrays of `callable`s (and other `Struct`s), so they can
 easily be worked into systems and be extended accordingly

src/Exception/InvalidValueException.php

@@ -6,6 +6,6 @@ class InvalidValueException extends \Exception
 {
     public function __construct(string $property)
     {
-        parent::__construct("Invalid value for property '{$property}'");
+        parent::__construct("Invalid value for property: '{$property}'");
     }
 }

src/Exception/MissingPropertyException.php

@@ -6,6 +6,6 @@ class MissingPropertyException extends \Exception
 {
     public function __construct(string $property)
     {
-        parent::__construct("missing value for '{$property}'");
+        parent::__construct("Missing value for property: '{$property}'");
     }
 }

src/Exception/StructValidationException.php

@@ -9,7 +9,7 @@ class StructValidationException extends \Exception
     public function __construct(Struct $struct, \Throwable $reason)
     {
         parent::__construct(
-            "Struct '{$struct->name()}' failed validation: {$reason->getMessage()}",
+            "{$struct->name()} failed validation. {$reason->getMessage()}",
             0,
             $reason
         );

src/Exception/UnexpectedPropertyException.php

@@ -7,7 +7,7 @@ class UnexpectedPropertyException extends \Exception
     public function __construct(string ...$properties)
     {
         parent::__construct(sprintf(
-            "Unexpected %s '%s'",
+            "Unexpected %s: '%s'",
             count($properties) === 1 ? 'property' : 'properties',
             implode(', ', $properties)
         ));

src/Struct.php

@@ -6,16 +6,16 @@ class Struct
 {
     /** @var string */
     private $name;
-    /** @var callable|Struct[] */
+    /** @var callable[]|Struct[] */
     private $interface;
     /** @var bool */
     private $exhaustive;
 
     /**
      * Struct constructor.
      *
-     * @param string $name
-     * @param callable|Struct[] $interface
+     * @param string $name Used in error messaging, useful when nesting or validating multiple Structs.
+     * @param callable[]|Struct[] $interface A list of expected keys and their associated validator.
      * @param bool $exhaustive Used to specify whether the declared Struct properties are exhaustive,
      * meaning data arrays submitted for validation must not contain unknown keys. This defaults
      * to `true`; Set to `false` if you only want to validate some of the array elements.
@@ -33,13 +33,24 @@ public static function of(
         return $struct;
     }
 
+    /**
+     * @internal
+     *
+     * @param array $interface
+     * @return static
+     */
+    public static function default(array $interface): self
+    {
+        return static::of('Struct', $interface, false);
+    }
+
     public function name(): string
     {
         return $this->name;
     }
 
     /**
-     * @return callable|Struct[]
+     * @return callable[]|Struct[]
      */
     public function interface(): array
     {

src/Validator.php

@@ -8,13 +8,17 @@ class Validator
 {
     /**
      * @param array $data
-     * @param Struct $struct
+     * @param array|Struct $struct If an array is supplied, a generic, non-exhaustive Struct is used.
      * @return bool
      * @throws Exception\StructValidationException
      */
-    public static function validate(array &$data, Struct $struct): bool
+    public static function validate(array &$data, $struct): bool
     {
         try {
+            if (is_array($struct)) {
+                $struct = Struct::default($struct);
+            }
+
             $unexpectedProperties = array_diff_key($data, $struct->interface());
             if ($struct->isExhaustive() && !empty($unexpectedProperties)) {
                 throw new Exception\UnexpectedPropertyException(...array_keys($unexpectedProperties));
@@ -24,26 +28,34 @@ public static function validate(array &$data, Struct $struct): bool
                 $value = array_key_exists($field, $data)
                     ? $data[$field]
                     : Missing::property($field);
-                $valueIsMissing = is_a($value, Missing::class);
+                $propertyIsMissing = is_a($value, Missing::class);
 
                 if (is_callable($validator)) {
                     if (!$validator($value)) {
                         throw new Exception\InvalidValueException($field);
                     }
                     // If value has changed, set corresponding data field
-                    if ($valueIsMissing && !is_a($value, Missing::class)) {
+                    if ($propertyIsMissing && !is_a($value, Missing::class)) {
                         $data[$field] = $value;
                     }
-                } elseif (is_a($validator, Struct::class)) {
-                    if ($valueIsMissing) {
-                        throw new Exception\MissingPropertyException($field);
-                    }
+                    return true;
+                }
+
+                if ($propertyIsMissing) {
+                    throw new Exception\MissingPropertyException($field);
+                }
+
+                if (is_array($validator)) {
+                    $validator = Struct::default($validator);
+                }
+                if (is_a($validator, Struct::class)) {
                     if (!validate($value, $validator)) {
                         throw new Exception\InvalidValueException($field);
                     }
-                } else {
-                    throw new Exception\InvalidValidatorException($validator);
+                    return true;
                 }
+
+                throw new Exception\InvalidValidatorException($validator);
             }
         } catch (\Throwable $t) {
             /**

src/functions.php

@@ -75,9 +75,11 @@ function optional(callable $validator, $default = Missing::class): callable
 /**
  * @see Struct::of()
  *
- * @param string $name
- * @param callable|Struct[] $interface
- * @param bool $exhaustive
+ * @param string $name Used in error messaging, useful when nesting or validating multiple Structs.
+ * @param callable[]|Struct[] $interface A list of expected keys and their associated validator.
+ * @param bool $exhaustive Used to specify whether the declared Struct properties are exhaustive,
+ * meaning data arrays submitted for validation must not contain unknown keys. This defaults
+ * to `true`; Set to `false` if you only want to validate some of the array elements.
  * @return Struct
  */
 function struct(string $name, array $interface, bool $exhaustive = true): Struct
@@ -89,11 +91,11 @@ function struct(string $name, array $interface, bool $exhaustive = true): Struct
  * @see Validator::validate()
  *
  * @param array $data
- * @param Struct $struct
+ * @param array|Struct $struct If an array is supplied, a generic, non-exhaustive Struct is used.
  * @return bool
  * @throws Exception\StructValidationException
  */
-function validate(array &$data, Struct $struct): bool
+function validate(array &$data, $struct): bool
 {
     return Validator::validate($data, $struct);
 }

tests/Unit/StructTest.php

@@ -3,7 +3,6 @@
 namespace SK\StructArray\Test\Unit;
 
 use PHPUnit\Framework\TestCase;
-use SK\StructArray\Exception;
 use SK\StructArray\Exception\StructValidationException;
 use SK\StructArray\Property\Type;
 use SK\StructArray\Struct;
@@ -15,42 +14,64 @@ class StructTest extends TestCase
     /**
      * @dataProvider dataProviderForTest
      */
-    public function test($data, $interface, $exhaustive, $expectedException)
+    public function test($data, $struct, $expectedException)
     {
         if ($expectedException) {
             $this->expectException(StructValidationException::class);
         }
 
-        $this->assertTrue(validate($data, Struct::of('Test', $interface, $exhaustive)));
+        $this->assertTrue(validate($data, $struct));
     }
 
     public function dataProviderForTest(): array
     {
+        $name = 'Test';
         return [
             [
                 ['name' => 'toasty',],
-                ['name' => 'invalid validator'],
-                true,
+                Struct::of($name, ['name' => 'invalid validator'], true),
                 true,
             ],
             [
                 ['name' => 10],
-                ['name' => 'is_string'],
-                true,
+                Struct::of($name, ['name' => 'is_string'], true),
                 true,
             ],
             [
                 [],
-                ['name' => 'is_string'],
-                true,
+                Struct::of($name, ['name' => 'is_string'], true),
                 true,
             ],
             [
                 ['name' => 'toasty', 'age' => 10],
-                ['name' => 'is_string'],
-                true,
+                Struct::of($name, ['name' => 'is_string'], true),
                 true,
             ],
+            [
+                [
+                    'id' => '123',
+                    'type' => 'theatre',
+                    'date' => new \DateTime(),
+                    'price' => [
+                        'value' => 20.5,
+                        'currency' => 'GBP',
+                    ],
+                    'tickets' => ['General', 10],
+                    'onSale' => true,
+                    'artist' => 'some guy',
+                ],
+                Struct::of($name, [
+                    'id' => Type::allOf('is_string', 'is_numeric'),
+                    'type' => 'is_string',
+                    'date' => Type::anyOf(Type::classOf(\DateTime::class), 'is_null'),
+                    'price' => Struct::of('Price', [
+                        'value' => 'is_float',
+                        'currency' => 'is_string'
+                    ]),
+                    'tickets' => Type::arrayOf(Type::not('is_null')),
+                ], false),
+                null
+            ],
             [
                 [
                     'id' => '123',
@@ -74,7 +95,6 @@ public function dataProviderForTest(): array
                     ]),
                     'tickets' => Type::arrayOf(Type::not('is_null')),
                 ],
-                false,
                 null
             ],
         ];