feat: binary file size validation support

Author: yitzwillroth

src/Illuminate/Validation/Rules/File.php

@@ -17,6 +17,16 @@ class File implements Rule, DataAwareRule, ValidatorAwareRule
 {
     use Conditionable, Macroable;
 
+    /**
+     * Binary units flag used for size validation.
+     */
+    public const BINARY = 'binary';
+
+    /**
+     * International units flag used for size validation.
+     */
+    public const INTERNATIONAL = 'international';
+
     /**
      * The MIME types that the given file should match. This array may also contain file extensions.
      *
@@ -45,6 +55,11 @@ class File implements Rule, DataAwareRule, ValidatorAwareRule
      */
     protected $maximumFileSize = null;
 
+    /**
+     * The units used for size validation.
+     */
+    protected string $units = self::INTERNATIONAL;
+
     /**
      * An array of custom rules that will be merged into the validation rules.
      *
@@ -150,84 +165,175 @@ public function extensions($extensions)
         return $this;
     }
 
+    /**
+     * Set the units for size validation to binary.
+     */
+    public function binary(): static
+    {
+        $this->units = self::BINARY;
+        return $this;
+    }
+
+    /**
+     * Set the units for size validation to international.
+     */
+    public function international(): static
+    {
+        $this->units = self::INTERNATIONAL;
+        return $this;
+    }
+
+
+
     /**
      * Indicate that the uploaded file should be exactly a certain size in kilobytes.
-     *
-     * @param  string|int  $size
-     * @return $this
      */
-    public function size($size)
+    public function size(string|int $size, ?string $units = null): static
     {
-        $this->minimumFileSize = $this->toKilobytes($size);
+        $this->minimumFileSize = $this->toKilobytes($size, $this->units($units));
         $this->maximumFileSize = $this->minimumFileSize;
 
         return $this;
     }
 
     /**
      * Indicate that the uploaded file should be between a minimum and maximum size in kilobytes.
-     *
-     * @param  string|int  $minSize
-     * @param  string|int  $maxSize
-     * @return $this
      */
-    public function between($minSize, $maxSize)
+    public function between(string|int $minSize, string|int $maxSize, ?string $units = null): static
     {
-        $this->minimumFileSize = $this->toKilobytes($minSize);
-        $this->maximumFileSize = $this->toKilobytes($maxSize);
+        $this->minimumFileSize = $this->toKilobytes($minSize, $this->units($units));
+        $this->maximumFileSize = $this->toKilobytes($maxSize, $this->units($units));
 
         return $this;
     }
 
     /**
      * Indicate that the uploaded file should be no less than the given number of kilobytes.
-     *
-     * @param  string|int  $size
-     * @return $this
      */
-    public function min($size)
+    public function min(string|int $size, ?string $units = null): static
     {
-        $this->minimumFileSize = $this->toKilobytes($size);
+        $this->minimumFileSize = $this->toKilobytes($size, $this->units($units));
 
         return $this;
     }
 
     /**
      * Indicate that the uploaded file should be no more than the given number of kilobytes.
-     *
-     * @param  string|int  $size
-     * @return $this
      */
-    public function max($size)
+    public function max(string|int $size, ?string $units = null): static
     {
-        $this->maximumFileSize = $this->toKilobytes($size);
+        $this->maximumFileSize = $this->toKilobytes($size, $this->units($units));
 
         return $this;
     }
 
+    /**
+     * Resolve the units to use for size calculations.
+     */
+    protected function units(?string $units = null): string
+    {
+        return $units ?? $this->units;
+    }
+
     /**
      * Convert a potentially human-friendly file size to kilobytes.
-     *
-     * @param  string|int  $size
-     * @return mixed
      */
-    protected function toKilobytes($size)
+    protected function toKilobytes(string|int $size, string $units): float|int
     {
         if (! is_string($size)) {
             return $size;
         }
 
-        $size = strtolower(trim($size));
+        if (($value = $this->parseSize($size)) === false || $value < 0) {
+            throw new InvalidArgumentException('Invalid numeric value in file size.');
+        }   
+
+        return $units === self::BINARY
+            ? $this->toBinaryKilobytes($size, $value)
+            : $this->toInternationalKilobytes($size, $value);
+    }
+
+    /**
+     * Parse the numeric portion from a file size string.
+     */
+    protected function parseSize($size): false|float
+    {
+        return filter_var(
+            is_numeric($size)
+                ? $size
+                : Str::before(trim($size), Str::match('/[a-zA-Z]/', trim($size))),
+            FILTER_VALIDATE_FLOAT, FILTER_FLAG_ALLOW_THOUSAND
+        );
+    }
+
+    /**
+     * Convert a human-friendly file size to kilobytes using the International System.
+     */
+    protected function toInternationalKilobytes(string $size, float $value): float|int
+    {
+        return round(
+            $this->protectValueFromOverflow(
+                $this->prepareValueForPrecision($value),
+                ! is_numeric($size)
+                    ? match (substr(strtolower(trim($size)), -2)) {
+                        'kb' => 1,
+                        'mb' => 1_000,
+                        'gb' => 1_000_000,
+                        'tb' => 1_000_000_000,
+                        default => throw new InvalidArgumentException(
+                            'Invalid file size suffix. Valid suffixes are: KB, MB, GB, TB (case insensitive).'
+                        ),
+                    } : 1
+                )
+            );
+    }
+
+    /**
+     * Convert a human-friendly file size to kilobytes using the Binary System.
+     */
+    protected function toBinaryKilobytes(string $size, float $value): float|int
+    {
+        return round(
+            $this->protectValueFromOverflow(
+                $this->prepareValueForPrecision($value),
+                ! is_numeric($size)
+                    ? match (substr(strtolower(trim($size)), -2)) {
+                        'kb' => 1,
+                        'mb' => 1_024,
+                        'gb' => 1_048_576,
+                        'tb' => 1_073_741_824,
+                        default => throw new InvalidArgumentException(
+                            'Invalid file size suffix. Valid suffixes are: KB, MB, GB, TB (case insensitive).'
+                        ),
+                    } : 1
+                )
+            );
+    }
 
-        $value = floatval($size);
+    /**
+     * Converts whole numbers to integers for exact arithmetic while keeping
+     * fractional numbers as floats; also provides overflow protection by
+     * falling back to float arithmetic for values too large for integer range.
+     */
+    protected function prepareValueForPrecision(float $value): float|int
+    {
+        return $value > PHP_INT_MAX
+            || $value < PHP_INT_MIN
+            || ((float) (int) $value) !== $value
+                ? $value
+                : (int) $value;
+    }
 
-        return round(match (true) {
-            Str::endsWith($size, 'kb') => $value * 1,
-            Str::endsWith($size, 'mb') => $value * 1_000,
-            Str::endsWith($size, 'gb') => $value * 1_000_000,
-            Str::endsWith($size, 'tb') => $value * 1_000_000_000,
-            default => throw new InvalidArgumentException('Invalid file size suffix.'),
-        });
+    /**
+     * Protect calculations from integer overflow by switching to float arithmetic when necessary.
+     */
+    protected function protectValueFromOverflow(float|int $value, int $multiplier): float|int
+    {
+        return $value > PHP_INT_MAX / $multiplier 
+            || $value < PHP_INT_MIN / $multiplier
+            || is_float($value)
+                ? (float) $value * $multiplier
+                : (int) $value * $multiplier;
     }
 
     /**
@@ -283,14 +389,18 @@ protected function buildValidationRules()
             $rules[] = 'extensions:'.implode(',', array_map(strtolower(...), $this->allowedExtensions));
         }
 
-        $rules[] = match (true) {
-            is_null($this->minimumFileSize) && is_null($this->maximumFileSize) => null,
-            is_null($this->maximumFileSize) => "min:{$this->minimumFileSize}",
-            is_null($this->minimumFileSize) => "max:{$this->maximumFileSize}",
-            $this->minimumFileSize !== $this->maximumFileSize => "between:{$this->minimumFileSize},{$this->maximumFileSize}",
-            default => "size:{$this->minimumFileSize}",
+        $rule = match (true) {
+            $this->minimumFileSize === null && $this->maximumFileSize === null => null,
+            $this->maximumFileSize === null => "min:{$this->minimumFileSize}",
+            $this->minimumFileSize === null => "max:{$this->maximumFileSize}",
+            $this->minimumFileSize === $this->maximumFileSize => "size:{$this->minimumFileSize}",
+            default => "between:{$this->minimumFileSize},{$this->maximumFileSize}",
         };
 
+        if ($rule) {
+            $rules[] = $rule;
+        }
+
         return array_merge(array_filter($rules), $this->customRules);
     }