Automattic\WooCommerce\Internal\Fulfillments\Providers

USPSShippingProvider::try_parse_tracking_number │ public │ WC 1.0

Attempts to parse and validate a USPS tracking number.

Method of the class: USPSShippingProvider{}

No Hooks.

Returns

Array|null. Array with tracking URL and score, or null if invalid.

Usage

$USPSShippingProvider = new USPSShippingProvider();
$USPSShippingProvider->try_parse_tracking_number( $tracking_number, $shipping_from, $shipping_to ): ?array;

$tracking_number(string) (required)

The tracking number to validate.

$shipping_from(string) (required)

Origin country code.

$shipping_to(string) (required)

Destination country code.

USPSShippingProvider::try_parse_tracking_number() USPSShippingProvider::try parse tracking number code ^{WC 10.3.3}

public function try_parse_tracking_number( string $tracking_number, string $shipping_from, string $shipping_to ): ?array {
	if ( empty( $tracking_number ) || ! $this->can_ship_from_to( $shipping_from, $shipping_to ) ) {
		return null;
	}

	// Remove spaces and uppercase for consistency.
	$tracking_number = strtoupper( preg_replace( '/\s+/', '', $tracking_number ) );
	$is_domestic     = in_array( $shipping_to, $this->domestic_countries, true );

	// USPS tracking number patterns (ordered by confidence).
	$patterns = array(
		// 22-digit, 20-digit, and 26-34 digit numeric (domestic and third-party)
		'/^(94|93|92|95|96|94|94|94|94)\d{18,22}$/' => function () use ( $tracking_number ) {
			// Most common domestic, check digit validation.
			return FulfillmentUtils::validate_mod10_check_digit( $tracking_number ) ? 100 : 95;
		},

		// S10/UPU international (2 letters, 9 digits, 2 letters, e.g., EC123456789US).
		'/^[A-Z]{2}\d{9}[A-Z]{2}$/'                 => function () use ( $tracking_number ) {
			return FulfillmentUtils::check_s10_upu_format( $tracking_number ) ? 98 : 90;
		},

		// Global Express Guaranteed (10 or 11 digits, starts with 82).
		'/^82\d{8,9}$/'                             => 95,

		// 26-34 digit numeric (Parcel Pool, third-party, starts with 420)
		'/^420\d{23,31}$/'                          => 90,

		// 20-22 digit numeric (fallback, domestic)
		'/^\d{20,22}$/'                             => 80,

		// 9x... (fallback, 22-34 digits, numeric)
		'/^9\d{21,33}$/'                            => 75,

		// Legacy/Express/other.
		'/^91\d{18,20}$/'                           => function () use ( $tracking_number ) {
			return FulfillmentUtils::validate_mod10_check_digit( $tracking_number ) ? 90 : 80;
		},
		'/^030[67]\d{16,20}$/'                      => function () use ( $tracking_number ) {
			return FulfillmentUtils::validate_mod10_check_digit( $tracking_number ) ? 88 : 80;
		},
	);

	foreach ( $patterns as $pattern => $score ) {
		if ( preg_match( $pattern, $tracking_number ) ) {
			$ambiguity_score = is_callable( $score ) ? $score() : $score;
			return array(
				'url'             => $this->get_tracking_url( $tracking_number ),
				'ambiguity_score' => $ambiguity_score,
			);
		}
	}

	// Fallback: Accept any 13-char S10/UPU format ending with "US".
	if ( preg_match( '/^[A-Z]{2}\d{9}US$/', $tracking_number ) ) {
		return array(
			'url'             => $this->get_tracking_url( $tracking_number ),
			'ambiguity_score' => 80,
		);
	}

	// Fallback: Accept any 20-34 digit numeric string (very low confidence).
	if ( preg_match( '/^\d{20,34}$/', $tracking_number ) ) {
		return array(
			'url'             => $this->get_tracking_url( $tracking_number ),
			'ambiguity_score' => 60,
		);
	}

	return null; // No matching pattern found.
}