tez-utils-num/README.md

tez-utils-num

PHP number utilities: formatting, byte sizes, percentage, clamping, and rounding helpers (Num), plus arbitrary-precision decimal arithmetic via bcmath (Bc). PHP 8.3+, requires ext-bcmath.

Installation

composer require tez/utils-num

Components

Class	Purpose
Num	Formatting, byte sizes, percentages, clamping, rounding
Bc	Arbitrary-precision decimal arithmetic wrapping ext-bcmath

---

Num

Formatting and rounding helpers for everyday number display.

format()

use Tez\Utils\Num\Num;

Num::format(1234567.891);                              // '1,234,567.89'
Num::format(1234567.891, dec: ',', thousands: '.');    // '1.234.567,89'
Num::format(1234.5, decimals: 0);                      // '1,235'
Num::format(-1000.0);                                  // '-1,000.00'

bytes()

Converts a byte count to a human-readable string using binary units (1 KB = 1 024 B).

Num::bytes(0);           // '0 B'
Num::bytes(1023);        // '1,023 B'
Num::bytes(1024);        // '1.00 KB'
Num::bytes(1048576);     // '1.00 MB'
Num::bytes(1073741824);  // '1.00 GB'
Num::bytes(1024 ** 4);   // '1.00 TB'
Num::bytes(1500, precision: 0); // '1 KB'

percent()

Formats a ratio (0.0–1.0) as a percentage string.

Num::percent(0.1234);              // '12.3%'
Num::percent(1.0);                 // '100.0%'
Num::percent(0.0056, decimals: 2); // '0.56%'

clamp()

Constrains a value to the inclusive range [$min, $max].

Num::clamp(105, 0, 100);   // 100
Num::clamp(-5,  0, 100);   // 0
Num::clamp(50,  0, 100);   // 50
Num::clamp(1.5, 0.0, 0.5); // 0.5

roundTo()

Rounds a value to the nearest multiple of $multiple.

Num::roundTo(17, 5);   // 15
Num::roundTo(18, 5);   // 20
Num::roundTo(1.7, 0.5); // 1.5

---

Bc

Arbitrary-precision decimal arithmetic wrapping PHP's bcmath extension. Designed for financial calculations where floating-point imprecision is not acceptable.

All inputs must be numeric strings (e.g. '1.50000000'). Passing a non-numeric string throws \InvalidArgumentException. Division by zero throws \DivisionByZeroError.

The default scale is 8 decimal places for all methods.

Arithmetic

use Tez\Utils\Num\Bc;

Bc::add('10.5', '20.3');          // '30.80000000'
Bc::sub('20.3', '11.1');          // '9.20000000'
Bc::mul('4', '5');                 // '20.00000000'
Bc::div('1', '3');                 // '0.33333333'
Bc::div('1', '3', scale: 2);      // '0.33'

// Array operations
Bc::sum(['1', '2', '3']);          // '6.00000000'
Bc::sum([]);                       // '0.00000000'
Bc::product(['2', '3', '4']);      // '24.00000000'
Bc::product([]);                   // '1.00000000'
Bc::subAll(['10', '3', '2']);      // '5.00000000'  (10 - 3 - 2)
Bc::divAll(['100', '5', '4']);     // '5.00000000'  (100 / 5 / 4)

Utilities

Bc::abs('-5');                     // '5.00000000'
Bc::negate('3.14');                // '-3.14000000'
Bc::negate('-5');                  // '5.00000000'
Bc::max('10', '5');                // '10.00000000'
Bc::min('10', '3');                // '3.00000000'
Bc::scale('1.5');                  // '1.50000000'  — normalize to 8 decimal places
Bc::scale('1.123456789');          // '1.12345678'  — truncates, does not round
Bc::percent('200', '15');          // '30.00000000' — 15% of 200

Comparisons

Bc::compare('10', '5');    // 1   (greater)
Bc::compare('5', '10');    // -1  (less)
Bc::compare('5.00', '5'); // 0   (equal)

Bc::eq('5.00', '5.000');   // true
Bc::gt('10', '5');          // true
Bc::lt('3', '7');           // true
Bc::gte('5', '5');          // true
Bc::lte('3', '7');          // true

Bc::isZero('0.00000000');   // true
Bc::isZero('0.00000001');   // false
Bc::isPositive('0.00000001'); // true
Bc::isNegative('-0.00000001'); // true

Scale behaviour

Bc::scale() truncates (does not round). All arithmetic methods default to scale 8 and accept an explicit scale parameter:

Bc::add('10.5', '20.3', scale: 2); // '30.80'
Bc::div('1', '3', scale: 4);       // '0.3333'

// Equal at scale 2, different at scale 8
Bc::eq('5.001', '5.009', scale: 2); // true
Bc::eq('5.001', '5.009');           // false

---

Requirements

• PHP 8.3+
• ext-bcmath
• tez/utils-validate ^1.0

License

MIT