PHPackages scriptfusion/byte-formatter - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. scriptfusion/byte-formatter ActiveLibrary[Utility & Helpers](/categories/utility) scriptfusion/byte-formatter =========================== Formats byte values as human-readable strings. 4.2.1(8mo ago)43349.4k↑21.7%1[3 issues](https://github.com/ScriptFUSION/ByteFormatter/issues)6MITPHPPHP ^8CI failing Since Apr 8Pushed 8mo ago2 watchersCompare [ Source](https://github.com/ScriptFUSION/ByteFormatter)[ Packagist](https://packagist.org/packages/scriptfusion/byte-formatter)[ RSS](/packages/scriptfusion-byte-formatter/feed)WikiDiscussions master Synced 2w ago READMEChangelogDependencies (3)Versions (15)Used By (6) ByteFormatter ============= [](#byteformatter) [![Latest version](https://camo.githubusercontent.com/d7d34222b6ac84b65b3d52024b347dcaf86f5c3efc8b3d9fff7523dcebeace09/68747470733a2f2f706f7365722e707567782e6f72672f736372697074667573696f6e2f627974652d666f726d61747465722f76657273696f6e "Latest version")](https://github.com/ScriptFUSION/ByteFormatter/releases)[![Total downloads](https://camo.githubusercontent.com/3deef0fe88cda1c96bbcb3c9c02590d21381c819af1813167ba4d1aff3f45e1c/68747470733a2f2f706f7365722e707567782e6f72672f736372697074667573696f6e2f627974652d666f726d61747465722f646f776e6c6f616473 "Total downloads")](https://packagist.org/packages/scriptfusion/byte-formatter)[![Build status](https://github.com/ScriptFUSION/ByteFormatter/actions/workflows/Tests.yaml/badge.svg "Build status")](https://github.com/ScriptFUSION/ByteFormatter/actions/workflows/Tests.yaml)[![Test coverage](https://camo.githubusercontent.com/351bb886bf9a3e59d18b5ce2e207eeeb8d7e6f9fdd1749ed5796b32f2462a17b/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f536372697074465553494f4e2f42797465466f726d61747465722f62616467652e737667 "Test coverage")](https://coveralls.io/github/ScriptFUSION/ByteFormatter)[![Code style](https://camo.githubusercontent.com/96a41a6eced513c13413122d9af60a135e80c01ec72842ae907bb70142b89663/68747470733a2f2f7374796c6563692e696f2f7265706f732f31383534313334302f736869656c643f7374796c653d666c6174 "Code style")](https://styleci.io/repos/18541340) ByteFormatter formats byte values as human-readable strings. An appropriate exponent 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*. Usage ----- [](#usage) By default, bytes are divided using `Base::BINARY` into multiples of 1024. ``` (new ByteFormatter)->format(0x80000); ``` > 512 KiB Bytes can be divided into multiples of 1000 by specifying `Base::DECIMAL` as the base. ``` (new ByteFormatter)->setBase(Base::DECIMAL)->format(500000); ``` > 500 KB Precision --------- [](#precision) By default, all values are rounded to the nearest integer. ``` (new ByteFormatter)->format(0x80233); ``` > 513 KiB Increasing the default precision with `setPrecision()` allows the specified number of digits after the decimal point. ``` (new ByteFormatter)->setPrecision(2)->format(0x80233); ``` > 512.55 KiB Increasing the precision will increase the maximum digits allowed, but the formatter will only display as many as needed. ``` (new ByteFormatter)->setPrecision(2)->format(0x80200); ``` > 512.5 KiB Automatic precision scaling can be disabled if this behaviour is undesired. ``` (new ByteFormatter)->setPrecision(2)->disableAutomaticPrecision()->format(0x80200); ``` > 512.50 KiB The default precision can be overridden by passing the second argument to `format()`. ``` (new ByteFormatter)->setPrecision(2)->format(0x80233, 4); ``` > 512.5498 KiB Significant figures ------------------- [](#significant-figures) Formatting by the specified number of significant figures by calling `setSignificantFigures()`. This is mutually exclusive with precision scaling such that whichever method is called last will be used. ``` (new ByteFormatter)->setBase(Base::DECIMAL)->setSignificantFigures(2)->format(123); ``` > 120 ``` (new ByteFormatter)->setBase(Base::DECIMAL)->setSignificantFigures(2)->format(1234); ``` > 1.2K ``` (new ByteFormatter)->setBase(Base::DECIMAL)->setSignificantFigures(3)->format(1234); ``` > 1.23K This is particularly useful for keeping the display width of formatted numbers predicable. Output format ------------- [](#output-format) The format can be changed by calling `setFormat()` 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. ``` (new ByteFormatter)->setFormat('%v%u')->format(0x80000); ``` > 512KiB Fixed exponent -------------- [](#fixed-exponent) One of the main benefits of the formatter is an appropriate exponent is calculated automatically, however it is also possible to fix the exponent to a specific value using `setFixedExponent()`. ``` (new ByteFormatter)->setFixedExponent(1)->format(1024 * 1024); ``` > 1024 KiB Normally we would expect the above example to output `1 MiB` but because the exponent is locked to `1` the output will always be in `KiB`. Consult the following table to see how exponents map to symbols. ExponentSymbol0B1K2M3G4T5P6E7Z8YUnit customization ------------------ [](#unit-customization) Units are provided by decorators extending `UnitDecorator`. Two implementations are provided: the default `SymbolDecorator` and an optional `NameDecorator`. Unit decorators receive the base of the formatter when asked to decorate a value so that different units can be returned for different bases. For example, the default decorator outputs `KiB` in base 1024 for *210 < bytes < 220* but outputs `KB` in base 1000 for *1000 < bytes < 1000000*. This behaviour can be suppressed by calling`SymbolDecorator::setSuffix()` with the desired `SymbolDecorator` suffix constant to prevent units changing when the base is changed. Decorators also receive the exponent and scaled byte value. ### Symbol decorator [](#symbol-decorator) `SymbolDecorator` is the default unit decorator 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. ConstantBKMGTPEZYSUFFIX\_NONEKMGTPEZYSUFFIX\_METRICBKBMBGBTBPBEBZBYBSUFFIX\_IECBKiBMiBGiBTiBPiBEiBZiBYiBThe following example uses base 1024 but displays the metric suffix, like Windows Explorer. ``` (new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_METRIC))) ->format(0x80000) ``` > 512 KB If you prefer terse notation the suffix may be removed with `SUFFIX_NONE`. ``` (new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE))) ->format(0x80000) ``` > 512 K Note that no unit is displayed for bytes when the suffix is disabled. If this is undesired, byte units can be forced with `SymbolDecorator::alwaysShowUnit()`. ``` (new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE))) ->format(512) ``` > 512 ``` (new ByteFormatter( (new SymbolDecorator(SymbolDecorator::SUFFIX_NONE)) ->alwaysShowUnit() )) ->format(512) ``` > 512 B ### Name decorator [](#name-decorator) `NameDecorator` can be used to replace the default decorator and returns units like *byte*, *kilobyte*, *megabyte*, etc. ``` (new ByteFormatter(new NameDecorator)) ->format(0x80000) ``` > 512 kibibytes Using decimal base: ``` (new ByteFormatter(new NameDecorator)) ->setBase(Base::DECIMAL) ->format(500000) ``` > 500 kilobytes Testing ------- [](#testing) This library is fully unit tested. Run the tests with `composer test` from the command line. All examples in this document can be found in `DocumentationTest`. ### Health Score 53 — FairBetter than 96% of packages Maintenance59 Moderate activity, may be stable Popularity46 Moderate usage in the ecosystem Community20 Small or concentrated contributor base Maturity71 Established project with proven stability Bus Factor1 Top contributor holds 76.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~328 days Recently: every ~366 days Total 14 Last Release 245d ago Major Versions 1.0.0 → 2.0.02014-04-08 2.0.1 → 3.0.02015-12-30 3.3.0 → 4.0.02021-03-09 PHP version history (4 changes)1.0.0PHP >=5.5 3.3.0PHP ^5.5|^7 4.0.0PHP ^7.3|^8 4.1.0PHP ^8 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/470626?v=4)[Bilge](/maintainers/Bilge)[@Bilge](https://github.com/Bilge) --- Top Contributors [![Bilge](https://avatars.githubusercontent.com/u/470626?v=4)](https://github.com/Bilge "Bilge (23 commits)")[![okdana](https://avatars.githubusercontent.com/u/122095?v=4)](https://github.com/okdana "okdana (4 commits)")[![mpesari](https://avatars.githubusercontent.com/u/11061725?v=4)](https://github.com/mpesari "mpesari (3 commits)") --- Tags bytesformatterphp-development ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/scriptfusion-byte-formatter/health.svg) ``` [![Health](https://phpackages.com/badges/scriptfusion-byte-formatter/health.svg)](https://phpackages.com/packages/scriptfusion-byte-formatter) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)