Money Bugs: Currency, Rounding, Discounts and VAT

var_dump(0.1 + 0.2 === 0.3);   // bool(false)
$cart = 0.0;
foreach (array_fill(0, 10, 0.1) as $price) { $cart += $price; }
var_dump($cart);               // float(0.9999999999999999)
var_dump($cart === 1.0);       // bool(false)

final class Money
{
    private const EXPONENTS = [
        'EGP' => 2, 'USD' => 2, 'EUR' => 2, 'SAR' => 2,
        'KWD' => 3, 'BHD' => 3, 'JPY' => 0,
    ];

    // amounts stay far below PHP_INT_MAX even after tax/mul arithmetic
    private const MAX_MINOR = 1_000_000_000_000;

    private function __construct(
        public readonly int $minor,      // amount in smallest units, nonnegative
        public readonly string $currency // ISO 4217
    ) {}

    public static function of(string $amount, string $currency): self
    {
        if (!isset(self::EXPONENTS[$currency])) {
            throw new InvalidArgumentException("unsupported currency $currency");
        }
        $amount = trim($amount);
        if (!preg_match('/^\d+(\.\d+)?$/', $amount)) {
            throw new InvalidArgumentException("not a nonnegative decimal string: $amount");
        }
        [$i, $f] = array_pad(explode('.', $amount, 2), 2, '');
        $exp = self::EXPONENTS[$currency];
        if (strlen($f) > $exp) {
            throw new InvalidArgumentException("too many decimal places for $currency");
        }
        // compare the normalized minor-unit digit string BEFORE any (int) cast,
        // so arbitrarily long inputs are rejected instead of overflowing/saturating
        $digits = ltrim(ltrim($i, '0') . str_pad($f, $exp, '0'), '0');
        $max = (string) self::MAX_MINOR;
        if (strlen($digits) > strlen($max) || (strlen($digits) === strlen($max) && $digits > $max)) {
            throw new InvalidArgumentException('amount out of supported range');
        }
        return new self($digits === '' ? 0 : (int)$digits, $currency);
    }

    public function add(self $o): self
    {
        if ($o->currency !== $this->currency) {
            throw new LogicException('currency mismatch - convert first');
        }
        if ($this->minor > self::MAX_MINOR - $o->minor) {
            throw new LogicException('amount out of supported range');
        }
        return new self($this->minor + $o->minor, $this->currency);
    }

    public function mul(int $qty): self
    {
        if ($qty < 0) {
            throw new InvalidArgumentException('quantity must be nonnegative');
        }
        if ($qty > 0 && $this->minor > intdiv(self::MAX_MINOR, $qty)) {
            throw new LogicException('amount out of supported range');
        }
        return new self($this->minor * $qty, $this->currency);
    }

    public function taxBps(int $bps): self
    {
        // $bps in basis points: 1400 = 14.00%. Half-up, per line, integer only.
        if ($bps < 0 || $bps > 100_000) {
            throw new InvalidArgumentException('basis points out of range');
        }
        if ($this->minor > intdiv(PHP_INT_MAX - 5000, max(1, $bps))) {
            throw new LogicException('amount out of supported range');
        }
        $tax = intdiv($this->minor * $bps + 5000, 10000);
        if ($tax > self::MAX_MINOR) {
            throw new LogicException('amount out of supported range');
        }
        return new self($tax, $this->currency);
    }

    public function format(): string
    {
        $exp = self::EXPONENTS[$this->currency];
        $i = intdiv($this->minor, 10 ** $exp);
        $f = $exp ? '.' . str_pad((string)($this->minor % 10 ** $exp), $exp, '0') : '';
        return $i . $f . ' ' . $this->currency;
    }
}

function roundHalfUp(int $m3): int
{
    if ($m3 < 0 || $m3 > PHP_INT_MAX - 1000) {
        throw new InvalidArgumentException('milliunits out of supported range');
    }
    return intdiv($m3 + 500, 1000);
}

function roundHalfEven(int $m3): int
{
    if ($m3 < 0) {
        throw new InvalidArgumentException('milliunits must be nonnegative');
    }
    $q = intdiv($m3, 1000);
    $r = $m3 % 1000;
    if ($r > 500 || ($r === 500 && $q % 2 === 1)) { $q++; }
    return $q;
}

function roundDown(int $m3): int
{
    if ($m3 < 0) {
        throw new InvalidArgumentException('milliunits must be nonnegative');
    }
    return intdiv($m3, 1000);
}

function roundUp(int $m3): int
{
    if ($m3 < 0 || $m3 > PHP_INT_MAX - 1000) {
        throw new InvalidArgumentException('milliunits out of supported range');
    }
    return intdiv($m3 + 999, 1000);
}

function splitDiscount(array $lineMinors, int $discountMinor): array
{
    if ($discountMinor < 0) {
        throw new InvalidArgumentException('discount must be nonnegative');
    }
    if (!array_is_list($lineMinors)) {
        throw new InvalidArgumentException('line amounts must be a list (tie order is insertion order)');
    }
    $total = 0;
    foreach ($lineMinors as $m) {
        if (!is_int($m) || $m <= 0 || $m > 1_000_000_000_000) {
            throw new InvalidArgumentException('line amounts must be positive integers in range');
        }
        if ($m > PHP_INT_MAX - $total) {
            throw new LogicException('subtotal out of supported range');
        }
        $total += $m;
    }
    if ($total === 0) {
        throw new InvalidArgumentException('line subtotal must be positive');
    }
    if ($discountMinor > $total) {
        throw new InvalidArgumentException('discount cannot exceed subtotal');
    }
    $biggest = max($lineMinors);
    if ($discountMinor > 0 && $discountMinor > intdiv(PHP_INT_MAX, $biggest)) {
        throw new LogicException('amounts out of supported range');
    }
    $shares = []; $remainders = []; $assigned = 0;
    foreach ($lineMinors as $i => $m) {
        $shares[$i] = intdiv($discountMinor * $m, $total);    // floor, integer only
        $remainders[$i] = ($discountMinor * $m) % $total;     // integer remainder
        $assigned += $shares[$i];
    }
    $left = $discountMinor - $assigned; // always < count(lines)
    // deterministic: biggest remainder first, ties broken by line order
    $order = array_keys($remainders);
    usort($order, fn($a, $b) => $remainders[$b] <=> $remainders[$a] ?: $a <=> $b);
    foreach ($order as $i) {
        if ($left <= 0) break;
        $shares[$i]++; $left--;
    }
    return $shares;
}