feat(util): add binary unit label support to humanFileSize()

[joshtrichards]

• Resolves: [Bug]: Request used more than 300 MB of RAM: 288 MB #58019

Summary

Refactors humanFileSize() to support IEC binary unit labels (KiB, MiB, GiB) while maintaining backward compatibility with existing decimal labels (KB, MB, GB). Math stays the same, but permits us to make the string be technically accurate where we'd prefer that (i.e. in logs - e.g. see #58019) versus where the conventional (albeit inaccurate) end-user friendly facing convention of using KB/MB/GB is preferred even when doing base-1024 math.

Changes

• New parameter: Added optional $useBinaryLabel parameter (defaults to false)
• Refactored logic: Replaced cascading if-statements with maintainable loop-based structure
• Class constants: Introduced DECIMAL_LABELS, BINARY_LABELS, and MAX_LABEL_INDEX for better maintainability
• Improved documentation: Enhanced docblock with examples and clear explanation of binary vs decimal labels
• Preserved behavior: Maintains existing rounding strategy (0 decimals for KB/KiB, 1 decimal for larger units) to prevent "1024 KB" displays
• EB / EiB support: !

Motivation

• Provides technically accurate option for displaying file sizes using IEC binary prefixes
• Improves code maintainability by eliminating repetitive if-statement cascade
• Makes it trivial to add support for additional units (ZB/ZiB!) in the future
• Addresses the common confusion between binary calculation (÷1024) and decimal unit labels (KB, MB)

TODO

• ...

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

[provokateurin]

Suggested change

	if ($value < 1024 || $unitIndex === self::MAX_LABEL_INDEX) {
	/** @var int<0, 5> $unitIndex */
	return "$value {$units[$unitIndex]}";
	}
	}
	$bytes = round($bytes / 1024, 1);
	return "$bytes PB";
	// Unreachable, but keeps static analyzer happy
	return "$value {$units[self::MAX_LABEL_INDEX]}";
	if ($value < 1024) {
	/** @var int<0, 5> $unitIndex */
	return "$value {$units[$unitIndex]}";
	}
	}
	return "$value {$units[self::MAX_LABEL_INDEX]}";

I think this is easier to understand and also doesn't need to workaround the analyzer.