README

ByteSize

A small value object for working with file sizes in a clean and predictable way.

It uses 1024 based conversion and gives you a simple API to:

• create sizes from bytes, KB, MB, GB, or TB
• convert values between units
• format values for UI or CLI output
• generate human-readable file size strings

Installation

composer require elephant-php/byte-size

Requirements

• PHP 8.1 or higher

Quick example

use ElephantPhp\ByteSize\ByteSize;
use ElephantPhp\ByteSize\ByteSizeUnit;

$size = ByteSize::fromBytes(2_621_440);

echo $size->toMegabytes();                      // 2.5
echo $size->format(ByteSizeUnit::MEGABYTES);    // 2.5 MB
echo $size->human();                            // 2.5 MB
echo $size->human(0);                           // 2 MB
echo $size->human(0, 'Megabytes');              // 2 Megabytes
echo (string) $size;                            // 2.5 MB

Real-world example

use ElephantPhp\ByteSize\ByteSize;

$bytes = filesize('/path/to/archive.zip');
$size = ByteSize::fromBytes($bytes);

echo $size->human(); // e.g. "14.8 MB"

Creation

use ElephantPhp\ByteSize\ByteSize;

ByteSize::fromBytes(2621440);
ByteSize::fromKilobytes(2560);
ByteSize::fromMegabytes(2.5);
ByteSize::fromGigabytes(0.0025);
ByteSize::fromTerabytes(0.0000025);

Short aliases are available too:

ByteSize::bytes(2621440);
ByteSize::kb(2560);
ByteSize::mb(2.5);
ByteSize::gb(0.0025);
ByteSize::tb(0.0000025);

Conversion

use ElephantPhp\ByteSize\ByteSize;

$size = ByteSize::fromBytes(2_621_440);

$size->toBytes();      // 2621440
$size->toKilobytes();  // 2560
$size->toMegabytes();  // 2.5
$size->toGigabytes();  // 0.00244140625
$size->toTerabytes();  // 0.000002384185791015625

Short aliases:

$size->toKb();
$size->toMb();
$size->toGb();
$size->toTb();

Formatting

Use format() when you want an explicit unit.

use ElephantPhp\ByteSize\ByteSize;
use ElephantPhp\ByteSize\ByteSizeUnit;

$size = ByteSize::fromBytes(2_621_440);

echo $size->format(ByteSizeUnit::TERABYTES, 7);       // 0.0000024 TB
echo $size->format(ByteSizeUnit::TERABYTES, 7, '');   // 0.0000024
echo $size->format(ByteSizeUnit::MEGABYTES, 2);       // 2.5 MB
echo $size->format(ByteSizeUnit::MEGABYTES, 2, 'МБ'); // 2.5 МБ

• $precision controls the number of decimal places before trailing zeros are trimmed
• $label overrides the default unit label
• passing '' as label returns only the numeric value

Human-readable output

Use human() when you want ByteSize to choose the most suitable unit automatically.

use ElephantPhp\ByteSize\ByteSize;

$size = ByteSize::fromBytes(2_621_440);

echo $size->human();              // 2.5 MB
echo $size->human(2, 'MEGABYTE'); // 2.5 MEGABYTE
echo (string) $size;              // 2.5 MB

Examples:

ByteSize::fromBytes(999)->human();                 // 999 B
ByteSize::fromBytes(1024)->human();                // 1 KB
ByteSize::fromBytes(1048576)->human();             // 1 MB
ByteSize::fromBytes(1073741824)->human();          // 1 GB
ByteSize::fromBytes(1099511627776)->human();       // 1 TB

Available units

use ElephantPhp\ByteSize\ByteSizeUnit;

ByteSizeUnit::BYTES;
ByteSizeUnit::KILOBYTES;
ByteSizeUnit::MEGABYTES;
ByteSizeUnit::GIGABYTES;
ByteSizeUnit::TERABYTES;

License

MIT License

Please see LICENSE for more information.