README

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

Installation

user@machine:~$ composer require unit/information

Units

The used units follow the IEC standard.

Usage

Intelligent formatting:

use Unit\Information\Size;

// Format 1 Byte
(new Size(1))->format(); // "1B"

// Format Byte values
(new Size(4300000))->format();     // "4.3MB"
(new Size(73042346800))->format(); // "73.0423468GB"

// Cut at precision
(new Size(73042346800))->format(null);    // "73GB"
(new Size(73042346800))->format(null, 0); // "73GB"
(new Size(73042346800))->format(null, 2); // "73.04GB"

// Custom format
(new Size(73042346800))->format(null, 1, '%size% %unit_abbreviation% (%unit_name%)'); // "73.0 GB (Gigabyte)"

Format value in specified unit:

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

(new Size(73042346800))->format(Unit::MEGABYTE); // "73042MB"
(new Size(300000))->format(Unit::MEGABYTE, 1);   // "0.3MB"

Transform to a number (not a formatted string) value in another unit:

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

(new Size(100000))->get(Unit::KILOBYTE); // 100
(new Size(1))->get(Unit::KILOBYTE);      // 0.001

Create a size from a value in a specified unit:

use Unit\Information\Size;

new Size(1);     // If the value is not a string it is treated as a Byte value which is transformed to a Bit value internally
new Size('1MB'); // If it is a string the string is transformed to a Bit value intelligently
new Size('0.05GB');

Calculating:

use Unit\Information\Size;

$size = new Size(1);
$otherSize = new Size('1MB');

$size->add($otherSize);
$size->subtract($otherSize);
$size->multiply($otherSize);
$size->divide($otherSize);

$size->add($otherSize)->subtract($otherSize); // Can be chained

Instantiate from PHP's shorthand values (which do not follow the IEC standard, see https://www.php.net/manual/en/faq.using.php#faq.using.shorthandbytes):

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

$size = Size::createFromPhpShorthandValue('1M'); // Results in 1048576 Bytes
try {
    $size = Size::createFromPhpShorthandValue(ini_get('memory_limit'));
} catch (InvalidPhpShorthandValueException $exception) {
    // $exception->getMessage() is: 'The PHP shorthand value "-1" cannot be converted to a meaningful size.'
}

Development

For some development tools the Symfony binary has to be installed:

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

Build repo for development:

user@machine:~$ git clone git@github.com:michaelKaefer/money-bundle.git
user@machine:~$ cd money-bundle/
user@machine:~$ make build-dev

Testing:

user@machine:~$ make tests
// Build PHP code coverage
user@machine:~$ make code-coverage

Linting:

user@machine:~$ make composer-validate
user@machine:~$ make security-check
user@machine:~$ make psalm-dry-run
user@machine:~$ make cs-fixer-dry-run

License

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