Usage

Full documentation on how to use the ByteUnitConverter library on your PHP project.

All methods use numeric strings as arguments and returns numeric strings as the results. All this is because native PHP integers or floats doesn't support big numbers. That's why this library also requires BCMath extension.

ByteUnit

This enum works as a type safety for conversions using ByteUnitConverter utility class, check its documentation to see its usage.

DataUnit

Same as ByteUnit, this is also an enum used for perform conversion between different data units (bytes or bits).

Check this Wikipedia article to understand what a byte is in terms of bytes and more.

MetricSystem

This is another enum used to convert byte units between different metric systems.

Check this Wikipedia article to understand what a metric system means as of a general perspective.

ByteUnitConverter

This utility class is used to convert between:

• Different byte units (KB to MB, TB to GB, etc...)

• Different data units (kilobytes to kilobits, bytes to bits, etc...)

• And different metric systems (kilobytes to kibibytes, tebibytes to gigabytes, etc...).

new

Create new instance from bytes:

(string) ByteUnitConverter::new(1000)->toKB(); // '1 KB'

toBytesFromUnit

Get bytes from unit:

ByteUnitConverter::toBytesFromUnit('1', ByteUnit::KiB); // '1024'

from

Get new instance from value and unit:

(string) ByteUnitConverter::from(1, ByteUnit::MB)->toKB(); // '1000 KB'

numberFormat

Reused internally within the library but publicly available.

Format numbers using PHP's number_format built-in function but removing thousands separator and some other improvements:

ByteUnitConverter::numberFormat('1000.00', 0); // '1000'

setPrecision

Default to 2 as is same as the decimal positions from the output.

See asRound to remove decimals instead of setting this option to 0.

Customise precision for some conversion operations like divisions:

(string) ByteUnitConverter::new('500')->toKiB(); // '0.48 KiB'
(string) ByteUnitConverter::new('500')->setPrecision(3)->toKiB(); // '0.488 KiB'
(string) ByteUnitConverter::new('500')->setPrecision(6)->toKiB(); // '0.488281 KiB'

asRound

As for v3 this is now accepting integers and booleans as input argument. Defaults to at least 2 decimals if possible.

Round result to a integer with as less decimals as possible:

(string) ByteUnitConverter::new('229829')->toMB(); // '0.23 MB'

(string) ByteUnitConverter::new('229829')->asRound()->toMB(); // '0.2 MB'

Disable any rounding on the result:

(string) ByteUnitConverter::new('229829')->asRound(false)->toMB(); // '0.2298 MB'

Round as much as possible until reach 3 decimals:

(string) ByteUnitConverter::new('229829')->asRound(3)->toMB(); // '0.23 MB'

(string) ByteUnitConverter::new('2290829')->asRound(false)->toMB(); // '2.2908 MB'

(string) ByteUnitConverter::new('2290829')->asRound(3)->toMB(); // '2.291 MB'

(string) ByteUnitConverter::new('2290829')->asRound(2)->toMB(); // '2.29 MB'

useUnitLabel

Round result to a integer without decimals:

(string) ByteUnitConverter::new('500')->useUnitLabel()->toKiB(); // '0.5 kibibyte'
(string) ByteUnitConverter::new('2000')->useUnitLabel()->toKB(); // '2 kilobytes'

nearestUnit

Convert bytes to their nearest unit on the specified metric system:

(string) ByteUnitConverter::new('10000239595')->nearestUnit(); // '10 GB'
(string) ByteUnitConverter::new('102239595')->nearestUnit(); // '102.23 MB'

// Can also specify a different metric system
(string) ByteUnitConverter::new('10000239595')->nearestUnit(MetricSystem::Binary); // '9.31 GiB'
(string) ByteUnitConverter::new('102239595')->nearestUnit(MetricSystem::Binary); // '97.50 MiB'

getValue

Get the resulting numeric value from the conversion:

ByteUnitConverter::new('500')->toKB()->getValue(); // '0.50'

getUnit

Get the resulting byte unit as string from the conversion:

ByteUnitConverter::new('1000')->toKB()->getUnit(); // 'KB'
ByteUnitConverter::new('1000')->toKB()->useUnitLabel()->getUnit(); // 'kilobyte'
ByteUnitConverter::new('2000')->toKB()->useUnitLabel()->getUnit(); // 'kilobytes'

to

Convert bytes to byte unit:

(string) ByteUnitConverter::new('500')->to(ByteUnit::KB); // '0.5 KB'

// or use convenience method
(string) ByteUnitConverter::new('500')->toKB(); // '0.5 KB'

All byte units from all metric systems available in this library have their own conversion methods for convenience.

usingBytes

Perform conversions using bytes data unit:

(string) ByteUnitConverter::new('500')->usingBytes()->toKB(); // '0.50 KB'

This library already use bytes as a default data unit.

usingBits

Perform conversions using bits data unit:

(string) ByteUnitConverter::new('500')
    ->usingBits()
    ->useUnitLabel()
    ->toKB(); // '4 kilobits'

__toString

Serialise conversion result to string:

ByteUnitConverter::new('500')->__toString(); // '500 B'

// or just casting as we always use
(string) ByteUnitConverter::new('500'); // '500 B'

toArray

Serialise conversion result to multidimensional array:

ByteUnitConverter::new('1000')->toKB()->toArray(); // ['unit' => 'KB', 'unit_label' => 'kilobyte', 'value' => '1.00']

serialize

The ByteUnitConverter utility class can be also serialised/deserialised using PHP serialisation:

$serialised = serialize(ByteUnitConverter::new('1000')->toKB()); // 'O:50:"OpenSoutheners\ByteUnitConverter\ByteUnitConverter":3:{s:5:"bytes";s:4:"1000";s:9:"byte_unit";s:3:"1e3";s:9:"data_unit";s:1:"1";}'

unserialize($serialised); // ByteUnitConverter instance

add

Manipulation methods returns new instances of the ByteUnitConverter to remain immutable.

Add quantity of any byte unit to the current instance making a new one:

ByteUnitConverter::new('1000')->add('1', ByteUnit::KB)->toKB(); // '2 KB'

subtract

Remove quantity of any byte unit to the current instance making a new one:

ByteUnitConverter::new('2000')->subtract('1', ByteUnit::KB)->toKB(); // '1 KB