Update documentation

Author: Seif Kamal

README.md

@@ -12,12 +12,26 @@ dumb for the task at hand, requiring several unpleasant control structures to va
 Moreover, creating a dedicated DTO class (or more) might be overkill, requiring a lot of boilerplate
 code, whilst making things like error messaging and future refactoring more difficult.
 
-In cases like this I find myself itching for a Go/Rust like `Struct` instead.
+In cases like this I find myself itching for a Go/Rust like `struct` instead.
 
 See [doc](docs/use-case.md) for a more in depth discussion.
 
 ## Usage
 
+To define and validate an array data structure, first create a `Struct` - this requires a
+`name`, used for error messaging, and an `interface` - then use the provided `Validator`
+function to validate the data against the defined `Struct`.
+
+A `Struct`'s `interface` ia an array consisting of string keys (matching the expected property names)
+and callable values. These values can be any callable PHP entity, and is expected to accept
+a single mixed type `$value`, and return a `bool`. Some valid examples are:
+- `is_*` [variable handling functions](https://www.php.net/manual/en/ref.var.php) (`is_string`,
+`is_int`, `is_callable` etc.)
+- A `Closure` (`function ($value): bool {}`)
+- A class with an `__invoke($value): bool` method
+
+### Example
+
 Here's an example written using the provided convenient helper functions:
 
 ```php
@@ -104,4 +118,4 @@ echo "File: {$directory['file']}" . PHP_EOL;
 // File: /Users/seifkamal/src/struct-array/examples/directory-validation.php
 ```
 
-For more detailed ones, see the [examples directory](examples).
+For more, see the [examples directory](examples).

docs/use-case.md

@@ -10,14 +10,14 @@ optional, and returns aggregated statistics.
 
 ## Scenario
 
-Let's say your controller endpoint expects a `$filterParams` array with:
+Let's say your controller endpoint expects a `$filterParams` array containing some event data:
 
 - `name string`
