Bring FileNode to 1.x (#9)

* [fix] Split test-related namespace to autoload-dev stanza

* README updates

* [Feature] Implement `FileNode` (#8)

* Support `Stringable` as rule entries
* Implement `FileNode`
* Docs for `FileNode`

* PHPStan fix

Author: bezhermoso

docs/file-upload-validation-images.md

@@ -0,0 +1,37 @@
+## File Upload Validation - Images
+
+Here are a few examples for how you can validate image uploads.
+
+### Validate dimensions
+
+```php
+
+$builder = Hyrule::create()
+    ->file('avatar')
+        ->required()
+        ->image()   // Validates that upload is an image.
+        ->dimensions()  // Starts dimension constraints...
+            ->ratio(1)
+            ->maxWidth(1000)
+            ->end() // Ends dimension rule-set.
+        ->end() // Ends the "avatar" field.
+    // ... 
+
+```
+
+See [`Dimensions`](https://github.com/laravel/framework/blob/9.x/src/Illuminate/Validation/Rules/Dimensions.php) class for all available constraints.
+
+### Only accept subset of image types
+
+```php
+$builder = Hyrule::create()
+    ->file('avatar')
+        ->required()
+        ->mimeType() // Starts MIME-type constriants...
+            ->image('jpeg', 'gif', 'png') // Only accept image/{jpeg,gif,png}
+            ->end() // End MIME-Type constraints.
+        ->end() // End the "avatar" field.
+    // ... 
+```
+
+See [File Upload Validation - MIME Types](./file-upload-validation-mime-types.md) for a comprehensive guide on MIME-Type rules.

docs/file-upload-validation-mime-types.md

@@ -0,0 +1,41 @@
+## File Upload Validation - MIME Types
+
+It is considered best practice to validate the MIME type of uploaded files. Here are a few examples on how to do that with Hyrule:
+
+```php
+$builder = Hyrule::create()
+    ->file('attachment')
+        ->mimeType() // Starts MIME-Type contraints
+            /*
+             * All 5 top-level MIME type categories are supported
+             */
+            ->application('pdf') // Allows application/pdf
+            ->image('jpg', 'png', ...) // Variadic. Enumerate sub-types e.g. image/jpeg, image/png, etc.
+            ->video('mp4', 'webm')
+            ->multipart(...)
+            ->message(...)
+            ->end() // Ends MIME Type constraint.
+        ->end() // Ends "attachment" field
+        // ...
+```
+
+Use `->allow(...)` to enumerate specific specific MIME-types:
+
+```php
+$builder = Hyrule::create()
+    ->array('attachments')
+        ->between(1, 10)
+        ->each('file')
+            ->mimeType()
+                ->allow('application/pdf')
+                ->allow('image/jpg')
+                ->allow('image/png')
+                ->allow('image/svg')
+                ->allow('video/mp4')
+                // etc.
+                ->end()
+            ->end()
+        ->end()
+    // ...
+
+```

src/Nodes/AbstractNode.php

@@ -166,9 +166,9 @@ public function requiredWith($path): self
      */
     public function rule($rule): self
     {
-        if (!is_string($rule) && !$rule instanceof Rule) {
+        if (!is_string($rule) && !$rule instanceof Rule && !method_exists($rule, '__toString')) {
             throw new InvalidArgumentException(sprintf(
-                'Expected argument to be a string, or instance of %s.', Rule::class,
+                'Expected argument to be a string, instance of %s, or has a __toString() method.', Rule::class,
             ));
         }
         $this->rules[] = $rule;
@@ -234,6 +234,8 @@ public function build(): array
                 $rule = (string) $rule->setNode($this)->stringify();
             } else if ($rule instanceof self) {
                 $rule = (string) (new Path($rule))->pathName();
+            } else if (method_exists($rule, '__toString')) {
+                $rule = (string) $rule;
             }
             return $rule;
         }, $this->rules);

src/Nodes/ArrayNode.php

@@ -9,9 +9,6 @@
 use InvalidArgumentException;
 use LogicException;
 
-/**
- * @property bool $allowUnknownProperties
- */
 class ArrayNode extends CompoundNode
 {
     /**
@@ -31,6 +28,7 @@ class ArrayNode extends CompoundNode
         'array' => ArrayNode::class,
         'object' => ObjectNode::class,
         'scalar' => ScalarNode::class,
+        'file' => FileNode::class,
     ];
 
     /**
@@ -45,7 +43,7 @@ public function __construct(string $name, ?CompoundNode $parent = null)
 
     /**
      * @param string $type
-     * @return AbstractNode|ArrayNode|ObjectNode
+     * @return AbstractNode|ArrayNode|ObjectNode|FileNode
      */
     public function each(string $type): AbstractNode
     {

src/Nodes/FileNode.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Square\Hyrule\Nodes;
+
+use Square\Hyrule\Rules\Dimensions;
+use Square\Hyrule\Rules\MIMEType;
+
+class FileNode extends AbstractNode
+{
+    protected ?Dimensions $dimensions;
+
+    protected ?MIMEType $mimeType;
+
+    /**
+     * @return Dimensions
+     */
+    public function dimensions(): Dimensions
+    {
+        if (!isset($this->dimensions)) {
+            // Create a new Dimensions rule object, push it to the rules array, and
+            // keep a reference so we can modify it when we need to in the future.
+            $this->rule($this->dimensions = new Dimensions($this));
+        }
+        return $this->dimensions;
+    }
+
+    /**
+     * @return $this
+     */
+    public function image(): FileNode
+    {
+        $this->rule('image');
+        return $this;
+    }
+
+    /**
+     * @return MIMEType
+     */
+    public function mimeType(): MIMEType
+    {
+        if (!isset($this->mimeType)) {
+            // Create a new MIMEType rule object, push it to the rules array, and
+            // keep a reference so we can modify it when we need to in the future.
+            $this->rule($this->mimeType = new MIMEType($this));
+        }
+        return $this->mimeType;
+    }
+}

src/Nodes/ObjectNode.php

@@ -88,6 +88,15 @@ public function array(string $name): ArrayNode
         return $this->registerNode(new ArrayNode($name, $this));
     }
 
+    /**
+     * @param string $name
+     * @return FileNode
+     */
+    public function file(string $name): FileNode
+    {
+        return $this->registerNode(new FileNode($name, $this));
+    }
+
     /**
      * @param string $name
      * @return ObjectNode
@@ -195,6 +204,18 @@ public function arrayWith(string $name, callable $callable): self
         return $this;
     }
 
+    /**
+     * @param string $name
+     * @param callable $callable
+     * @return $this
+     */
+    public function fileWith(string $name, callable $callable): self
+    {
+        $this->registerNode(new FileNode($name, $this))
+            ->with($callable);
+        return $this;
+    }
+
     /**
      * @param string $name
      * @param callable $callable

src/PHPStan/ArrayNodeEachDynamicReturnExtension.php

@@ -13,6 +13,7 @@
 use PHPStan\Type\Type;
 use Square\Hyrule\Nodes\ArrayNode;
 use Square\Hyrule\Nodes\BooleanNode;
+use Square\Hyrule\Nodes\FileNode;
 use Square\Hyrule\Nodes\FloatNode;
 use Square\Hyrule\Nodes\IntegerNode;
 use Square\Hyrule\Nodes\NumericNode;
@@ -65,6 +66,8 @@ public function getTypeFromMethodCall(MethodReflection $methodReflection, Method
                 return new ObjectType(NumericNode::class);
             case "boolean":
                 return new ObjectType(BooleanNode::class);
+            case "file":
+                return new ObjectType(FileNode::class);
             default:
                 return null;
         }

src/Rules/Dimensions.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Square\Hyrule\Rules;
+
+use Illuminate\Validation\Rules\Dimensions as DimensionsRule;
+use Square\Hyrule\Nodes\FileNode;
+
+/**
+ * Extends the Laravel's built-in Dimensions helper and adds methods to support Hyrule's fluent API.
+ */
+class Dimensions extends DimensionsRule
+{
+    private FileNode $node;
+
+    /**
+     * @param FileNode $node
+     * @param array<string,mixed> $constraints
+     */
+    public function __construct(FileNode $node, array $constraints = [])
+    {
+        $this->node = $node;
+        parent::__construct($constraints);
+    }
+
+    public function end(): FileNode
+    {
+        return $this->node;
+    }
+}