Make file size messages human-readable

samdark · samdark · commit b4e4c860dd85 · 2026-06-04T23:00:21.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 ## 2.6.1 under development
 
-- no changes in this release.
+- Bug #802: Use human-readable file sizes in `File` validation messages (@samdark)
 
 ## 2.6.0 June 02, 2026
 
diff --git a/docs/guide/en/built-in-rules-file.md b/docs/guide/en/built-in-rules-file.md
@@ -79,6 +79,10 @@ This option should be used with care because the client can send any media type
 For filesystem-backed uploads, size checks use the actual file size on disk. For pathless streams, size checks use the
 PSR-7 upload size when available. If a size constraint is configured and the size can't be determined, validation fails.
 
+Size placeholders in error messages are formatted in a human-readable form, for example `{limit}` is `50 MB` when
+`maxSize` is `50 * 1024 * 1024`. Use `{limitBytes}` or `{exactlyBytes}` when a custom message needs the raw byte value
+for ICU number or plural formatting.
+
 `size` is mutually exclusive with `minSize` and `maxSize`. When both `minSize` and `maxSize` are set, `minSize` must be
 less than or equal to `maxSize`.
 
diff --git a/src/Rule/File.php b/src/Rule/File.php
@@ -127,23 +127,26 @@ final class File implements DumpedRuleInterface, SkipOnErrorInterface, WhenInter
      * - `{property}`: the translated label of the property being validated.
      * - `{Property}`: the translated label of the property being validated, capitalized.
      * - `{file}`: the validated file name when it is available.
-     * - `{exactly}`: expected exact size in bytes.
+     * - `{exactly}`: expected exact size in a human-readable format.
+     * - `{exactlyBytes}`: expected exact size in bytes.
      * @param string $tooSmallMessage A message used when the file size is less than {@see $minSize}.
      *
      * You may use the following placeholders in the message:
      *
      * - `{property}`: the translated label of the property being validated.
      * - `{Property}`: the translated label of the property being validated, capitalized.
      * - `{file}`: the validated file name when it is available.
-     * - `{limit}`: expected minimum size in bytes.
+     * - `{limit}`: expected minimum size in a human-readable format.
+     * - `{limitBytes}`: expected minimum size in bytes.
      * @param string $tooBigMessage A message used when the file size is greater than {@see $maxSize}.
      *
      * You may use the following placeholders in the message:
      *
      * - `{property}`: the translated label of the property being validated.
      * - `{Property}`: the translated label of the property being validated, capitalized.
      * - `{file}`: the validated file name when it is available.
-     * - `{limit}`: expected maximum size in bytes.
+     * - `{limit}`: expected maximum size in a human-readable format.
+     * - `{limitBytes}`: expected maximum size in bytes.
      * @param string $unableToDetermineSizeMessage A message used when file size constraints are configured, but the
      * file size can't be determined.
      *
@@ -200,6 +203,7 @@ public function __construct(
         $this->extensions = $this->normalizeList($extensions);
         $this->mimeTypes = $this->normalizeList($mimeTypes);
         $this->skipOnEmpty = $skipOnEmpty;
+        $this->normalizeDefaultSizeMessages();
     }
 
     public function getName(): string
@@ -485,6 +489,30 @@ private function normalizeList(array|string|null $value): ?array
         return $value;
     }
 
+    private function normalizeDefaultSizeMessages(): void
+    {
+        if (
+            $this->notExactSizeMessage
+            === 'The size of {property} must be exactly {exactly, number} {exactly, plural, one{byte} other{bytes}}.'
+        ) {
+            $this->notExactSizeMessage = 'The size of {property} must be exactly {exactly}.';
+        }
+
+        if (
+            $this->tooSmallMessage
+            === 'The size of {property} cannot be smaller than {limit, number} {limit, plural, one{byte} other{bytes}}.'
+        ) {
+            $this->tooSmallMessage = 'The size of {property} cannot be smaller than {limit}.';
+        }
+
+        if (
+            $this->tooBigMessage
+            === 'The size of {property} cannot be larger than {limit, number} {limit, plural, one{byte} other{bytes}}.'
+        ) {
+            $this->tooBigMessage = 'The size of {property} cannot be larger than {limit}.';
+        }
+    }
+
     private static function isUploadMissing(mixed $value): bool
     {
         return $value instanceof UploadedFileInterface && $value->getError() === UPLOAD_ERR_NO_FILE;
diff --git a/src/Rule/FileHandler.php b/src/Rule/FileHandler.php
@@ -20,7 +20,10 @@
 use function is_readable;
 use function is_string;
 use function mime_content_type;
+use function number_format;
 use function pathinfo;
+use function round;
+use function rtrim;
 use function str_contains;
 use function str_ends_with;
 use function str_replace;
@@ -279,27 +282,76 @@ private function validateSize(array $file, File $rule, ValidationContext $contex
         }
 
         if ($rule->getSize() !== null && $size !== $rule->getSize()) {
+            $ruleSize = $rule->getSize();
             $result->addError(
                 $rule->getNotExactSizeMessage(),
-                $this->getParameters($context, $file, ['exactly' => $rule->getSize()]),
+                $this->getParameters(
+                    $context,
+                    $file,
+                    [
+                        'exactly' => $this->formatSize($ruleSize),
+                        'exactlyBytes' => $ruleSize,
+                    ],
+                ),
             );
         }
 
         if ($rule->getMinSize() !== null && $size < $rule->getMinSize()) {
+            $minSize = $rule->getMinSize();
             $result->addError(
                 $rule->getTooSmallMessage(),
-                $this->getParameters($context, $file, ['limit' => $rule->getMinSize()]),
+                $this->getParameters(
+                    $context,
+                    $file,
+                    [
+                        'limit' => $this->formatSize($minSize),
+                        'limitBytes' => $minSize,
+                    ],
+                ),
             );
         }
 
         if ($rule->getMaxSize() !== null && $size > $rule->getMaxSize()) {
+            $maxSize = $rule->getMaxSize();
             $result->addError(
                 $rule->getTooBigMessage(),
-                $this->getParameters($context, $file, ['limit' => $rule->getMaxSize()]),
+                $this->getParameters(
+                    $context,
+                    $file,
+                    [
+                        'limit' => $this->formatSize($maxSize),
+                        'limitBytes' => $maxSize,
+                    ],
+                ),
             );
         }
     }
 
