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:

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

Round result to a integer without decimals:

(string) ByteUnitConverter::new('500')->asRound()->toKiB(); // '0.5 KiB'

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