README

A simple, handy PHP library to work with file sizes and units.

Convert, compare, parse, and format sizes in bytes, bits, kilobytes, megabytes... you name it.
Supports bits and bytes, plus all common units up to yottabytes.

Features

Convert sizes between any units (e.g. MB → GB, bits → bytes)
Generate human-readable size strings from raw values or unit-based input
Parse human-readable strings like "1.5 GB" or "200 Kb"
Auto-detect the best unit for a given raw size (e.g. 1536000 → MB)
Format numbers cleanly with optional decimal precision
Compare two sizes across different units
Get percentage relations between sizes
Validate units easily (B, KB, Mb, Gb, etc.)
Customize unit labels for flexible display

Supported Units

Bytes: B, KB, MB, GB, TB, PB, EB, ZB, YB
Bits: b, Kb, Mb, Gb, Tb, Pb, Eb, Zb, Yb

🫡 Usage

🚀 Installation

You can install the package via composer:

composer require nabeghe/filesize

Or manually include the FileSize.php if you want to keep it old school.

Examples

First:

use Nabeghe\FileSize;

Get a list of all supported units

Syntax: getAllUnits(bool $bits = false): array

FileSize::getAllUnits();     // ['B', 'KB', 'MB', 'GB', ...]
FileSize::getAllUnits(true); // ['b', 'Kb', 'Mb', 'Gb', ...]

Check if a unit is supported

Syntax: isValidUnit(string $unit): bool

FileSize::isValidUnit('MB');  // true
FileSize::isValidUnit('xyz'); // false

Clean up a number to a fixed decimal format

Syntax: format(float|int $size, int $decimals = 2): int|float

FileSize::format(13);         // 13
FileSize::format(14);         // 14
FileSize::format(100.456);    // 100.46
FileSize::format(100.000001); // 100
FileSize::format(313.1314, 3) // 313.131

Convert between units

Syntax: convert($size, $fromUnit, $toUnit, $format = false, $isBinary = true)

FileSize::convert(1, 'GB', 'MB');               // 1024
FileSize::convert(1024, 'KB', 'MB');            // 1
FileSize::convert(1, 'GB', 'Mb');               // 8192
FileSize::convert(1234, 'MB', 'GB', 1);         // 1.2
FileSize::convert(1, 'Gb', 'Mb');               // 1024
FileSize::convert(1, 'Gb', 'Mb', false, false); // 1000 (decimal)

Compare two sizes, even if in different units

Syntax: compare($size1, $unit1, $size2, $unit2): int

FileSize::compare(1, 'GB', 1024, 'MB'); // 0 (equal)
FileSize::compare(1, 'GB', 2, 'GB');    // -1 (smaller)
FileSize::compare(3, 'Mb', 2, 'MB');    // -1 (smaller, because 3Mb ≈ 0.375MB)

Find the best-fit unit for a byte size

Syntax: detectUnit($size, $isBits = false, &$finalSize = null, bool $isBinary = true: string

$unit = FileSize::detectUnit(123456789, false, $finalSize); // binary=1024
// $unit => 'MB', $finalSize => 117.74

$unit = FileSize::detectUnit(123456789, false, $finalSize, false); // decimal=1000
// $unit => 'MB', $finalSize => 123.46

Turn a byte or bit size into a human-readable string

Syntax: readable($size, $isBits = false, $labels = [])

FileSize::readable(123456789);                                  // "117.74 MB"
FileSize::readable(123456789, false, null, false);              // "123.46 MB"
FileSize::readable(123456789, true);                            // "117.74 Mb"
FileSize::readable(123456789, true, null, false);               // "123.46 Mb"
FileSize::readable(1024**3, false, ['GB' => 'Gigabyte'])        // "1 Gigabyte"
FileSize::readable(1024**3, false, ['GB' => 'Gigabyte'], false) // "1.07 Gigabyte"

Convert a size from a specific unit and make it readable

Syntax: readableFromUnit($size, $unit, $labels = [], bool $isBinary = true)

FileSize::readableFromUnit(2048, 'KB');              // "2 MB"
FileSize::readableFromUnit(2000, 'KB', null, false); // "2 MB"
FileSize::readableFromUnit(2048, 'Kb');              // "2 Mb"
FileSize::readableFromUnit(1, 'Gb');                 // "1 Gb"

Extract numeric value and unit from a string

Syntax: parse(string $input): array

FileSize::parse('1.5 GB');   // [1.5, 'GB']
FileSize::parse('  200 Kb'); // [200, 'Kb']
FileSize::parse('3mb');      // [3.0, 'mb']

Calculate how much size1 is of size2 in %

Syntax: percentage($size1, $unit1, $size2, $unit2, bool $isBinary = true): float

FileSize::percentage(512, 'MB', 1, 'GB'); // 50.0
FileSize::percentage(100, 'Kb', 1, 'Mb'); // 10.0

📖 License

Licensed under the MIT license, see LICENSE.md for details.

nabeghe / file-size

Maintainers

Details