Adding Binary-Based Size Validation Support for File Validation

[wheesnoza]

Hello,

I’d like to propose an enhancement to Laravel’s file size validation to support binary-based size calculations (1KB = 1,024 bytes). This proposal includes two related ideas to address this:

1. Add binary size validation directly to the File validation class.
2. Introduce a Number::kilobytes helper method as a flexible and reusable alternative.

Background

Currently, Laravel’s file validation (e.g., max, size, min) uses SI units (1KB = 1,000 bytes). While this aligns with the SI system, most operating systems and browsers report file sizes using binary units (1KB = 1,024 bytes). This discrepancy can cause unexpected validation failures, particularly for files that appear to be within size limits when viewed through a browser or OS.

For example:

use Illuminate\Validation\Rules\File;

$request->validate([
    'file' => [
        'required',
        File::types(['pdf', 'jpeg', 'png'])
            ->max('10MB'), // 10MB = 10,000KB in SI units
    ],
]);

If a user uploads a file reported as "10MB" by their OS or browser (binary units, 10,240KB), this file would fail validation because Laravel is using SI-based calculations.

Proposal: Two Complementary Solutions

1. Binary Size Validation in the File Class

   • Introduce a method like binarySize() to the File validation class to support binary-based calculations.
   • Example usage:

     File::image()
         ->binarySize()
         ->max('10MB'); // 10MB = 10,240KB (binary units)

   • This approach keeps validation intuitive and aligns with how file sizes are reported by most systems.

2. Add a Number::kilobytes Helper Method

   • Add a reusable helper method to the Number class to convert human-readable size strings (e.g., "10MB", "5GB") into kilobytes using binary calculations.
   • Example implementation:

     public static function kilobytes(string $unit)
     {
         $value = floatval($unit);
         $unit = Str::lower($unit);
     
         return match (true) {
             Str::endsWith($unit, 'kb') => $value,
             Str::endsWith($unit, 'mb') => $value * 1_024,
             Str::endsWith($unit, 'gb') => $value * 1_024 * 1_024,
             Str::endsWith($unit, 'tb') => $value * 1_024 * 1_024 * 1_024,
             default => null,
         };
     }

   • Example usage with the File validation class:

     File::image()
         ->max(Number::kilobytes('10MB'));

   • This provides a flexible way to support binary size calculations without modifying the core File class directly.

Why This Approach?

• There is likely a deliberate reason why Laravel’s file validation currently uses SI units, perhaps for alignment with other frameworks or consistency with PHP’s native ini settings (e.g., upload_max_filesize).
• Instead of modifying the File validation class directly, this approach allows developers to extend functionality in a way that is both backward-compatible and minimally intrusive.
• By combining a binarySize() method with a reusable Number::kilobytes helper, developers have multiple ways to achieve binary size validation, depending on their project needs.

Questions for the Community

1. Do you see value in introducing binary-based size validation to Laravel's File class?
2. Would a Number::kilobytes method, as a flexible helper, be a useful addition for developers?

Next Steps

If the community finds this proposal meaningful, I am happy to proceed with a pull request to implement the Number::kilobytes method and, optionally, the binarySize() method for the File validation class.

Looking forward to your feedback!