Refactor Size rule

Currently, the Size rule does multiple things, yet it's limited. Because it does many things, it's also confusing. Turning the Size rule into a transformation allows for way more flexibility and clarity. The syntax becomes more verbose, but the rule becomes more reusable.
Respect · Dec 16, 2024 · 6e3ed79 · 6e3ed79
1 parent 94daa8d
commit 6e3ed79
Show file tree

Hide file tree

Showing 23 changed files with 514 additions and 266 deletions.
diff --git a/docs/09-list-of-rules-by-category.md b/docs/09-list-of-rules-by-category.md
@@ -265,6 +265,7 @@
 - [Length](rules/Length.md)
 - [Max](rules/Max.md)
 - [Min](rules/Min.md)
+- [Size](rules/Size.md)
 
 ## Types
 

diff --git a/docs/rules/Size.md b/docs/rules/Size.md
@@ -1,78 +1,71 @@
 # Size
 
-- `Size(string $minSize)`
-- `Size(string $minSize, string $maxSize)`
-- `Size(null, string $maxSize)`
+- `Size(string $unit, Rule $rule)`
 
 Validates whether the input is a file that is of a certain size or not.
 
 ```php
-v::size('1KB')->isValid($filename); // Must have at least 1KB size
-v::size('1MB', '2MB')->isValid($filename); // Must have the size between 1MB and 2MB
-v::size(null, '1GB')->isValid($filename); // Must not be greater than 1GB
+v::size('KB', v::greaterThan(1))->isValid($filename);
+v::size('MB', v::between(1, 2))->isValid($filename);
+v::size('GB', v::lessThan(1))->isValid($filename);
 ```
 
-Sizes are not case-sensitive and the accepted values are:
+Accepted data storage units are `B`, `KB`, `MB`, `GB`, `TB`, `PB`, `EB`, `ZB`, and `YB`.
 
-- B
-- KB
-- MB
-- GB
-- TB
-- PB
-- EB
-- ZB
-- YB
+This validator will accept:
 
-This validator will consider `SplFileInfo` instances, like:
+* `string` file paths
+* `SplFileInfo` objects (see [SplFileInfo][])
+* `Psr\Http\Message\UploadedFileInterface` objects (see [PSR-7][])
+* `Psr\Http\Message\StreamInterface` objects (see [PSR-7][])
 
-```php
-v::size('1.5mb')->isValid(new SplFileInfo($filename)); // Will return true or false
-```
+## Templates
 
-Message template for this validator includes `{{minSize}}` and `{{maxSize}}`.
+### `Size::TEMPLATE_STANDARD`
 