+    private function formatSize(int $size): string
+    {
+        if ($size < 1024) {
+            return $size . ' ' . ($size === 1 ? 'byte' : 'bytes');
+        }
+
+        $value = (float) $size;
+        foreach (['KB', 'MB', 'GB', 'TB'] as $unit) {
+            $value /= 1024;
+            if (round($value, 2) >= 1024) {
+                continue;
+            }
+
+            return $this->formatSizeValue($value) . ' ' . $unit;
+        }
+
+        $value /= 1024;
+        return $this->formatSizeValue($value) . ' PB';
+    }
+
+    private function formatSizeValue(float $value): string
+    {
+        return rtrim(rtrim(number_format($value, 2, '.', ''), '0'), '.');
+    }
+
     /**
      * @psalm-param FileData $file
      */
diff --git a/tests/Rule/FileTest.php b/tests/Rule/FileTest.php
@@ -149,15 +149,15 @@ public static function dataOptions(): array
                         'parameters' => [],
                     ],
                     'notExactSizeMessage' => [
-                        'template' => 'The size of {property} must be exactly {exactly, number} {exactly, plural, one{byte} other{bytes}}.',
+                        'template' => 'The size of {property} must be exactly {exactly}.',
                         'parameters' => [],
                     ],
                     'tooSmallMessage' => [
-                        'template' => 'The size of {property} cannot be smaller than {limit, number} {limit, plural, one{byte} other{bytes}}.',
+                        'template' => 'The size of {property} cannot be smaller than {limit}.',
                         'parameters' => [],
                     ],
                     'tooBigMessage' => [
-                        'template' => 'The size of {property} cannot be larger than {limit, number} {limit, plural, one{byte} other{bytes}}.',
+                        'template' => 'The size of {property} cannot be larger than {limit}.',
                         'parameters' => [],
                     ],
                     'unableToDetermineSizeMessage' => [
@@ -369,6 +369,52 @@ public static function dataValidationFailed(): array
                 new File(maxSize: 920),
                 ['' => ['The size of value cannot be larger than 920 bytes.']],
             ],
+            'exact size mismatch uses human-readable size' => [
+                self::TEXT_FILE,
+                new File(size: 50 * 1024 * 1024),
+                ['' => ['The size of value must be exactly 50 MB.']],
+            ],
+            'too small uses human-readable size' => [
+                self::TEXT_FILE,
+                new File(minSize: 1536),
+                ['' => ['The size of value cannot be smaller than 1.5 KB.']],
+            ],
+            'too big uses human-readable size' => [
+                self::JPG_FILE,
+                new File(maxSize: 512),
+                ['' => ['The size of value cannot be larger than 512 bytes.']],
+            ],
+            'size boundary rounds to next unit' => [
+                self::createStreamUpload('large.bin', 'application/octet-stream', 1024 * 1024),
+                new File(maxSize: 1024 * 1024 - 1),
+                ['' => ['The size of value cannot be larger than 1 MB.']],
+            ],
+            'custom message uses human-readable size placeholder' => [
+                self::createStreamUpload('large.bin', 'application/octet-stream', 60 * 1024 * 1024),
+                new File(
+                    maxSize: 50 * 1024 * 1024,
+                    tooBigMessage: '{file} is larger than {limit}.',
+                ),
+                ['' => ['large.bin is larger than 50 MB.']],
+            ],
+            'custom message can use raw byte size placeholder' => [
+                self::JPG_FILE,
+                new File(
+                    maxSize: 512,
+                    tooBigMessage: '{file} is larger than {limit}; raw limit is {limitBytes, number} '
+                    . '{limitBytes, plural, one{byte} other{bytes}}.',
+                ),
+                ['' => ['16x18.jpg is larger than 512 bytes; raw limit is 512 bytes.']],
+            ],
+            'custom exact size message can use raw byte size placeholder' => [
+                self::JPG_FILE,
+                new File(
+                    size: 512,
+                    notExactSizeMessage: '{file} must be {exactly}; raw size is {exactlyBytes, number} '
+                    . '{exactlyBytes, plural, one{byte} other{bytes}}.',
+                ),
+                ['' => ['16x18.jpg must be 512 bytes; raw size is 512 bytes.']],
+            ],
             'stream upload unknown exact size' => [
                 self::createStreamUpload('resume.txt', 'text/plain', null),
                 new File(extensions: 'txt', mimeTypes: 'text/plain', size: 22, trustClientMediaType: true),
