Skip to content

Commit 00c8a00

Browse files
BilgeBilge
committed
Refactored ByteUnitCollection into Byte\Unit\Decorator.
1 parent 795e275 commit 00c8a00

21 files changed

+1173
-557
lines changed

‎.travis.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
sudo: false
2+
3+
language: php
4+
5+
php:
6+
- 5.5
7+
- 5.6
8+
- 7.0
9+
10+
before_install:
11+
- phpenv config-rm xdebug.ini
12+
13+
install:
14+
- composer -n selfupdate
15+
- composer -n --prefer-source install
16+
17+
script:
18+
- vendor/bin/phpunit test
19+
- vendor/bin/phpcs --standard=PSR2 src
20+
21+
notifications:
22+
email: false

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2015 Bilge <[email protected]>
3+
Copyright (c) 2016 Bilge <[email protected]>
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 59 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
ByteFormatter
22
=============
33

4-
ByteFormatter is a PHP library that formats byte values as human-readable strings. An appropriate scale is calculated automatically such that the value never exceeds the base. For example, in base 1024, `format(1023)` gives *1023 B* but `format(1024)` gives *1 KiB* instead of *1024 B*.
4+
[![Version][Version image]][Releases]
5+
[![Build status][Build image]][Build]
6+
7+
ByteFormatter is a [PSR-2](http://www.php-fig.org/psr/psr-2/) compliant PHP library that formats byte values as
8+
human-readable strings. An appropriate scale is calculated automatically such that the value never exceeds the base.
9+
For example, in base 1024, `format(1023)` gives *1023 B* but `format(1024)` gives *1 KiB* instead of *1024 B*.
510

611
Requirements
712
------------
8-
- PHP 5.5 for generator support.
9-
- 64-bit support is required if you want to work with terabytes or run the unit tests.
13+
14+
- PHP 5.5 and Composer.
15+
- Nothing else and no production dependencies!
1016

1117
Usage
1218
-----
@@ -27,6 +33,7 @@ Bytes can be divided into multiples of 1000 by specifying `Base::DECIMAL` as the
2733
2834
Precision
2935
---------
36+
3037
By default all values are rounded to the nearest integer.
3138

3239
```php
@@ -40,7 +47,8 @@ Increasing the precision with `setPrecision($precision)` allows the specified am
4047
```
4148
> 512.55 KiB
4249
43-
Increasing the precision will increase the maximum digits allowed but the formatter will only display as many as needed.
50+
Increasing the precision will increase the maximum digits allowed but the formatter will only display as many as
51+
needed.
4452

4553
```php
4654
(new ByteFormatter)->setPrecision(2)->format(0x80200);
@@ -49,22 +57,32 @@ Increasing the precision will increase the maximum digits allowed but the format
4957
5058
Output format
5159
-------------
52-
The format can be changed by calling the `setFormat($format)` function which takes a string format parameter. The default format is `'%v %u'`. Occurrences of `%v` and `%u` in the format string will be replaced with the calculated *value* and *units* respectively.
60+
61+
The format can be changed by calling the `setFormat($format)` function which takes a string format parameter.
62+
The default format is `'%v %u'`. Occurrences of `%v` and `%u` in the format string will be replaced with the calculated
63+
*value* and *units* respectively.
5364

5465
```php
5566
(new ByteFormatter)->setFormat('%v%u')->format(0x80000);
5667
```
5768
> 512KiB
5869
59-
Customizing units
60-
-----------------
61-
Units are provided by collections that extend `ByteUnitCollection`. The current unit collection instance can be retrieved from `ByteFormatter::getUnitCollection()`.
70+
Unit customization
71+
------------------
72+
73+
Units are provided by decorators extending `UnitDecorator`. Two implementations are provided: the default
74+
`SymbolDecorator` and an optional `NameDecorator`.
6275

63-
Unit collections are notified of base changes in the formatter so that different units can be returned for different bases. For example, the default collection outputs `KiB` in base 1024 for *2<sup>10</sup> < bytes < 2<sup>20</sup>* but outputs `KB` in base 1000 for *1000 < bytes < 1000000*. This behaviour can be suppressed by calling `disableAutomaticUnitSwitching(true)` to prevent units changing when the base is changed.
76+
Unit decorators receive the base of the formatter when asked to decorate a value so that different units can be
77+
returned for different bases. For example, the default decorator outputs `KiB` in base 1024 for
78+
*2<sup>10</sup> < bytes < 2<sup>20</sup>* but outputs `KB` in base 1000 for *1000 < bytes < 1000000*. This behaviour
79+
can be suppressed by calling`SymbolDecorator::setSuffix()` with the desired `SymbolDecorator` suffix constant to
80+
prevent units changing when the base is changed. Decorators also receive the exponent and scaled byte value.
6481

65-
### Symbol collection
82+
### Symbol decorator
6683

67-
`ByteUnitSymbolCollection` is the default unit collection and returns units like *B*, *KB*, *MB*, etc. The symbol's suffix can be changed using one of the class constants from the following table.
84+
`SymbolDecorator` is the default unit decorator and returns units like *B*, *KB*, *MB*, etc. The symbol's suffix can be
85+
changed using one of the class constants from the following table.
6886

6987
| Constant | B | K | M | G | T | P | E | Z | Y |
7088
|---------------|:-:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
@@ -75,57 +93,65 @@ Unit collections are notified of base changes in the formatter so that different
7593
The following example uses base 1024 but displays the metric suffix, like Windows Explorer.
7694

7795
```php
78-
(new ByteFormatter)
79-
->setBase(Base::BINARY)
80-
->setUnitSymbolSuffix(ByteUnitSymbolCollection::SUFFIX_METRIC)
81-
->format(0x80000);
96+
(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_METRIC)))
97+
->format(0x80000)
8298
```
8399
> 512 KB
84100
85101
If you prefer terse notation the suffix may be removed with `SUFFIX_NONE`.
86102

87103
```php
88-
(new ByteFormatter)
89-
->setUnitSymbolSuffix(ByteUnitSymbolCollection::SUFFIX_NONE)
90-
->format(0x80000);
104+
(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE)))
105+
->format(0x80000)
91106
```
92107
> 512 K
93108
94-
Note that no unit is displayed for bytes when the suffix is disabled. If this is undesired, byte units can be forced with `ByteUnitSymbolCollection::alwaysShowUnit()`.
109+
Note that no unit is displayed for bytes when the suffix is disabled. If this is undesired, byte units can be forced
110+
with `SymbolDecorator::alwaysShowUnit()`.
95111

96112
```php
97-
$formatter = (new ByteFormatter)
98-
->setUnitSymbolSuffix(ByteUnitSymbolCollection::SUFFIX_NONE)
99-
->format(512);
113+
(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE)))
114+
->format(512)
100115
```
101116
> 512
102117
103118
```php
104-
$formatter->getUnitCollection()->alwaysShowUnit();
105-
$formatter->format(512);
119+
(new ByteFormatter(
120+
(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE))
121+
->alwaysShowUnit()
122+
))
123+
->format(512)
106124
```
107125
> 512 B
108126
109-
### Name collection
110-
`ByteUnitNameCollection` can be used to replace the default collection and returns units like *byte*, *kilobyte*, *megabyte*, etc.
127+
### Name decorator
128+
129+
`NameDecorator` can be used to replace the default decorator and returns units like *byte*, *kilobyte*, *megabyte*,
130+
etc.
111131

112132
```php
113-
(new ByteFormatter)
114-
->setUnitCollection(new ByteUnitNameCollection)
115-
->format(0x80000);
133+
(new ByteFormatter(new NameDecorator))
134+
->format(0x80000)
116135
```
117136
> 512 kibibytes
118137
119138
Using decimal base:
120139

121140
```php
122-
(new ByteFormatter)
123-
->setUnitCollection(new ByteUnitNameCollection)
141+
(new ByteFormatter(new NameDecorator))
124142
->setBase(Base::DECIMAL)
125-
->format(500000);
143+
->format(500000)
126144
```
127145
> 500 kilobytes
128146
129147
Testing
130148
-------
131-
This library is fully unit tested. Run the tests with `vendor/bin/phpunit test/` from the command line.
149+
150+
This library is fully unit tested. Run the tests with `vendor/bin/phpunit test` from the command line. All the examples
151+
in this file can be found in `DocumentationTest`.
152+
153+
[Releases]: https://github.com/ScriptFUSION/ByteFormatter/releases
154+
[Version image]: http://img.shields.io/github/tag/ScriptFUSION/ByteFormatter.svg "Latest version"
155+
[Build]: http://travis-ci.org/ScriptFUSION/ByteFormatter
156+
[Build image]: http://img.shields.io/travis/ScriptFUSION/ByteFormatter.svg "Build status"
157+

‎composer.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
{
22
"name": "scriptfusion/byte-formatter",
33
"description": "Formats byte values as human-readable strings.",
4+
"license": "MIT",
45
"authors": [
56
{
67
"name": "Bilge",
78
"email": "[email protected]"
89
}
910
],
10-
"license": "MIT",
1111
"autoload": {
1212
"psr-4": {
1313
"ScriptFUSION\\": "src"
@@ -17,6 +17,8 @@
1717
"php": ">=5.5"
1818
},
1919
"require-dev": {
20-
"phpunit/phpunit": "*"
20+
"phpunit/phpunit": "^4",
21+
"mockery/mockery": "^0",
22+
"squizlabs/php_codesniffer": "^2"
2123
}
2224
}

0 commit comments

Comments
 (0)