+- `category string` (one of 'theatre', 'concert', or 'sport')
 - `date DateTime` (optional - defaults today's date)
 - `priceRange array`
   - `from float`
   - `to float`
-- `tags array<string>` (optional - defaults to empty array)
 
 ```php
 <?php
@@ -49,6 +49,12 @@ class StatsController {
             throw new InvalidArgumentException("'name' param must be string");
         }
 
+        // Validate `category`
+        $categories = ['theatre', 'concert', 'sport'];
+        if (!isset($filterParams['category']) || !in_array($filterParams['category'], $categories)) {
+            throw new InvalidArgumentException("'category' param must be one of: " . implode(', ', $categories));
+        }
+
         // Validate `date`
         if (!!isset($filterParams['date'])) {
             $filterParams['date'] =  new DateTime();
@@ -67,15 +73,6 @@ class StatsController {
             throw new InvalidArgumentException("Price range 'to' param must be a float");
         }
 
-        // Validate `tags`
-        if (!array_key_exists('tags', $filterParams)) {
-            $filterParams['tags'] = [];
-        } elseif (!is_array($filterParams['tags'])) {
-            throw new InvalidArgumentException("'tags' param must be an array of strings");
-        } else {
-            $filterParams['tags'] = array_filter($filterParams['tags'], 'is_string');
-        }
-
         return DB::action($filterParams);
     }
 }
@@ -117,36 +114,41 @@ class Price {
     // + necessary accessors
 }
 
-// Filter.php
-class Filter {
+// Event.php
+class Event {
+    const CATEGORIES = ['theatre', 'concert', 'sport'];
+
     /** @var string */
     private $name;
+    /** @var string */
+    private $category;
     /** @var DateTime */
     private $date;
     /** @var Price */
     private $priceRange;
-    /** @var string[] */
-    private $tags;
 
     public function __construct(
         string $name,
+        string $category,
         DateTime $date,
-        Price $priceRange,
-        array $tags
+        Price $priceRange
     ) {
         $this->name = $name;
+        if (!in_array($category, self::CATEGORIES)) {
+            throw new InvalidArgumentException("'category' param must be one of: " . implode(', ', self::CATEGORIES);
+        }
+        $this->category = $category;
         $this->date = $date;
         $this->priceRange = $priceRange;
-        $this->tags = array_filter($tags, 'is_string');
     }
 
     public static function from(array $params): self
     {
         return new static(
             $params['name'],
+            $params['category'],
             $params['date'] ?? new DateTime(),
-            new Price($params['priceRange']['from'], $params['priceRange']['to']),
-            $params['tags'] ?? []
+            new Price($params['priceRange']['from'], $params['priceRange']['to'])
         );
     }
 
@@ -162,7 +164,7 @@ class Filter {
 class StatsController {
     public function index(array $filterParams)
     {
-        return DB::action(Filter::from($filterParams)->toArray());
+        return DB::action(Event::from($filterParams)->toArray());
     }
 }
 ```
@@ -183,22 +185,24 @@ required, and may even have an impact on performance
 ```php
 <?php
 
+// StatsController.php
 use function \SK\StructArray\{
-    arrayOf, classOf, optional, struct, validate
+    classOf, optional, struct, validate
 };
 
-// StatsController.php
 class StatsController {
     public function index(array $filterParams)
     {
-        validate($filterParams, struct('Filter', [
+        validate($filterParams, struct('Event', [
             'name' => 'is_string',
+            'category' => function (string $value): bool {
+                return in_array($value, ['theatre', 'concert', 'sport']);
+            },
             'date' => optional(classOf(DateTime::class), new DateTime()),
             'priceRange' => struct('Price', [
                 'from' => 'is_float',
                 'to' => 'is_float',
             ]),
-            'tags' => arrayOf('is_string'),
         ]));
 
         return DB::action($filterParams);
@@ -209,11 +213,11 @@ class StatsController {
 **Pros:**
 - Easy to read
 - Easy to scale
-- Automatic, meaningful error messaging; Here's an example:
-> Struct 'Filter' failed validation: Invalid value for property 'date'
+- Automatic, customisable error messaging; Here's an example:
+> Struct '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 use `callable`s (and other `Struct`s) for validation, so it can easily be
-worked into an existing system or customised accordingly
+- 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
 
 **Cons:**
 - ???

examples/basic.php

@@ -6,12 +6,12 @@
 use SK\StructArray\Exception\StructValidationException;
 
 use function SK\StructArray\{
-    allOf, anyOf, arrayOf, classOf, not, struct, validate
+    allOf, anyOf, arrayOf, classOf, not, optional, struct, validate
 };
 
 $eventStruct = struct('Event', [
     'id' => allOf('is_string', 'is_numeric'),
-    'type' => 'is_string',
+    'type' => optional('is_string', 'general'),
     'date' => anyOf(classOf(DateTime::class), 'is_null'),
     'priceFrom' => 'is_float',
     'tickets' => arrayOf(not('is_null')),
@@ -53,7 +53,6 @@
     ],
     [
         'id' => '123',
-        'type' => null,
         'date' => new DateTime(),
         'priceFrom' => 20.5,
         'tickets' => ['General', null],

examples/custom.php renamed to examples/custom-error.php

@@ -9,14 +9,18 @@
 
 $message = [
     'subject' => 'Greetings',
-    'body' => 'hi',
+    'body' => 'yo',
 ];
 
 try {
     validate($message, struct('Message', [
         'subject' => 'is_string',
         'body' => function ($value): bool {
-            return in_array($value, ['hello', 'hi', 'hey']);
+            $greetings = ['hello', 'hi', 'hey'];
+            if (!in_array($value, $greetings)) {
+                throw new InvalidArgumentException('Greeting body must be one of: ' . implode(', ', $greetings));
+            }
+            return true;
         },
     ]));
 } catch (StructValidationException $e) {

examples/directory-validation.php

@@ -3,12 +3,8 @@
 namespace SK\StructArray\Property;
 
 /**
- * Class Missing
- *
- * This class is used to represent a property that is missing from the
- * data structure.
- *
- * @package SK\StructArray\Property
+ * @internal This class is used to represent a property that is missing
+ * from the data structure.
  */
 class Missing
 {

examples/nested.php

@@ -8,12 +8,8 @@
 use function SK\StructArray\validate;
 
 /**
- * Class Type
- *
  * Contains static methods that return validator functions; Each said function
  * takes in a $value parameter, validates it, and returns a boolean value.
- *
- * @package SK\StructArray\Property
  */
 class Type
 {

examples/optional.php

@@ -16,7 +16,9 @@ class Struct
      *
      * @param string $name
      * @param callable|Struct[] $interface
-     * @param bool $exhaustive
+     * @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
      */
     public static function of(string $name, array $interface, bool $exhaustive = true): self