Initial commit

Author: Seif Kamal

.gitattributes

@@ -0,0 +1,7 @@
+# .gitattributes
+docs/ export-ignore
+examples/ export-ignore
+tests/ export-ignore
+
+# Auto detect text files and perform LF normalization
+* text=auto

.gitignore

@@ -0,0 +1,3 @@
+.idea
+vendor
+composer.lock

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Seif Kamal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,106 @@
+![GitHub license](https://img.shields.io/github/license/safe-k/struct-array)
+
+# PHP Structured Arrays
+
+Make PHP array data validation easier and clearer by defining array structures.
+
+## Why
+
+We often need to receive, validate, and process data objects. Sometimes, an array might be too
+dumb for the task at hand, requiring several unpleasant control structures to validate and setup.
+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.
+
+See [doc](docs/use-case.md) for a more in depth discussion.
+
+## Usage
+
+Here's an example written using the provided convenient helper functions:
+
+```php
+<?php
+
+use SK\StructArray\Exception\StructValidationException;
+
+use function SK\StructArray\{
+    arrayOf, optional, not, struct, validate
+};
+
+$directory = [
+    'path' => __DIR__,
+    'content' => [
+        [
+            'header' => 'Greeting',
+            'line' => 'Hello',
+        ],
+    ]
+];
+
+try {
+    validate($directory, struct('Directory', [
+         'path' => 'is_dir',
+         'file' => optional('is_file', __DIR__ . '/directory-validation.php'),
+         'content' => arrayOf(struct('Paragraph', [
+             'header' => 'is_string',
+             'line' => not('is_null'),
+         ])),
+     ]));
+} catch (StructValidationException $e) {
+    echo $e->getMessage() . PHP_EOL;
+    return;
+}
+
+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
+```
+
+Here's the same one using static class methods:
+
+```php
+<?php
+
+use SK\StructArray\Exception\StructValidationException;
+use SK\StructArray\Property\Type;
+use SK\StructArray\Struct;
+use SK\StructArray\Validator;
+
+$directory = [
+    'path' => __DIR__,
+    'content' => [
+        [
+            'header' => 'Greeting',
+            'line' => 'Hello',
+        ],
+    ]
+];
+
+$paragraphStruct = Struct::of('Paragraph', [
+     'header' => 'is_string',
+     'line' => Type::not('is_null'),
+]);
+$directoryStruct = Struct::of('Directory', [
+     'path' => 'is_dir',
+     'file' => Type::optional('is_file', __DIR__ . '/directory-validation.php'),
+     'content' => Type::arrayOf($paragraphStruct),
+]);
+
+try {
+    Validator::validate($directory, $directoryStruct);
+} catch (StructValidationException $e) {
+    echo $e->getMessage() . PHP_EOL;
+    return;
+}
+
+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
+```
+
+For more detailed ones, see the [examples directory](examples).

composer.json

@@ -0,0 +1,42 @@
+{
+  "name": "safe-k/struct-array",
+  "type": "library",
+  "description": "Array structure validation",
+  "keywords": [
+    "data",
+    "array",
+    "structure",
+    "validation",
+    "dto",
+    "ddd"
+  ],
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Seif Kamal",
+      "email": "[email protected]"
+    }
+  ],
+  "require": {
+    "php": ">=7.0.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^9.1"
+  },
+  "autoload": {
+    "psr-4": {
+      "SK\\StructArray\\": "src"
+    },
+    "files": [
+      "src/functions.php"
+    ]
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "SK\\StructArray\\Test\\": "tests"
+    }
+  },
+  "scripts": {
+    "test": "phpunit tests"
+  }
+}