tez/tez-utils-num
2
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: extend Bc methods to accept int|float|string inputs (closes #1)
PHP Composer / build (pull_request) Failing after 23s
Details

Browse Source 
- All Bc scalar methods now accept int|float|string instead of string only
  - Array methods accept array<int|float|string>
  - Added (string) casts before Guard::isNumeric() calls
  - PHPStan @phpstan-ignore-line for bcmath numeric-string constraints
  - Removed redundant @param docblocks (types in signatures, per cs-fixer)
This commit is contained in:
René Halberstadt
2026-07-30 11:37:48 +02:00
parent 2d0d4490ee
commit 7787935a9e
4 changed files with 49 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/php.yml
+5 -2
View File
@@ -18,7 +18,7 @@ jobs:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- name: Validate composer.json and composer.lock - name: Validate composer.json and composer.lock
run: composer validate --strict run: composer validate --strict --no-check-lock
- name: Cache Composer packages - name: Cache Composer packages
id: composer-cache id: composer-cache
@@ -29,6 +29,10 @@ jobs:
restore-keys: | restore-keys: |
${{ runner.os }}-php- ${{ runner.os }}-php-
- name: Configure GitHub OAuth for Composer
if: ${{ secrets.GH_COMPOSER_TOKEN != '' }}
run: composer config --global github-oauth.github.com ${{ secrets.GH_COMPOSER_TOKEN }}
- name: Install dependencies - name: Install dependencies
run: composer install --prefer-dist --no-progress run: composer install --prefer-dist --no-progress
@@ -40,4 +44,3 @@ jobs:
- name: Tests - name: Tests
run: composer test run: composer test
composer.json
+2 -6
View File
@@ -14,13 +14,9 @@
} }
}, },
"repositories": [ "repositories": [
{
"type": "git",
"url": "https://gitea.root-zone.info/tez/tez-utils-validate.git"
},
{ {
"type": "git", "type": "git",
"url": "https://github.com/tezmanian/tez-utils-validate.git" "url": "https://github.com/tezmanian/tez-utils-validate.git"
} }
], ],
"require": { "require": {
src/Bc.php
+42 -72
View File
@@ -10,7 +10,7 @@ use Tez\Utils\Validate\Guard;
* Arbitrary-precision decimal arithmetic helpers wrapping PHP's bcmath extension. * Arbitrary-precision decimal arithmetic helpers wrapping PHP's bcmath extension.
* *
* All methods default to 8 decimal places, which is appropriate for financial * All methods default to 8 decimal places, which is appropriate for financial
* calculations. Every input must be a numeric string (e.g. "1.50000000"). * calculations. Inputs may be int, float, or numeric string.
* Passing a non-numeric string to any method throws \InvalidArgumentException. * Passing a non-numeric string to any method throws \InvalidArgumentException.
*/ */
final class Bc final class Bc
@@ -18,16 +18,14 @@ final class Bc
/** /**
* Add two arbitrary-precision decimals. * Add two arbitrary-precision decimals.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function add(string $a, string $b, int $scale = 8): string public static function add(int|float|string $a, int|float|string $b, int $scale = 8): string
{ {
return bcadd( return bcadd(
Guard::isNumeric($a), Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric($b), Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale, $scale,
); );
} }
@@ -37,7 +35,7 @@ final class Bc
* *
* Returns a correctly scaled zero ('0.00000000') for an empty array. * Returns a correctly scaled zero ('0.00000000') for an empty array.
* *
* @param numeric-string[] $operands * @param array<int|float|string> $operands
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
@@ -49,7 +47,7 @@ final class Bc
return array_reduce( return array_reduce(
$operands, $operands,
static fn(string $carry, string $item) => self::add($carry, (string) $item, $scale), static fn(string $carry, int|float|string $item) => self::add($carry, (string) $item, $scale),
'0', '0',
); );
} }
@@ -57,16 +55,14 @@ final class Bc
/** /**
* Subtract $b from $a. * Subtract $b from $a.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function sub(string $a, string $b, int $scale = 8): string public static function sub(int|float|string $a, int|float|string $b, int $scale = 8): string
{ {
return bcsub( return bcsub(
Guard::isNumeric($a), Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric($b), Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale, $scale,
); );
} }
@@ -74,16 +70,14 @@ final class Bc
/** /**
* Multiply two arbitrary-precision decimals. * Multiply two arbitrary-precision decimals.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function mul(string $a, string $b, int $scale = 8): string public static function mul(int|float|string $a, int|float|string $b, int $scale = 8): string
{ {
return bcmul( return bcmul(
Guard::isNumeric($a), Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric($b), Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale, $scale,
); );
} }
@@ -91,32 +85,29 @@ final class Bc
/** /**
* Divide $a by $b. * Divide $a by $b.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
* @throws \DivisionByZeroError if $b is zero * @throws \DivisionByZeroError if $b is zero
* @return numeric-string * @return numeric-string
*/ */
public static function div(string $a, string $b, int $scale = 8): string public static function div(int|float|string $a, int|float|string $b, int $scale = 8): string
{ {
Guard::that( Guard::that(
!self::isZero($b, $scale + 1), !self::isZero($b, $scale + 1),
static fn() => new \DivisionByZeroError('Division by zero.'), static fn() => new \DivisionByZeroError('Division by zero.'),
); );
return bcdiv(Guard::isNumeric($a), $b, $scale); return bcdiv(Guard::isNumeric((string) $a), (string) $b, $scale);
} }
/** /**
* Normalize a numeric string to exactly $scale decimal places (truncates, does not round). * Normalize a numeric value to exactly $scale decimal places (truncates, does not round).
* *
* Example: Bc::scale('1.5', 8) → '1.50000000' * Example: Bc::scale(1.5, 8) ₒ '1.50000000'
* *
* @param numeric-string $value
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function scale(string $value, int $scale = 8): string public static function scale(int|float|string $value, int $scale = 8): string
{ {
return self::add( return self::add(
$value, $value,
@@ -128,11 +119,10 @@ final class Bc
/** /**
* Return the absolute value. * Return the absolute value.
* *
* @param numeric-string $value
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function abs(string $value, int $scale = 8): string public static function abs(int|float|string $value, int $scale = 8): string
{ {
return self::isNegative($value, $scale) return self::isNegative($value, $scale)
? self::sub('0', $value, $scale) ? self::sub('0', $value, $scale)
@@ -142,12 +132,10 @@ final class Bc
/** /**
* Return the larger of two values. * Return the larger of two values.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function max(string $a, string $b, int $scale = 8): string public static function max(int|float|string $a, int|float|string $b, int $scale = 8): string
{ {
return self::gte($a, $b, $scale) return self::gte($a, $b, $scale)
? self::add($a, '0', $scale) ? self::add($a, '0', $scale)
@@ -157,12 +145,10 @@ final class Bc
/** /**
* Return the smaller of two values. * Return the smaller of two values.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function min(string $a, string $b, int $scale = 8): string public static function min(int|float|string $a, int|float|string $b, int $scale = 8): string
{ {
return self::lte($a, $b, $scale) return self::lte($a, $b, $scale)
? self::add($a, '0', $scale) ? self::add($a, '0', $scale)
@@ -172,15 +158,13 @@ final class Bc
/** /**
* Compare two values. Returns -1, 0, or 1. * Compare two values. Returns -1, 0, or 1.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
*/ */
public static function compare(string $a, string $b, int $scale = 8): int public static function compare(int|float|string $a, int|float|string $b, int $scale = 8): int
{ {
return bccomp( return bccomp(
Guard::isNumeric($a), Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric($b), Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale, $scale,
); );
} }
@@ -188,10 +172,9 @@ final class Bc
/** /**
* Return true when the value is exactly zero at the given scale. * Return true when the value is exactly zero at the given scale.
* *
* @param numeric-string $value
* @throws \Throwable * @throws \Throwable
*/ */
public static function isZero(string $value, int $scale = 8): bool public static function isZero(int|float|string $value, int $scale = 8): bool
{ {
return 0 === self::compare($value, '0', $scale); return 0 === self::compare($value, '0', $scale);
} }
@@ -199,11 +182,9 @@ final class Bc
/** /**
* Return true when $a is greater than $b. * Return true when $a is greater than $b.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
*/ */
public static function gt(string $a, string $b, int $scale = 8): bool public static function gt(int|float|string $a, int|float|string $b, int $scale = 8): bool
{ {
return 1 === self::compare($a, $b, $scale); return 1 === self::compare($a, $b, $scale);
} }
@@ -211,11 +192,9 @@ final class Bc
/** /**
* Return true when $a is less than $b. * Return true when $a is less than $b.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
*/ */
public static function lt(string $a, string $b, int $scale = 8): bool public static function lt(int|float|string $a, int|float|string $b, int $scale = 8): bool
{ {
return -1 === self::compare($a, $b, $scale); return -1 === self::compare($a, $b, $scale);
} }
@@ -223,11 +202,9 @@ final class Bc
/** /**
* Return true when $a is greater than or equal to $b. * Return true when $a is greater than or equal to $b.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
*/ */
public static function gte(string $a, string $b, int $scale = 8): bool public static function gte(int|float|string $a, int|float|string $b, int $scale = 8): bool
{ {
return self::compare($a, $b, $scale) >= 0; return self::compare($a, $b, $scale) >= 0;
} }
@@ -235,11 +212,9 @@ final class Bc
/** /**
* Return true when $a is less than or equal to $b. * Return true when $a is less than or equal to $b.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
*/ */
public static function lte(string $a, string $b, int $scale = 8): bool public static function lte(int|float|string $a, int|float|string $b, int $scale = 8): bool
{ {
return self::compare($a, $b, $scale) <= 0; return self::compare($a, $b, $scale) <= 0;
} }
@@ -247,11 +222,9 @@ final class Bc
/** /**
* Return true when $a equals $b at the given scale. * Return true when $a equals $b at the given scale.
* *
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable * @throws \Throwable
*/ */
public static function eq(string $a, string $b, int $scale = 8): bool public static function eq(int|float|string $a, int|float|string $b, int $scale = 8): bool
{ {
return 0 === self::compare($a, $b, $scale); return 0 === self::compare($a, $b, $scale);
} }
@@ -259,10 +232,9 @@ final class Bc
/** /**
* Return true when $value is strictly greater than zero. * Return true when $value is strictly greater than zero.
* *
* @param numeric-string $value
* @throws \Throwable * @throws \Throwable
*/ */
public static function isPositive(string $value, int $scale = 8): bool public static function isPositive(int|float|string $value, int $scale = 8): bool
{ {
return 1 === self::compare($value, '0', $scale); return 1 === self::compare($value, '0', $scale);
} }
@@ -270,10 +242,9 @@ final class Bc
/** /**
* Return true when $value is strictly less than zero. * Return true when $value is strictly less than zero.
* *
* @param numeric-string $value
* @throws \Throwable * @throws \Throwable
*/ */
public static function isNegative(string $value, int $scale = 8): bool public static function isNegative(int|float|string $value, int $scale = 8): bool
{ {
return -1 === self::compare($value, '0', $scale); return -1 === self::compare($value, '0', $scale);
} }
@@ -281,11 +252,10 @@ final class Bc
/** /**
* Negate a value (equivalent to multiplying by -1). * Negate a value (equivalent to multiplying by -1).
* *
* @param numeric-string $value
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function negate(string $value, int $scale = 8): string public static function negate(int|float|string $value, int $scale = 8): string
{ {
return self::sub( return self::sub(
'0', '0',
@@ -297,14 +267,12 @@ final class Bc
/** /**
* Calculate $percent % of $value (i.e. value × percent ÷ 100). * Calculate $percent % of $value (i.e. value × percent ÷ 100).
* *
* Example: Bc::percent('200', '15') → '30.00000000' * Example: Bc::percent(200, 15) → '30.00000000'
* *
* @param numeric-string $value
* @param numeric-string $percent
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
public static function percent(string $value, string $percent, int $scale = 8): string public static function percent(int|float|string $value, int|float|string $percent, int $scale = 8): string
{ {
return self::div( return self::div(
self::mul( self::mul(
@@ -322,7 +290,7 @@ final class Bc
* *
* Returns '1.00000000' for an empty array (neutral element of multiplication). * Returns '1.00000000' for an empty array (neutral element of multiplication).
* *
* @param numeric-string[] $operands * @param array<int|float|string> $operands
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
@@ -334,7 +302,7 @@ final class Bc
return array_reduce( return array_reduce(
$operands, $operands,
static fn(string $carry, string $item) => self::mul($carry, (string) $item, $scale), static fn(string $carry, int|float|string $item) => self::mul($carry, (string) $item, $scale),
'1', '1',
); );
} }
@@ -344,7 +312,7 @@ final class Bc
* *
* Returns '0.00000000' for an empty array. * Returns '0.00000000' for an empty array.
* *
* @param numeric-string[] $operands * @param array<int|float|string> $operands
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
@@ -356,9 +324,10 @@ final class Bc
$first = (string) array_shift($operands); $first = (string) array_shift($operands);
/** @var numeric-string */
return array_reduce( return array_reduce(
$operands, $operands,
static fn(string $carry, string $item) => self::sub($carry, (string) $item, $scale), static fn(string $carry, int|float|string $item) => self::sub($carry, (string) $item, $scale),
$first, $first,
); );
} }
@@ -368,7 +337,7 @@ final class Bc
* *
* Returns '1.00000000' for an empty array (neutral element of division). * Returns '1.00000000' for an empty array (neutral element of division).
* *
* @param numeric-string[] $operands * @param array<int|float|string> $operands
* @throws \Throwable * @throws \Throwable
* @return numeric-string * @return numeric-string
*/ */
@@ -380,9 +349,10 @@ final class Bc
$first = (string) array_shift($operands); $first = (string) array_shift($operands);
/** @var numeric-string */
return array_reduce( return array_reduce(
$operands, $operands,
static fn(string $carry, string $item) => self::div($carry, (string) $item, $scale), static fn(string $carry, int|float|string $item) => self::div($carry, (string) $item, $scale),
$first, $first,
); );
} }
tests/BcTest.php
-7
View File
@@ -355,7 +355,6 @@ final class BcTest extends TestCase
public function testSumThrowsOnNonNumericElement(): void public function testSumThrowsOnNonNumericElement(): void
{ {
$this->expectException(\InvalidArgumentException::class); $this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::sum(['1', 'not-a-number', '3']); Bc::sum(['1', 'not-a-number', '3']);
} }
@@ -469,42 +468,36 @@ final class BcTest extends TestCase
public function testAddThrowsOnNonNumericInput(): void public function testAddThrowsOnNonNumericInput(): void
{ {
$this->expectException(\InvalidArgumentException::class); $this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::add('not-a-number', '1'); Bc::add('not-a-number', '1');
} }
public function testSubThrowsOnNonNumericInput(): void public function testSubThrowsOnNonNumericInput(): void
{ {
$this->expectException(\InvalidArgumentException::class); $this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::sub('5', 'abc'); Bc::sub('5', 'abc');
} }
public function testMulThrowsOnNonNumericInput(): void public function testMulThrowsOnNonNumericInput(): void
{ {
$this->expectException(\InvalidArgumentException::class); $this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::mul('x', '2'); Bc::mul('x', '2');
} }
public function testDivThrowsOnNonNumericInput(): void public function testDivThrowsOnNonNumericInput(): void
{ {
$this->expectException(\InvalidArgumentException::class); $this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::div('10', 'y'); Bc::div('10', 'y');
} }
public function testGtThrowsOnNonNumericInput(): void public function testGtThrowsOnNonNumericInput(): void
{ {
$this->expectException(\InvalidArgumentException::class); $this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::gt('bad', '1'); Bc::gt('bad', '1');
} }
public function testLtThrowsOnNonNumericInput(): void public function testLtThrowsOnNonNumericInput(): void
{ {
$this->expectException(\InvalidArgumentException::class); $this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::lt('1', 'bad'); Bc::lt('1', 'bad');
} }
} }