<?php
/**
 * @package PlugixaCrm
 */

declare( strict_types = 1 );

namespace PlugixaCrm\Core;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Money arithmetic, in one place.
 *
 * This exists because the Quotes module needed it and the Invoices module needed exactly the
 * same thing. Two copies of a rounding rule is how a quote for 3.03 becomes an invoice for
 * 3.02 — and the customer is then holding two documents from the same company that disagree
 * about what they owe.
 *
 * Amounts are stored as DECIMAL(18,4) throughout, which is exact in MySQL. The "never use
 * floats for money" rule is about FLOAT/DOUBLE, which cannot represent 0.10; DECIMAL can.
 * PHP does the arithmetic in float, so every intermediate result is rounded to the
 * currency's own scale here rather than left to drift.
 */
final class Money {

	/**
	 * Currencies with no minor unit.
	 *
	 * Rounding a yen amount to two places invents a precision the currency does not have and
	 * prints ¥1,234.57 on a document that a Japanese customer will find absurd.
	 */
	public const ZERO_DECIMAL = array( 'JPY' );

	/**
	 * How many decimal places this currency actually has.
	 *
	 * @param string $currency ISO 4217 code.
	 */
	public static function scale( string $currency ): int {
		return in_array( strtoupper( $currency ), self::ZERO_DECIMAL, true ) ? 0 : 2;
	}

	/**
	 * Round an amount to its currency's scale.
	 *
	 * @param float  $amount   The amount.
	 * @param string $currency ISO 4217 code.
	 */
	public static function round( float $amount, string $currency ): float {
		return round( $amount, self::scale( $currency ) );
	}

	/**
	 * Are two amounts the same money?
	 *
	 * Never compare money with ===. 0.1 + 0.2 is not 0.3 in binary floating point, so a
	 * balance that *is* settled can compare unequal to zero and an invoice stays forever one
	 * hundredth of a penny short of paid. Compare at the currency's own scale.
	 *
	 * @param float  $a        One amount.
	 * @param float  $b        The other.
	 * @param string $currency ISO 4217 code.
	 */
	public static function equal( float $a, float $b, string $currency ): bool {
		return abs( self::round( $a, $currency ) - self::round( $b, $currency ) ) < self::epsilon( $currency );
	}

	/**
	 * Is $a greater than $b, as money?
	 *
	 * @param float  $a        One amount.
	 * @param float  $b        The other.
	 * @param string $currency ISO 4217 code.
	 */
	public static function greater( float $a, float $b, string $currency ): bool {
		return self::round( $a, $currency ) - self::round( $b, $currency ) >= self::epsilon( $currency );
	}

	/**
	 * Half of the smallest unit this currency can express — the largest difference that is
	 * definitely not real money.
	 *
	 * @param string $currency ISO 4217 code.
	 */
	private static function epsilon( string $currency ): float {
		return ( 10 ** -self::scale( $currency ) ) / 2;
	}
}