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 = null;
+
     /**
      * An array of custom rules that will be merged into the validation rules.
      *
@@ -150,83 +165,134 @@ public function extensions($extensions)
         return $this;
     }
 
+    /**
+     * Set the default units for size validation to binary.
+     */
+    public static function binary(): static
+    {
+        return tap(new static, static fn ($file) => $file->units = self::BINARY);
+    }
+
+    /**
+     * Set the default units for size validation to international.
+     */
+    public static function international(): static
+    {
+        return tap(new static, static fn ($file) => $file->units = self::INTERNATIONAL);
+    }
+
     /**
      * 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;
     }
 
+    protected function units(?string $units = null): string
+    {
+        return $units ?? $this->units ?? static::INTERNATIONAL;
+    }
+
+    /**
+     * 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;
+    }
+
     /**
      * 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));
 
-        $value = floatval($size);
+        $value = (float) $size;
+
+        return $units === self::BINARY
+            ? $this->toBinaryKilobytes($size, $value)
+            : $this->toInternationalKilobytes($size, $value);
+    }
+
+    /**
+     * Convert a human-friendly file size to kilobytes using the International System.
+     */
+    protected function toInternationalKilobytes(string $size, float $value): float|int
+    {
+        $value = $this->prepareValueForPrecision($value);
 
         return round(match (true) {
-            Str::endsWith($size, 'kb') => $value * 1,
+            is_numeric($size) => $value,
+            Str::endsWith($size, 'kb') => $value,
             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.'),
+            default => throw new InvalidArgumentException(
+                'Invalid file size suffix. Valid suffixes are: KB, MB, GB, TB (case insensitive).'
+            ),
+        });
+    }
+
+    /**
+     * Convert a human-friendly file size to kilobytes using the Binary System.
+     */
+    protected function toBinaryKilobytes(string $size, float $value): float|int
+    {
+        $value = $this->prepareValueForPrecision($value);
+
+        return round(match (true) {
+            is_numeric($size) => $value,
+            Str::endsWith($size, 'kb') => $value,
+            Str::endsWith($size, 'mb') => $value * 1_024,
+            Str::endsWith($size, 'gb') => $value * 1_048_576,
+            Str::endsWith($size, 'tb') => $value * 1_073_741_824,
+            default => throw new InvalidArgumentException(
+                'Invalid file size suffix. Valid suffixes are: KB, MB, GB, TB (case insensitive).'
+            ),
         });
     }
 
@@ -283,14 +349,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);
     }