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

declare( strict_types = 1 );

namespace PlugixaCrm\Core;

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

/**
 * What a currency is worth in the system currency.
 *
 * THE RATES ARE ONE TABLE, WHOEVER FILLS IT. By default a person types them in, which is base EspoCRM's
 * whole arrangement (`currencyRates`, a plain map under Administration → Currency). An administrator can
 * instead switch on {@see ExchangeFeed}, which writes the European Central Bank's daily reference rates
 * into the SAME table through the same `Settings::save()`. This class cannot tell the two apart and does
 * not need to: a rate is a rate, and the feed is opt-in because it is an outbound connection to a third
 * party, disclosed under the readme's `== External services ==`.
 *
 * The ECB and not a commercial API because it needs no key, no account and no terms beyond a legal
 * notice, and because a CRM has no use for minute-by-minute rates; a daily reference rate is exactly
 * what a pipeline total and a forecast need.
 *
 * A CURRENCY WITH NO RATE IS STILL WORTH 1.0, and that remains a lie — but it is the site owner's
 * lie, introduced by entering two currencies and pricing neither, and a plugin that guessed would be
 * telling a better-disguised one. What has changed is that there is now somewhere to stop telling it.
 *
 * `plugixa_crm_currency_rate` stays, and stays LAST: a site with its own feed hooks it and overrides
 * whatever the table holds. Every conversion in the plugin goes through here, so that is one place.
 */
final class Exchange {

	/**
	 * The rate that turns one unit of $currency into the system currency.
	 *
	 * @param string $currency ISO code.
	 */
	public static function rate( string $currency ): float {
		$currency = strtoupper( substr( $currency, 0, 3 ) );
		$system   = Settings::currency();

		if ( $currency === $system ) {
			return 1.0;
		}

		$entered = Settings::currency_rates()[ $currency ] ?? 0.0;

		/**
		 * Filters the exchange rate from a currency into the system currency.
		 *
		 * The default is whatever was entered under Settings, or 1.0 when nothing was — see the class
		 * docblock for why an unpriced currency is left at one rather than guessed at.
		 *
		 * This filter runs LAST, so a site with a live rate feed overrides the typed-in number rather
		 * than competing with it.
		 *
		 * @param float  $rate     The entered rate, or 1.0.
		 * @param string $currency The currency being converted FROM.
		 * @param string $system   The currency being converted TO.
		 */
		return max( 0.0, (float) apply_filters( 'plugixa_crm_currency_rate', $entered > 0 ? $entered : 1.0, $currency, $system ) );
	}

	/**
	 * Convert an amount into the system currency.
	 *
	 * @param float  $amount   The amount.
	 * @param string $currency The currency it is in.
	 */
	public static function to_base( float $amount, string $currency ): float {
		return $amount * self::rate( $currency );
	}
}