<?php

namespace WPForms\Admin\Dashboard;

use DateTimeImmutable;
use WPForms\Admin\Payments\Views\Overview\Chart;
use WPForms\Db\Payments\StatsAggregator;

/**
 * Live payment stat tiles for the Dashboard.
 *
 * Unlike the Payments Overview, the Dashboard has no test/live switch — every figure it
 * shows is site-wide and live-mode. The shared payment queries resolve their mode through
 * `Overview\Page::get_mode()`, which falls back to the viewing user's stored Payments-page
 * mode on any admin-ajax request. Without the pin applied here, a range switch would return
 * that user's test-mode totals and store them in the site-wide Dashboard cache.
 *
 * @since 2.0.2
 */
class PaymentStats {

	/**
	 * Filter resolving the shared payment WHERE conditions (mode, currency, is_published).
	 *
	 * @since 2.0.2
	 *
	 * @var string
	 */
	public const WHERE_ARGS_FILTER = 'wpforms_db_payments_payment_add_secondary_where_conditions_args';

	/**
	 * Filter overriding the stat-card column aggregation expressions.
	 *
	 * @since 2.0.2
	 *
	 * @var string
	 */
	private const COLUMN_CLAUSES_FILTER = 'wpforms_admin_payments_views_overview_ajax_stats_column_clauses';

	/**
	 * Dashboard render order for the payment stat cards.
	 *
	 * The Overview catalog places refunds between sales and the subscription pair. The
	 * Dashboard leads with Total Sales (the default graph report), keeps the
	 * subscription cards together and closes its grid with the refund/coupon pair, so
	 * the order is declared here rather than reordering `Chart::stat_cards()` — that
	 * catalog also drives the Payments Overview screen.
	 *
	 * @since 2.0.2
	 */
	private const CARD_ORDER = [
		'total_sales',
		'total_payments',
		'total_subscription',
		'total_renewal_subscription',
		'total_refunded',
		'total_coupons',
	];

	/**
	 * Get the stat-card catalog in the Dashboard's own render order.
	 *
	 * Cards missing from the catalog are skipped, and catalog entries absent from
	 * `CARD_ORDER` keep their own order at the end — a card added to the Overview later
	 * still surfaces here instead of silently vanishing from the widget.
	 *
	 * @since 2.0.2
	 *
	 * @return array
	 */
	public static function get_ordered_stat_cards(): array {

		$cards   = Chart::stat_cards();
		$ordered = [];

		foreach ( self::CARD_ORDER as $report ) {
			if ( isset( $cards[ $report ] ) ) {
				$ordered[ $report ] = $cards[ $report ];
			}
		}

		return $ordered + $cards;
	}

	/**
	 * Fill in any tile the source could not report, so the widget always renders the full
	 * set of stat cards.
	 *
	 * `Payments::get_tiles()` skips a card whose key is absent, and the sources disagree on
	 * which keys they produce: the live aggregator omits cards whose `Chart::stat_cards()`
	 * condition is false, while the rollup tables track only four of the six measures. Left
	 * alone, the same widget would gain and lose cards as the range crossed rollup coverage.
	 * Zeros here mean "nothing to report", which is what an absent card conveyed anyway.
	 *
	 * @since 2.0.2
	 *
	 * @param array $tiles Tiles resolved so far, keyed by cached `payments.tiles` key.
	 *
	 * @return array
	 */
	public static function fill_missing_tiles( array $tiles ): array {

		$empty_amount = [
			'amount' => '0',
			'count'  => 0,
		];

		// The canonical zero-tile shape — `Cache::get_empty_payments()` consumes it for the
		// no-gateway state, so the two states cannot drift apart.
		return $tiles + [
			'total_payments'    => 0,
			'total_sales'       => '0',
			'total_refunded'    => $empty_amount,
			'new_subscriptions' => $empty_amount,
			'renewals'          => $empty_amount,
			'coupons'           => 0,
		];
	}

