unit/information

Package for transforming, formatting and calculating information units like bits, bytes, kilobits, kilobytes, megabits, megabytes, kibibytes, mebibytes etc.

2.0.2 2025-06-10 21:40 UTC

This package is auto-updated.

Last update: 2025-06-10 21:40:43 UTC


README

Package for calculating and formatting information units like Bit, Byte, Kilobit, Kilobyte, Megabit, Megabyte, etc.

Installation

user@machine:~$ composer require unit/information

Notes

The units follow the IEC standard:

Name Abbreviation Bit Byte
Bit b 1 0.125
Kilobit kb 1000 125
Megabit Mb 1000000 125000
Gigabit Gb 1000000000 125000000
Terabit Tb 1000000000000 125000000000
Petabit Pb 1000000000000000 125000000000000
Byte B 8 1
Kilobyte kB 8000 1000
Megabyte MB 8000000 1000000
Gigabyte GB 8000000000 1000000000
Terabyte TB 8000000000000 1000000000000
Petabyte PB 8000000000000000 1000000000000000
Kibibyte KiB 8192 1024
Mebibyte MiB 8388608 1048576
Gibibyte GiB 8589934592 1073741824
Tebibyte TiB 8796093022208 1099511627776
Pebibyte PiB 9007199254740992 1125899906842624

Usage

Create an instance:

use Unit\Information\Size;

// From bits
$bits = 8;
$size = new Size($bits);

// ...or from bytes (internally bytes are transformed to bits)
$size = Size::fromBytes(1);

// ...or from strings (internally strings are transformed to bits)
$size = Size::fromString('1b');
$size = Size::fromString('1B');
$size = Size::fromString('1MB');
$size = Size::fromString('1KiB');
$size = Size::fromString('0.05GB');

// ...or from PHP shorthand value (https://www.php.net/manual/en/faq.using.php#faq.using.shorthandbytes)
$size = Size::fromPhpShorthandValue('1M'); // 1048576 bytes

// ...another example for PHP shorthand value
try {
    $size = Size::createFromPhpShorthandValue(ini_get('memory_limit'));
} catch (\InvalidArgumentException $exception) {
    // ...
}

Formatting:

use Unit\Information\Size;
use Unit\Information\Unit;

Size::fromBytes(1)->format(); // "1B"

// Specific unit
Size::fromBytes(1)->format(Unit::Bit);                // "8b"
Size::fromBytes(1)->format(Unit::Byte);               // "1B"
Size::fromBytes(1)->format(Unit::Kilobyte);           // "0.001kB"
Size::fromBytes(73042346800)->format(Unit::Megabyte); // "73042MB"
Size::fromBytes(300000)->format(Unit::Megabyte, 1);   // "0.3MB"

// Specific precision
Size::fromBytes(73042346800)->format(precision: null); // "73.0423468GB"
Size::fromBytes(73042346800)->format(precision: 0);    // "73GB"
Size::fromBytes(73042346800)->format(precision: 1);    // "73.0GB"
Size::fromBytes(73042346800)->format(precision: 2);    // "73.04GB"

// Custom format
Size::fromBytes(1)->format(format: '%value% %unit_full_name% (%unit%)'); // "1 Byte (B)"

Numeric value in specific unit:

use Unit\Information\Size;
use Unit\Information\Unit;

Size::fromBytes(100000)->get(Unit::Kilobyte); // 100
Size::fromBytes(1)->get(Unit::Kilobyte);      // 0.001

Calculate:

use Unit\Information\Size;

$size = Size::fromString('1MB');
$otherSize = Size::fromString('1MB');

// Objects are immutable (all operations create a new instance)
$newSize = $size->add($otherSize);
$newSize = $size->subtract($otherSize);
$newSize = $size->multiply($otherSize);
$newSize = $size->divide($otherSize);

// Chainable
$newSize = $size->add($otherSize)->subtract($otherSize);

Development

Install Symfony binary to make life easier:

user@machine:~$ wget https://get.symfony.com/cli/installer -O - | bash

Build repo for development:

user@machine:~$ git clone git@github.com:michaelKaefer/information.git
user@machine:~$ cd information/
user@machine:~$ symfony composer install

Testing:

user@machine:~$ symfony run vendor/bin/phpunit
// Build PHP code coverage (needs Xdebug)
user@machine:~$ make code-coverage

Before releases:

user@machine:~$ make before-release

License

The MIT License (MIT). Please see License File for more information.