unit/information

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

2.0.3 2025-06-16 19:52 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Michael Käfer

• php
• unit
• bit
• information
• byte
• kilobit
• megabit
• gigabit
• terabit
• petabit
• kilobyte
• megabyte
• gigabyte
• terabyte
• petabyte
• kibibytes
• mebibyte
• gibibyte
• tebibyte
• pebibyte

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 other units (internally other units are converted to bits)
$size = Size::fromBytes(1);
$size = Size::fromMegabytes(10);
// Avoid an exception on invalid values (that means values that cannot be converted to bits):
$size = Size::fromBytes(1.111, false);

// ... 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.5GB');

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

// ... or from ini settings
try {
    $size = Size::fromMemoryLimit(); // Calls ini_get('memory_limit')
} catch (\Unit\Information\Exception\NoMemoryLimitException $exception) {
    // For example if memory_limit is "-1"
}
$size = Size::fromUploadMaxFilesize(); // Calls ini_get('upload_max_filesize')
$size = Size::fromRealMemoryUsage(); // Calls memory_get_usage(true)

// ... or from directories or files
$size = Size::fromDirectoryOrFile('/var/foobar');

Formatting:

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

// Default format uses nearest unit and returns a human-readable string
Size::fromBytes(1)->format();              // "1B"
Size::fromBytes(141642)->format();         // "141.6kB"
Size::fromBytes(14164234235235)->format(); // "14.2TB"

// Specific unit
Size::fromBytes(1)->format(Unit::Bit);                       // "8b"
Size::fromBytes(1)->format(Unit::Byte);                      // "1B"
Size::fromBytes(1)->format(Unit::Kilobyte);                  // "0.0kB"
Size::fromBytes(1)->format(Unit::Kilobyte, precision: null); // "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 return a new instance)
$newSize = $size->add($otherSize); // $size is still 1M, $otherSize is still 1M
$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 [e-mail]: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.