	/**
	 * Get the live payment tiles for a range, keyed by cached `payments.tiles` key.
	 *
	 * @since 2.0.2
	 *
	 * @param DateTimeImmutable $start Range start date.
	 * @param DateTimeImmutable $end   Range end date.
	 *
	 * @return array
	 */
	public function get_tiles( DateTimeImmutable $start, DateTimeImmutable $end ): array {

		// StatsAggregator may not be available on all branches.
		if ( ! class_exists( StatsAggregator::class ) ) {
			return [];
		}

		$row = $this->with_live_mode(
			static function () use ( $start, $end ) {

				return ( new StatsAggregator( Chart::stat_cards() ) )->get_summary_reports( $start, $end );
			}
		);

		return $this->normalize_tiles( (array) $row );
	}

	/**
	 * Run a callback with the shared payment queries pinned to live mode.
	 *
	 * Pinned for the duration of the callback only. Pinning globally would break the
	 * Payments Overview, whose test/live switch legitimately drives the same filter —
	 * so the pin is released in `finally`, or a throwing callback would leak live mode
	 * into every later query in the request.
	 *
	 * @since 2.0.2
	 *
	 * @param callable $callback Callback running the payment queries.
	 *
	 * @return mixed The callback's return value.
	 */
	public function with_live_mode( callable $callback ) { // phpcs:ignore WPForms.PHP.HooksMethod.InvalidPlaceForAddingHooks -- The mode pin is deliberately request-scoped; registering it in hooks() would force live mode on the Payments Overview too.

		add_filter( self::WHERE_ARGS_FILTER, [ $this, 'force_live_mode' ], PHP_INT_MAX );

		try {
			return $callback();
		} finally {
			remove_filter( self::WHERE_ARGS_FILTER, [ $this, 'force_live_mode' ], PHP_INT_MAX );
		}
	}

	/**
	 * Force live mode on the shared payment WHERE conditions.
	 *
	 * Runs last so it wins over the Payments page's own mode resolution.
	 *
	 * @since 2.0.2
	 *
	 * @param array|mixed $args Query arguments.
	 *
	 * @return array
	 */
	public function force_live_mode( $args ): array {

		$args         = (array) $args;
		$args['mode'] = 'live';

		return $args;
	}

	/**
	 * Whether anything overrides the stat-card column aggregation expressions.
	 *
	 * The rollup tables store pre-aggregated sums, so an override of the aggregation SQL
	 * cannot be reproduced from them. Callers use this to fall back to the live path rather
	 * than serve totals that would silently disagree with the Payments Overview. No core
	 * code hooks this filter, so any callback at all belongs to an addon or a custom snippet.
	 *
	 * @since 2.0.2
	 *
	 * @return bool
	 */
	public static function has_column_clause_overrides(): bool {

		return has_filter( self::COLUMN_CLAUSES_FILTER );
	}

	/**
	 * Map `StatsAggregator::get_summary_reports()`'s Chart-report keys to the cached
	 * `payments.tiles` keys.
	 *
	 * Also carries each tile's `{report}_delta` through as `{tile}_delta`, when present.
	 * `get_summary_reports()` already computes the deltas, so this is a pass-through.
	 * Reports absent from the row are omitted, so their tile is skipped entirely.
	 *
	 * @since 2.0.2
	 *
	 * @param array $row Raw summary report row, keyed by `Chart::stat_cards()` report names.
	 *
	 * @return array
	 */
	private function normalize_tiles( array $row ): array {

		$map = [
			'total_payments'             => 'total_payments',
			'total_sales'                => 'total_sales',
			'total_refunded'             => 'total_refunded',
			'total_subscription'         => 'new_subscriptions',
			'total_renewal_subscription' => 'renewals',
			'total_coupons'              => 'coupons',
		];

		$tiles = [];

		foreach ( $map as $source_key => $target_key ) {
			if ( array_key_exists( $source_key, $row ) ) {
				$tiles[ $target_key ] = $row[ $source_key ];
			}

			$delta_key = "{$source_key}_delta";

			if ( array_key_exists( $delta_key, $row ) ) {
				$tiles[ "{$target_key}_delta" ] = (int) $row[ $delta_key ];
			}
		}

		return $tiles;
	}
}