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:

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.