Money.php

<?php

namespace MatchBot\Domain;

use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\Embeddable;
use MatchBot\Application\Assertion;

/**
 * (not using PHP native readonly as ORM will replace properties during hydration)
 * @psalm-immutable
 */
#[Embeddable]
class Money implements \JsonSerializable, \Stringable
{
    /**
     * @var numeric-string
     */
    #[Column(type: 'bigint')]
    private string $amountInPence;

    /**
     * @param numeric-string $amountInPence - Amount of money in minor units, i.e. pence, assumed to be worth 1/100 of the major
     * unit. Has upper limit set above what we expect to ever deal with on a single account. Must not be `int` while
     * {@link https://github.com/doctrine/orm/issues/11721} is unresolved.
     * @param Currency $currency
     */
    private function __construct(
        string $amountInPence,
        #[Column(length: 3)]
        public Currency $currency
    ) {
        Assertion::regex($amountInPence, '/^-?\d+(?:\.00)?$/', 'Amount in pence must be an integer or have .00 decimal');

        // casting to int and then back to string to get rid of any trailing '.00', just required so that two instances
        // for the same amount match internally when checked by phpunit.
        $this->amountInPence = (string)(int)$amountInPence;
        // Almost 10 trillion £ is well Over the Max. fund value we use in regtest Salesforce sandboxes - these have very high sums of fictional money to allow continous automated donations for a long time.
        // other envs of course don't use use sums anywhere near this big.
        Assertion::between(
            value: $this->amountInPence,
            lowerLimit: 0,
            upperLimit: 9_999_999_999_999_00,
            message: "Cannot construct a negative or extremely large amount of money"
        );
    }

    public function amountInPence(): int
    {
        return (int) $this->amountInPence;
    }

    public static function fromPence(int $amountInPence, Currency $currency): self
    {
        return new self((string) $amountInPence, $currency);
    }

    public static function fromPoundsGBP(int $pounds): self
    {
        return new self((string) ($pounds * 100), Currency::GBP);
    }

    public static function sum(self ...$amounts): self
    {
        if ($amounts === []) {
            return self::zero(Currency::GBP);
        }

        return array_reduce(
            $amounts,
            static fn (self $a, self $b): self => $a->plus($b),
            self::zero($amounts[0]->currency),
        );
    }

    public static function zero(Currency $currency = Currency::GBP): self
    {
        return new self('0', $currency);
    }

    /**
     * Reconstructs object from serilized record (which may be generated by an older version of this class and cached)
     * @param array{amountInPence: int, currency: string} $value
     */
    public static function fromSerialized(mixed $value): self
    {
        return new self((string) $value['amountInPence'], Currency::fromIsoCode($value['currency']));
    }

    /**
     * @return string Human-readable amount for use in English, e.g. "£17,000.00"
     */
    public function format(): string
    {
        return $this->currency->symbol() .
            number_format(
                num: $this->amountInPence() / 100,
                decimals: 2,
                decimal_separator: '.',
                thousands_separator: ','
            );
    }

    /**
     * @return array{amountInPence: int, currency: string}
     */
    #[\Override]
    public function jsonSerialize(): mixed
    {
        return ['amountInPence' => $this->amountInPence(), 'currency' => $this->currency->isoCode()];
    }

    public function lessThan(Money $that): bool
    {
        if ($this->currency !== $that->currency) {
            throw new \UnexpectedValueException("Cannot compare amounts with different currencies");
        }

        return $this->amountInPence() < $that->amountInPence();
    }

    public function moreThan(Money $that): bool
    {
        if ($this->currency !== $that->currency) {
            throw new \UnexpectedValueException("Cannot compare amounts with different currencies");
        }

        return $this->amountInPence() > $that->amountInPence();
    }

    #[\Override]
    public function __toString()
    {
        return $this->currency->isoCode() . ' ' . (string)($this->amountInPence() / 100);
    }

    /**
     * Returns an amount in major units as a string, e.g. '1.00' for one pound.
     * @return numeric-string
     */
    public function toNumericString(): string
    {
        return bcdiv($this->amountInPence, '100', 2);
    }

    /**
     * @param numeric-string $amount
     */
    public static function fromNumericStringGBP(string $amount): self
    {
        $amountInPence = bcmul($amount, '100', 2);

        Assertion::integerish((float) $amountInPence);

        return new self($amountInPence, Currency::GBP);
    }

    /**
     * @param numeric-string $amount
     */
    public static function fromNumericString(string $amount, Currency $currency): self
    {
        $amountInPence = bcmul($amount, '100', 2);

        Assertion::integerish((float) $amountInPence);

        return new self($amountInPence, $currency);
    }

    public function withPence(int $amountInPence): self
    {
        return new self((string) $amountInPence, $this->currency);
    }

    public function plus(self $that): self
    {
        /** @psalm-suppress ImpureMethodCall */
        Assertion::same($this->currency, $that->currency);

        return new self(bcadd($this->amountInPence, $that->amountInPence, 0), $this->currency);
    }

    public function minus(self $that): self
    {
        /** @psalm-suppress ImpureMethodCall */
        Assertion::same($this->currency, $that->currency);

        return new self(bcsub($this->amountInPence, $that->amountInPence, 0), $this->currency);
    }

    /**
     * @param numeric-string $amount
     */
    public function equalsIgnoringCurrency(string $amount): bool
    {
        return bccomp($amount, bcdiv($this->amountInPence, '100', 2), 2) === 0;
    }

    public function toMajorUnitFloat(): float
    {
        return $this->amountInPence() / 100;
    }

    public function isZero(): bool
    {
        return $this->amountInPence() === 0;
    }

    /** @psalm-suppress PossiblyUnusedMethod May use in future */
    public function isStrictlyPositive(): bool
    {
        return $this->amountInPence() > 0;
    }

    public function times(int $multiplier): self
    {
        return new self(bcmul($this->amountInPence, (string) $multiplier, 0), $this->currency);
    }

    public function greaterThan(Money $that): bool
    {
        if ($this->currency !== $that->currency) {
            throw new \Exception('Cannot compare money in different currencies');
        }

        return $this->amountInPence > $that->amountInPence;
    }
}