{"id":21473039,"url":"https://github.com/scriptfusion/byteformatter","last_synced_at":"2025-04-05T08:07:24.694Z","repository":{"id":15801895,"uuid":"18541340","full_name":"ScriptFUSION/ByteFormatter","owner":"ScriptFUSION","description":":pencil2: Formats byte values as human-readable strings.","archived":false,"fork":false,"pushed_at":"2024-11-24T12:07:26.000Z","size":62,"stargazers_count":42,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T07:07:34.836Z","etag":null,"topics":["bytes","formatter","php-development"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ScriptFUSION.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-04-08T01:48:46.000Z","updated_at":"2025-03-18T13:20:47.000Z","dependencies_parsed_at":"2025-01-10T13:34:02.573Z","dependency_job_id":"b89520b2-e92f-43bf-bbd2-3f1a4e3a6f8e","html_url":"https://github.com/ScriptFUSION/ByteFormatter","commit_stats":{"total_commits":23,"total_committers":3,"mean_commits":7.666666666666667,"dds":"0.30434782608695654","last_synced_commit":"b89895b092e5bfcdfd892e81c8204e873e22acb7"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScriptFUSION%2FByteFormatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScriptFUSION%2FByteFormatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScriptFUSION%2FByteFormatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ScriptFUSION%2FByteFormatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ScriptFUSION","download_url":"https://codeload.github.com/ScriptFUSION/ByteFormatter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305934,"owners_count":20917208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bytes","formatter","php-development"],"created_at":"2024-11-23T10:14:25.699Z","updated_at":"2025-04-05T08:07:24.667Z","avatar_url":"https://github.com/ScriptFUSION.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"ByteFormatter\n=============\n\n[![Latest version][Version image]][Releases]\n[![Total downloads][Downloads image]][Downloads]\n[![Build status][Build image]][Build]\n[![Test coverage][Coverage image]][Coverage]\n[![Code style][Style image]][Style]\n\nByteFormatter formats byte values as human-readable strings. An appropriate exponent is calculated automatically such\nthat the value never exceeds the base. For example, in base 1024, `format(1023)` gives *1023 B* but `format(1024)` gives\n*1 KiB* instead of *1024 B*.\n\nUsage\n-----\n\nBy default, bytes are divided using `Base::BINARY` into multiples of 1024.\n\n```php\n(new ByteFormatter)-\u003eformat(0x80000);\n```\n\u003e 512 KiB\n\nBytes can be divided into multiples of 1000 by specifying `Base::DECIMAL` as the base.\n\n```php\n(new ByteFormatter)-\u003esetBase(Base::DECIMAL)-\u003eformat(500000);\n```\n\u003e 500 KB\n\nPrecision\n---------\n\nBy default, all values are rounded to the nearest integer.\n\n```php\n(new ByteFormatter)-\u003eformat(0x80233);\n```\n\u003e 513 KiB\n\nIncreasing the default precision with `setPrecision()` allows the specified number of digits after the decimal point.\n\n```php\n(new ByteFormatter)-\u003esetPrecision(2)-\u003eformat(0x80233);\n```\n\u003e 512.55 KiB\n\nIncreasing the precision will increase the maximum digits allowed but the formatter will only display as many as\nneeded.\n\n```php\n(new ByteFormatter)-\u003esetPrecision(2)-\u003eformat(0x80200);\n```\n\u003e 512.5 KiB\n\nAutomatic precision scaling can be disabled if this behaviour is undesired.\n\n```php\n(new ByteFormatter)-\u003esetPrecision(2)-\u003edisableAutomaticPrecision()-\u003eformat(0x80200);\n```\n\u003e 512.50 KiB\n\nThe default precision can be overridden by passing the second argument to `format()`.\n\n```php\n(new ByteFormatter)-\u003esetPrecision(2)-\u003eformat(0x80233, 4);\n```\n\u003e 512.5498 KiB\n\nOutput format\n-------------\n\nThe format can be changed by calling `setFormat()` which takes a string format parameter. The default format is\n`'%v %u'`. Occurrences of `%v` and `%u` in the format string will be replaced with the calculated *value* and *units*\nrespectively.\n\n```php\n(new ByteFormatter)-\u003esetFormat('%v%u')-\u003eformat(0x80000);\n```\n\u003e 512KiB\n\nFixed exponent\n--------------\n\nOne of the main benefits of the formatter is an appropriate exponent is calculated automatically, however it is also\npossible to fix the exponent to a specific value using `setFixedExponent()`.\n\n```php\n(new ByteFormatter)-\u003esetFixedExponent(1)-\u003eformat(1024 * 1024);\n```\n\u003e 1024 KiB\n\nNormally we would expect the above example to output `1 MiB` but because the exponent is locked to `1` the output will\nalways be in `KiB`. Consult the following table to see how exponents map to symbols.\n\n| Exponent | Symbol |\n|:--------:|:------:|\n|    0     |   B    |\n|    1     |   K    |\n|    2     |   M    |\n|    3     |   G    |\n|    4     |   T    |\n|    5     |   P    |\n|    6     |   E    |\n|    7     |   Z    |\n|    8     |   Y    |\n\nUnit customization\n------------------\n\nUnits are provided by decorators extending `UnitDecorator`. Two implementations are provided: the default\n`SymbolDecorator` and an optional `NameDecorator`.\n\nUnit decorators receive the base of the formatter when asked to decorate a value so that different units can be\nreturned for different bases. For example, the default decorator outputs `KiB` in base 1024 for\n*2\u003csup\u003e10\u003c/sup\u003e \u003c bytes \u003c 2\u003csup\u003e20\u003c/sup\u003e* but outputs `KB` in base 1000 for *1000 \u003c bytes \u003c 1000000*. This behaviour\ncan be suppressed by calling`SymbolDecorator::setSuffix()` with the desired `SymbolDecorator` suffix constant to\nprevent units changing when the base is changed. Decorators also receive the exponent and scaled byte value.\n\n### Symbol decorator\n\n`SymbolDecorator` is the default unit decorator and returns units like *B*, *KB*, *MB*, etc. The symbol's suffix can be\nchanged using one of the class constants from the following table.\n\n| Constant      | B |  K  |  M  |  G  |  T  |  P  |  E  |  Z  |  Y  |\n|---------------|:-:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|\n| SUFFIX_NONE   |   |  K  |  M  |  G  |  T  |  P  |  E  |  Z  |  Y  |\n| SUFFIX_METRIC | B |  KB |  MB |  GB |  TB |  PB |  EB |  ZB |  YB |\n| SUFFIX_IEC    | B | KiB | MiB | GiB | TiB | PiB | EiB | ZiB | YiB |\n\nThe following example uses base 1024 but displays the metric suffix, like Windows Explorer.\n\n```php\n(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_METRIC)))\n    -\u003eformat(0x80000)\n```\n\u003e 512 KB\n\nIf you prefer terse notation the suffix may be removed with `SUFFIX_NONE`.\n\n```php\n(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE)))\n    -\u003eformat(0x80000)\n```\n\u003e 512 K\n\nNote that no unit is displayed for bytes when the suffix is disabled. If this is undesired, byte units can be forced\nwith `SymbolDecorator::alwaysShowUnit()`.\n\n```php\n(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE)))\n    -\u003eformat(512)\n```\n\u003e 512\n\n```php\n(new ByteFormatter(\n    (new SymbolDecorator(SymbolDecorator::SUFFIX_NONE))\n        -\u003ealwaysShowUnit()\n))\n    -\u003eformat(512)\n```\n\u003e 512 B\n\n### Name decorator\n\n`NameDecorator` can be used to replace the default decorator and returns units like *byte*, *kilobyte*, *megabyte*,\netc.\n\n```php\n(new ByteFormatter(new NameDecorator))\n    -\u003eformat(0x80000)\n```\n\u003e 512 kibibytes\n\nUsing decimal base:\n\n```php\n(new ByteFormatter(new NameDecorator))\n    -\u003esetBase(Base::DECIMAL)\n    -\u003eformat(500000)\n```\n\u003e 500 kilobytes\n\nTesting\n-------\n\nThis library is fully unit tested. Run the tests with `composer test` from the command line. All examples\nin this document can be found in `DocumentationTest`.\n\n\n  [Releases]: https://github.com/ScriptFUSION/ByteFormatter/releases\n  [Version image]: https://poser.pugx.org/scriptfusion/byte-formatter/version \"Latest version\"\n  [Downloads]: https://packagist.org/packages/scriptfusion/byte-formatter\n  [Downloads image]: https://poser.pugx.org/scriptfusion/byte-formatter/downloads \"Total downloads\"\n  [Build]: https://github.com/ScriptFUSION/ByteFormatter/actions/workflows/Tests.yaml\n  [Build image]: https://github.com/ScriptFUSION/ByteFormatter/actions/workflows/Tests.yaml/badge.svg \"Build status\"\n  [Coverage]: https://coveralls.io/github/ScriptFUSION/ByteFormatter\n  [Coverage image]: https://coveralls.io/repos/ScriptFUSION/ByteFormatter/badge.svg \"Test coverage\"\n  [Style]: https://styleci.io/repos/18541340\n  [Style image]: https://styleci.io/repos/18541340/shield?style=flat \"Code style\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscriptfusion%2Fbyteformatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscriptfusion%2Fbyteformatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscriptfusion%2Fbyteformatter/lists"}