Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gabrielelana/byte-units
Library to parse, format and convert byte units
https://github.com/gabrielelana/byte-units
Last synced: 19 days ago
JSON representation
Library to parse, format and convert byte units
- Host: GitHub
- URL: https://github.com/gabrielelana/byte-units
- Owner: gabrielelana
- License: mit
- Created: 2014-06-11T15:22:54.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-01-16T23:46:30.000Z (almost 4 years ago)
- Last Synced: 2024-05-17T04:01:46.591Z (7 months ago)
- Language: PHP
- Homepage:
- Size: 59.6 KB
- Stars: 160
- Watchers: 5
- Forks: 15
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-php - ByteUnits - A library to parse, format and convert byte units in binary and metric systems. (Table of Contents / Numbers)
- awesome-php-cn - ByteUnits - 库来解析,在二进制格式和转换字节单位和公制系统. (目录 / 数字 Numbers)
- awesome-projects - ByteUnits - A library to parse, format and convert byte units in binary and metric systems. (PHP / Numbers)
- awesome-php - ByteUnits - A library to parse, format and convert byte units in binary and metric systems. (Table of Contents / Numbers)
README
## Byte Units [](https://travis-ci.org/gabrielelana/byte-units)
This is a utility component for parsing, formatting, converting and manipulating byte units in various formats.
## Usage
```php
add('256B')->format('kB/0000'); // outputs 1420.2560kB
// Bytes comparison
ByteUnits\parse('1.2GB')->isMoreThan('256MB'); // it's true
```
### Parsing
Right now two unit systems are supported:
* The `Metric` system that is based on a 1000-byte kilobyte and uses standard SI suffixes (`kB`, `MB`, `GB`, `TB`, `PB`, …)
* The `Binary` system that is based on a 1024-byte kilobyte and uses binary suffixes (`KiB`, `MiB`, `GiB`, `TiB`, `PiB`, …)
```php
format(); // outputs 1.00kB
echo ByteUnits\Binary::bytes(1024)->format(); // outputs 1.00KiB
// Implicit selection through parsing
ByteUnits\parse('1.00kB'); // it's an instance of ByteUnits\Metric
// You can also constraint parsing to a specific system
ByteUnits\Metric::parse('1.00kB'); // it's an instance of ByteUnits\Metric
ByteUnits\Binary::parse('1.00kB'); // throws a ByteUnits\ParseException
// For each systems there are static constructors, one for each supported unit
echo ByteUnits\Metric::bytes(1000)->format(); // outputs 1.00kB
echo ByteUnits\Metric::kilobytes(1)->format(); // outputs 1.00kB
echo ByteUnits\Metric::megabytes(1)->format(); // outputs 1.00MB
// You can switch between systems
echo ByteUnits\Binary::bytes(1024)->asMetric()->format(); // outputs 1.02kB
```
### Formatting
In both systems you can format bytes with an appropriate format string
```php
format(); // outputs 1.32MB
echo ByteUnits\bytes(132200)->format(); // outputs 132.20kB
// You can force the unit using the related suffix
echo ByteUnits\bytes(1322000)->format('MB'); // outputs 1.32MB
echo ByteUnits\bytes(1322000)->format('kB'); // outputs 1322.00kB
echo ByteUnits\bytes(1322000)->format('B'); // outputs 1322000B
// You can choose the precision aka the number of digits after the `.`
echo ByteUnits\bytes(1322123)->format(6); // outputs 1.322123MB
echo ByteUnits\bytes(1322123)->format('/6'); // outputs 1.322123MB
echo ByteUnits\bytes(1322123)->format('MB/6'); // outputs 1.322123MB
echo ByteUnits\bytes(1322123)->format('MB/000000'); // outputs 1.322123MB
echo ByteUnits\bytes(1322123)->format('GB/9'); // outputs 0.001322123GB
// You can specify a separator between then number and the units
echo ByteUnits\bytes(1322000)->format('MB', ' '); // outputs 1.32 MB
echo ByteUnits\bytes(1322000)->format('MB', '/'); // outputs 1.32/MB
// If you don't want to format but get the number of bytes
// NOTE: The output is a string to ensure that there's no overflow
echo ByteUnits\bytes(1322000)->numberOfBytes(); // outputs 1322000
```
### Compare
There are a few methods that could be used to compare bytes in various units and systems
```php
isLessThan(ByteUnits\Binary::kilobytes(1)); // it's true
ByteUnits\Metric::kilobytes(1)->isEqualTo(ByteUnits\Binary::bytes(1000)); // it's true
ByteUnits\Metric::kilobytes(1.3)->isGreaterThan(ByteUnits\Binary::kilobytes(1)); // it's true
```
### Manipulate
Also you can add or remove bytes in various units and systems
```php
remove(ByteUnits\Metric::kilobytes(1))->format(); // outputs 24B
// Arithmetic operations always preserves the receiving unit system
echo ByteUnits\Binary::kilobytes(1)->add(ByteUnits\Metric::kilobytes(1))->format(); // outputs 1.98KiB
// You cannot have negative bytes
ByteUnits\Metric::kilobytes(1)->remove(ByteUnits\Binary::kilobytes(1))->format(); // throws ByteUnits\NegativeBytesException
```
### Auto Boxing
Most of the methods can take integers or strings and box them to appropriate byte units
```php
ByteUnits\Metric::kilobytes(1)->isLessThan('1KiB'); // it's true
echo ByteUnits\Binary::kilobytes(1)->remove('1KiB')->format(); // outputs 24B
```
## Installation via [Composer](http://getcomposer.org/)
* Install Composer to your project root:
```bash
curl -sS https://getcomposer.org/installer | php
```
* Add a `composer.json` file to your project:
```json
{
"require": {
"gabrielelana/byte-units": "^0.5"
}
}
```
* Run the Composer installer:
```bash
php composer.phar install
```
## Self-Promotion
If you like this project, then consider to:
* Star the repository on [GitHub](https://github.com/gabrielelana/byte-units)
* Follow me on
* [Twitter](http://twitter.com/gabrielelana)
* [GitHub](https://github.com/gabrielelana)