编辑文件

编辑文件：Helper.php

<?php

declare( strict_types=1 );

namespace Automattic\WooCommerce\Gateways\PayPal;

use WC_Order;
use Automattic\WooCommerce\Gateways\PayPal\Constants as PayPalConstants;

defined( 'ABSPATH' ) || exit;

/**
 * PayPal Helper Class
 *
 * Helper methods for PayPal gateway operations including order validation,
 * data redaction, and address updates.
 *
 * @since 10.5.0
 */
class Helper {
	/**
	 * Check if a country code is supported by PayPal.
	 *
	 * @param string $country_code Country code.
	 * @return bool True if the country is supported by PayPal, false otherwise.
	 */
	public static function is_country_supported_by_paypal( string $country_code ): bool {
		return array_key_exists( $country_code, PayPalConstants::SUPPORTED_COUNTRIES );
	}

/**
	 * Check if the PayPal gateway is enabled.
	 *
	 * @return bool
	 */
	public static function is_paypal_gateway_available(): bool {
		$settings    = get_option( 'woocommerce_paypal_settings', array() );
		$enabled     = isset( $settings['enabled'] ) && 'yes' === $settings['enabled'];
		$should_load = isset( $settings['_should_load'] ) && 'yes' === $settings['_should_load'];
		return $enabled && $should_load;
	}

/**
	 * Check if the merchant is eligible for migration from WPS to PPCP.
	 *
	 * @return bool
	 */
	public static function is_orders_v2_migration_eligible(): bool {
		$settings = get_option( 'woocommerce_paypal_settings', array() );

// If API keys are set, the merchant is not eligible for migration
		// as they may be using features that cannot be seamlessly migrated.
		$is_test_mode  = isset( $settings['testmode'] ) && 'yes' === $settings['testmode'];
		$api_username  = $is_test_mode ? ( $settings['sandbox_api_username'] ?? null ) : ( $settings['api_username'] ?? null );
		$api_password  = $is_test_mode ? ( $settings['sandbox_api_password'] ?? null ) : ( $settings['api_password'] ?? null );
		$api_signature = $is_test_mode ? ( $settings['sandbox_api_signature'] ?? null ) : ( $settings['api_signature'] ?? null );

return empty( $api_username ) && empty( $api_password ) && empty( $api_signature );
	}

/**
	 * Get the WC order from the PayPal custom ID.
	 *
	 * @param string $custom_id The custom ID string from the PayPal order.
	 * @return WC_Order|null
	 */
	public static function get_wc_order_from_paypal_custom_id( string $custom_id ): ?WC_Order {
		if ( '' === $custom_id ) {
			return null;
		}

$data = json_decode( $custom_id, true );
		if ( ! is_array( $data ) ) {
			return null;
		}

$order_id = $data['order_id'] ?? null;
		if ( ! $order_id ) {
			return null;
		}

$order = wc_get_order( $order_id );
		if ( ! $order instanceof \WC_Order ) {
			return null;
		}

// Validate the order key.
		$order_key = $data['order_key'] ?? null;
		if ( $order_key !== $order->get_order_key() ) {
			return null;
		}

return $order;
	}

/**
	 * Remove PII (Personally Identifiable Information) from data for logging.
	 *
	 * This function recursively traverses the data array and redacts sensitive information
	 * while preserving the structure for debugging purposes.
	 *
	 * @param mixed $data The data to remove PII from (array, string, or other types).
	 * @return mixed The data with PII redacted.
	 */
	public static function redact_data( $data ) {
		if ( ! is_array( $data ) ) {
			return $data;
		}

$redacted_data = array();

foreach ( $data as $key => $value ) {
			// Skip redacting the payee information as it belongs to the store merchant.
			if ( 'payee' === $key ) {
				$redacted_data[ $key ] = $value;
				continue;
			}
			// Mask the email address.
			if ( 'email_address' === $key || 'email' === $key ) {
				$redacted_data[ $key ] = self::mask_email( (string) $value );
				continue;
			}

if ( is_array( $value ) ) {
				$redacted_data[ $key ] = self::redact_data( $value );
			} elseif ( in_array( $key, Constants::FIELDS_TO_REDACT, true ) ) {
				$redacted_data[ $key ] = '[redacted]';
			} else {
				// Keep non-PII data as is.
				$redacted_data[ $key ] = $value;
			}
		}

return $redacted_data;
	}

/**
	 * Mask email address before @ keeping the full domain.
	 *
	 * @param string $email The email address to mask.
	 * @return string The masked email address or original input if invalid.
	 */
	public static function mask_email( string $email ): string {
		if ( empty( $email ) ) {
			return $email;
		}

$parts = explode( '@', $email, 2 );
		if ( count( $parts ) !== 2 || empty( $parts[0] ) || empty( $parts[1] ) ) {
			return $email;
		}
		list( $local, $domain ) = $parts;

if ( strlen( $local ) <= 3 ) {
			$masked_local = str_repeat( '*', strlen( $local ) );
		} else {
			$masked_local = substr( $local, 0, 2 )
						. str_repeat( '*', max( 1, strlen( $local ) - 3 ) )
						. substr( $local, -1 );
		}

return $masked_local . '@' . $domain;
	}

/**
	 * Update the addresses in the order.
	 *
	 * @param WC_Order|null $order The order object.
	 * @param array         $paypal_order_details The PayPal order details.
	 * @return void
	 */
	public static function update_addresses_in_order( ?WC_Order $order, array $paypal_order_details ): void {
		if ( empty( $order ) || empty( $paypal_order_details ) ) {
			return;
		}

// Bail early if '_paypal_addresses_updated' is 'yes', meaning the addresses update already have been successful.
		if ( 'yes' === $order->get_meta( PayPalConstants::PAYPAL_ORDER_META_ADDRESSES_UPDATED, true ) ) {
			return;
		}

// Update the shipping information.
		$full_name = $paypal_order_details['purchase_units'][0]['shipping']['name']['full_name'] ?? '';
		if ( ! empty( $full_name ) ) {
			$name_parts             = explode( ' ', $full_name, 2 );
			$approximate_first_name = $name_parts[0] ?? '';
			$approximate_last_name  = isset( $name_parts[1] ) ? $name_parts[1] : '';
			$order->set_shipping_first_name( $approximate_first_name );
			$order->set_shipping_last_name( $approximate_last_name );
		}

$shipping_address = $paypal_order_details['purchase_units'][0]['shipping']['address'] ?? array();
		if ( ! empty( $shipping_address ) ) {
			$order->set_shipping_country( $shipping_address['country_code'] ?? '' );
			$order->set_shipping_postcode( $shipping_address['postal_code'] ?? '' );
			$order->set_shipping_state( $shipping_address['admin_area_1'] ?? '' );
			$order->set_shipping_city( $shipping_address['admin_area_2'] ?? '' );
			$order->set_shipping_address_1( $shipping_address['address_line_1'] ?? '' );
			$order->set_shipping_address_2( $shipping_address['address_line_2'] ?? '' );
		}

// Update the billing information.
		$full_name = $paypal_order_details['payer']['name'] ?? array();
		$email     = $paypal_order_details['payer']['email_address'] ?? '';
		if ( ! empty( $full_name ) ) {
			$order->set_billing_first_name( $full_name['given_name'] ?? '' );
			$order->set_billing_last_name( $full_name['surname'] ?? '' );
			$order->set_billing_email( $email );
		}

$billing_address = $paypal_order_details['payer']['address'] ?? array();
		if ( ! empty( $billing_address ) ) {
			$order->set_billing_country( $billing_address['country_code'] ?? '' );
			$order->set_billing_postcode( $billing_address['postal_code'] ?? '' );
			$order->set_billing_state( $billing_address['admin_area_1'] ?? '' );
			$order->set_billing_city( $billing_address['admin_area_2'] ?? '' );
			$order->set_billing_address_1( $billing_address['address_line_1'] ?? '' );
			$order->set_billing_address_2( $billing_address['address_line_2'] ?? '' );
		}

$order->update_meta_data( PayPalConstants::PAYPAL_ORDER_META_ADDRESSES_UPDATED, 'yes' );
		$order->save();
	}
}