-## Templates
+| Mode       | Template                           |
+|------------|------------------------------------|
+| `default`  | The size in {{unit&#124;trans}} of |
+| `inverted` | The size in {{unit&#124;trans}} of |
 
-### `Size::TEMPLATE_BOTH`
+This template serve as message prefix:
 
-| Mode       | Template                                                 |
-|------------|----------------------------------------------------------|
-| `default`  | {{name}} must be between {{minSize}} and {{maxSize}}     |
-| `inverted` | {{name}} must not be between {{minSize}} and {{maxSize}} |
+```php
+v::size('MB', v::equals(2))->assert('filename.txt')
+// Message: The size in megabytes of "filename.txt" must be equal to 2
 
-### `Size::TEMPLATE_LOWER`
+v::size('KB', v::not(v::equals(56)))->assert('filename.txt')
+// Message: The size in kilobytes of "filename.txt" must not be equal to 56
+```
 
-| Mode       | Template                                      |
-|------------|-----------------------------------------------|
-| `default`  | {{name}} must be greater than {{minSize}}     |
-| `inverted` | {{name}} must not be greater than {{minSize}} |
+### `Size::TEMPLATE_WRONG_TYPE`
 
-### `Size::TEMPLATE_GREATER`
+Used when the input is not a valid file path, a `SplFileInfo` object, or a PSR-7 interface.
 
-| Mode       | Template                                    |
-|------------|---------------------------------------------|
-| `default`  | {{name}} must be lower than {{maxSize}}     |
-| `inverted` | {{name}} must not be lower than {{maxSize}} |
+| Mode       | Template                                                                           |
+|------------|------------------------------------------------------------------------------------|
+| `default`  | {{name}} must be a filename or an instance of SplFileInfo or a PSR-7 interface     |
+| `inverted` | {{name}} must not be a filename or an instance of SplFileInfo or a PSR-7 interface |
 
 ## Template placeholders
 
 | Placeholder | Description                                                      |
 |-------------|------------------------------------------------------------------|
-| `maxSize`   |                                                                  |
-| `minSize`   |                                                                  |
 | `name`      | The validated input or the custom validator name (if specified). |
+| `unit`      | The name of the storage unit (bytes, kilobytes, etc.)            |
 
 ## Categorization
 
 - File system
+- Transformations
 
 ## Changelog
 
-| Version | Description       |
-|--------:|-------------------|
-|   2.1.0 | Add PSR-7 support |
-|   1.0.0 | Created           |
+| Version | Description             |
+|--------:|-------------------------|
+|   3.0.0 | Became a transformation |
+|   2.1.0 | Add [PSR-7][] support   |
+|   1.0.0 | Created                 |
 
 ***
 See also:
@@ -88,3 +81,6 @@ See also:
 - [SymbolicLink](SymbolicLink.md)
 - [Uploaded](Uploaded.md)
 - [Writable](Writable.md)
+
+[PSR-7]: https://www.php-fig.org/psr/psr-7/
+[SplFileInfo]: https://www.php.net/SplFileInfo
diff --git a/library/Factory.php b/library/Factory.php
@@ -21,6 +21,7 @@
 use Respect\Validation\Transformers\DeprecatedKeyValue;
 use Respect\Validation\Transformers\DeprecatedLength;
 use Respect\Validation\Transformers\DeprecatedMinAndMax;
+use Respect\Validation\Transformers\DeprecatedSize;
 use Respect\Validation\Transformers\DeprecatedType;
 use Respect\Validation\Transformers\Prefix;
 use Respect\Validation\Transformers\RuleSpec;
@@ -44,7 +45,9 @@ public function __construct(
                 new DeprecatedKeyValue(
                     new DeprecatedMinAndMax(
                         new DeprecatedAge(
-                            new DeprecatedKeyNested(new DeprecatedLength(new DeprecatedType(new Aliases(new Prefix()))))
+                            new DeprecatedKeyNested(new DeprecatedLength(new DeprecatedType(new DeprecatedSize(
+                                new Aliases(new Prefix())
+                            ))))
                         )
                     )
                 )

diff --git a/library/Mixins/ChainedKey.php b/library/Mixins/ChainedKey.php
@@ -293,11 +293,10 @@ public function keyRoman(int|string $key): ChainedValidator;
 
     public function keyScalarVal(int|string $key): ChainedValidator;
 
-    public function keySize(
-        int|string $key,
-        string|int|null $minSize = null,
-        string|int|null $maxSize = null,
-    ): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public function keySize(int|string $key, string $unit, Rule $rule): ChainedValidator;
 
     public function keySlug(int|string $key): ChainedValidator;
 

diff --git a/library/Mixins/ChainedNot.php b/library/Mixins/ChainedNot.php
@@ -295,7 +295,10 @@ public function notRoman(): ChainedValidator;
 
     public function notScalarVal(): ChainedValidator;
 
-    public function notSize(string|int|null $minSize = null, string|int|null $maxSize = null): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public function notSize(string $unit, Rule $rule): ChainedValidator;
 
     public function notSlug(): ChainedValidator;
 

diff --git a/library/Mixins/ChainedNullOr.php b/library/Mixins/ChainedNullOr.php
@@ -305,7 +305,10 @@ public function nullOrRoman(): ChainedValidator;
 
     public function nullOrScalarVal(): ChainedValidator;
 
-    public function nullOrSize(string|int|null $minSize = null, string|int|null $maxSize = null): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public function nullOrSize(string $unit, Rule $rule): ChainedValidator;
 
     public function nullOrSlug(): ChainedValidator;
 

diff --git a/library/Mixins/ChainedProperty.php b/library/Mixins/ChainedProperty.php
@@ -314,11 +314,10 @@ public function propertyRoman(string $propertyName): ChainedValidator;
 
     public function propertyScalarVal(string $propertyName): ChainedValidator;
 
-    public function propertySize(
-        string $propertyName,
-        string|int|null $minSize = null,
-        string|int|null $maxSize = null,
-    ): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public function propertySize(string $propertyName, string $unit, Rule $rule): ChainedValidator;
 
     public function propertySlug(string $propertyName): ChainedValidator;
 

diff --git a/library/Mixins/ChainedUndefOr.php b/library/Mixins/ChainedUndefOr.php
@@ -303,7 +303,10 @@ public function undefOrRoman(): ChainedValidator;
 
     public function undefOrScalarVal(): ChainedValidator;
 
-    public function undefOrSize(string|int|null $minSize = null, string|int|null $maxSize = null): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public function undefOrSize(string $unit, Rule $rule): ChainedValidator;
 
     public function undefOrSlug(): ChainedValidator;
 

diff --git a/library/Mixins/ChainedValidator.php b/library/Mixins/ChainedValidator.php
@@ -349,7 +349,10 @@ public function roman(): ChainedValidator;
 
     public function scalarVal(): ChainedValidator;
 
-    public function size(string|int|null $minSize = null, string|int|null $maxSize = null): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public function size(string $unit, Rule $rule): ChainedValidator;
 
     public function slug(): ChainedValidator;
 

diff --git a/library/Mixins/StaticKey.php b/library/Mixins/StaticKey.php
@@ -301,11 +301,10 @@ public static function keyRoman(int|string $key): ChainedValidator;
 
     public static function keyScalarVal(int|string $key): ChainedValidator;
 
-    public static function keySize(
-        int|string $key,
-        string|int|null $minSize = null,
-        string|int|null $maxSize = null,
-    ): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public static function keySize(int|string $key, string $unit, Rule $rule): ChainedValidator;
 
     public static function keySlug(int|string $key): ChainedValidator;
 

diff --git a/library/Mixins/StaticNot.php b/library/Mixins/StaticNot.php
@@ -295,7 +295,10 @@ public static function notRoman(): ChainedValidator;
 
     public static function notScalarVal(): ChainedValidator;
 
-    public static function notSize(string|int|null $minSize = null, string|int|null $maxSize = null): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public static function notSize(string $unit, Rule $rule): ChainedValidator;
 
     public static function notSlug(): ChainedValidator;
 

diff --git a/library/Mixins/StaticNullOr.php b/library/Mixins/StaticNullOr.php
@@ -305,10 +305,10 @@ public static function nullOrRoman(): ChainedValidator;
 
     public static function nullOrScalarVal(): ChainedValidator;
 
-    public static function nullOrSize(
-        string|int|null $minSize = null,
-        string|int|null $maxSize = null,
-    ): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public static function nullOrSize(string $unit, Rule $rule): ChainedValidator;
 
     public static function nullOrSlug(): ChainedValidator;
 

diff --git a/library/Mixins/StaticProperty.php b/library/Mixins/StaticProperty.php
@@ -358,11 +358,10 @@ public static function propertyRoman(string $propertyName): ChainedValidator;
 
     public static function propertyScalarVal(string $propertyName): ChainedValidator;
 
-    public static function propertySize(
-        string $propertyName,
-        string|int|null $minSize = null,
-        string|int|null $maxSize = null,
-    ): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public static function propertySize(string $propertyName, string $unit, Rule $rule): ChainedValidator;
 
     public static function propertySlug(string $propertyName): ChainedValidator;
 

diff --git a/library/Mixins/StaticUndefOr.php b/library/Mixins/StaticUndefOr.php
@@ -303,10 +303,10 @@ public static function undefOrRoman(): ChainedValidator;
 
     public static function undefOrScalarVal(): ChainedValidator;
 
-    public static function undefOrSize(
-        string|int|null $minSize = null,
-        string|int|null $maxSize = null,
-    ): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public static function undefOrSize(string $unit, Rule $rule): ChainedValidator;
 
     public static function undefOrSlug(): ChainedValidator;
 

diff --git a/library/Mixins/StaticValidator.php b/library/Mixins/StaticValidator.php
@@ -329,7 +329,10 @@ public static function roman(): ChainedValidator;
 
     public static function scalarVal(): ChainedValidator;
 
-    public static function size(string|int|null $minSize = null, string|int|null $maxSize = null): ChainedValidator;
+    /**
+     * @param "B"|"KB"|"MB"|"GB"|"TB"|"PB"|"EB"|"ZB"|"YB" $unit
+     */
+    public static function size(string $unit, Rule $rule): ChainedValidator;
 
     public static function slug(): ChainedValidator;
 

diff --git a/library/Result.php b/library/Result.php
@@ -117,7 +117,7 @@ public function withInput(mixed $input): self
         return $this->clone(
             input: $input,
             children: array_map(
-                static fn (Result $child) => $child->input === $currentInput ? $input : $child->input,
+                static fn (Result $child) => $child->input === $currentInput ? $child->withInput($input) : $child,
                 $this->children
             ),
         );