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.

Name	Abbreviation	In Bit	In Byte	Constant to use
Bit	b	1	0.125	Unit\Information\Unit::BIT
Kilobit	kb	1000	125	Unit\Information\Unit::KILOBIT
Megabit	Mb	1000000	125000	Unit\Information\Unit::MEGABIT
Gigabit	Gb	1000000000	125000000	Unit\Information\Unit::GIGABIT
Terabit	Tb	1000000000000	125000000000	Unit\Information\Unit::TERABIT
Petabit	Pb	1000000000000000	125000000000000	Unit\Information\Unit::PETABIT
Byte	B	8	1	Unit\Information\Unit::BYTE
Kilobyte	kB	8000	1000	Unit\Information\Unit::KILOBYTE
Megabyte	MB	8000000	1000000	Unit\Information\Unit::MEGABYTE
Gigabyte	GB	8000000000	1000000000	Unit\Information\Unit::GIGABYTE
Terabyte	TB	8000000000000	1000000000000	Unit\Information\Unit::TERABYTE
Petabyte	PB	8000000000000000	1000000000000000	Unit\Information\Unit::PETABYTE
Kibibyte	KiB	8192	1024	Unit\Information\Unit::KIBIBYTE
Mebibyte	MiB	8388608	1048576	Unit\Information\Unit::MEBIBYTE
Gigabyte	GiB	8589934592	1073741824	Unit\Information\Unit::GIBIBYTE
Terabyte	TiB	8796093022208	1099511627776	Unit\Information\Unit::TEBIBYTE
Pebibyte	PiB	9007199254740992	1125899906842624	Unit\Information\Unit::PEBIBYTE

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.

unit / information

Maintainers

Details