<?php
/**
 * Resolve any WooCommerce order-ish thing to an order that HAS a customer.
 *
 * WHY THIS EXISTS
 * ---------------
 * wc_get_order() is documented as returning "an order", and every caller in
 * this plugin read that as "a WC_Order". It is not: the id space is shared, so
 * wc_get_order() hands back a WC_Order_Refund whenever the id belongs to a
 * refund, and a refund is NOT an order in the way that matters here.
 *
 *   WC_Order          extends WC_Abstract_Order  and adds billing/shipping.
 *   WC_Order_Refund   extends WC_Abstract_Order  and adds NOTHING of the sort.
 *
 * So get_billing_phone(), get_billing_email(), get_billing_first_name() and
 * every other customer-shaped getter simply does not exist on a refund. Calling
 * one is a fatal Error, not a null — which is exactly what production hit:
 *
 *   [6rsh WhatsApp] Followups::sync_order exception: Call to undefined method
 *   Automattic\WooCommerce\Admin\Overrides\OrderRefund::get_billing_phone()
 *
 * (That class name is WooCommerce Admin's subclass of WC_Order_Refund, which is
 * why an instanceof against the concrete admin class would be the wrong test —
 * we check the base class, so both the plain and the overridden refund match.)
 *
 * The refund is not a thing to message about; its PARENT is. A refund means the
 * parent order's totals changed, and the parent is what 6rsh wants a fresh
 * snapshot of. So this resolves to the parent rather than bailing out — bailing
 * out would silently drop a real state change.
 *
 * Every caller that is about to read customer data goes through here.
 *
 * @package SixRsh
 */

defined( 'ABSPATH' ) || exit;

/**
 * SixRsh_Order_Resolver.
 */
class SixRsh_Order_Resolver {

	/**
	 * Resolve to an order that is safe to read billing data from.
	 *
	 * Accepts an id or an object, because WooCommerce hooks are inconsistent
	 * about which they pass.
	 *
	 * @param \WC_Abstract_Order|int|mixed $order_or_id Order, refund, or id.
	 *
	 * @return \WC_Order|null A real order, or null when there is nothing
	 *                        billable behind it (missing, trashed, or a type
	 *                        that carries no customer at all).
	 */
	public static function billable_order( $order_or_id ) {
		if ( ! function_exists( 'wc_get_order' ) ) {
			return null;
		}

		$order = self::to_object( $order_or_id );

		if ( ! $order ) {
			return null;
		}

		// A refund carries no customer of its own — step up to the order it
		// belongs to. Deliberately ONE hop: refunds cannot nest in WooCommerce,
		// and a loop here would be a way to hang on corrupt data.
		if ( $order instanceof \WC_Order_Refund ) {
			$parent_id = (int) $order->get_parent_id();

			if ( ! $parent_id ) {
				return null;
			}

			$order = self::to_object( $parent_id );

			if ( ! $order ) {
				// Parent deleted or trashed out from under the refund.
				return null;
			}
		}

		// Anything still not a full order (a future WC order type, or a refund
		// whose parent is itself something odd) has no billing getters. Refusing
		// here is what keeps the callers free of instanceof noise.
		if ( ! $order instanceof \WC_Order ) {
			return null;
		}

		return $order;
	}

	/**
	 * Extract an id from an order/refund object or a raw value.
	 *
	 * WC_Abstract_Order, not WC_Order: a refund object must yield its own id
	 * rather than falling through to an (int) cast, which in PHP 8 warns and
	 * evaluates an object to 1 — quietly syncing whatever order has id 1.
	 *
	 * @param \WC_Abstract_Order|int|mixed $order_or_id Order, refund, or id.
	 *
	 * @return int Order id, or 0 when there is none.
	 */
	public static function id_of( $order_or_id ) {
		if ( $order_or_id instanceof \WC_Abstract_Order ) {
			return (int) $order_or_id->get_id();
		}

		if ( is_scalar( $order_or_id ) ) {
			return (int) $order_or_id;
		}

		return 0;
	}

	/**
	 * Load an order object from an id, passing objects through untouched.
	 *
	 * @param \WC_Abstract_Order|int|mixed $order_or_id Order, refund, or id.
	 *
	 * @return \WC_Abstract_Order|null
	 */
	private static function to_object( $order_or_id ) {
		if ( $order_or_id instanceof \WC_Abstract_Order ) {
			return $order_or_id;
		}

		$id = self::id_of( $order_or_id );

		if ( ! $id ) {
			return null;
		}

		$order = wc_get_order( $id );

		return $order instanceof \WC_Abstract_Order ? $order : null;
	}
}