Shipping Rate Selector

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Chooses eligible shipping rates based on cart weight, value, destination, and carrier rules.
 *
 * The function only selects rates from rules supplied by the caller. It does not call
 * carrier APIs, mutate orders, or calculate legal tax/shipping obligations.
 *
 * @param array $cart Cart data with lines, destination, subtotal, and weight metadata.
 * @param array $rate_rules Shipping rate rules to evaluate.
 * @return array Structured result with eligible rates, rejected rates, and the selected rate.
 */
function ogSelectShippingRate($cart = array(), $rate_rules = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($cart)) {
		$result['message'] = 'Cart must be an array.';
		return $result;
	}

	if (!is_array($rate_rules)) {
		$result['message'] = 'Shipping rate rules must be an array.';
		return $result;
	}

	$destination_country = '';
	if (!empty($cart['destination_country'])) {
		$destination_country = strtoupper(trim((string)$cart['destination_country']));
	}

	$destination_region = '';
	if (!empty($cart['destination_region'])) {
		$destination_region = strtoupper(trim((string)$cart['destination_region']));
	}

	$subtotal_minor_units = 0;
	if (!empty($cart['subtotal_minor_units'])) {
		$subtotal_minor_units = (int)$cart['subtotal_minor_units'];
	}

	$total_weight_ounces = 0;
	if (!empty($cart['total_weight_ounces'])) {
		$total_weight_ounces = (int)$cart['total_weight_ounces'];
	} elseif (!empty($cart['lines']) && is_array($cart['lines'])) {
		foreach ($cart['lines'] as $line) {
			$line_weight = 0;
			$quantity = 1;

			if (!empty($line['weight_ounces'])) {
				$line_weight = (int)$line['weight_ounces'];
			}

			if (!empty($line['quantity'])) {
				$quantity = (int)$line['quantity'];
			}

			if ($quantity < 1) {
				$quantity = 1;
			}

			$total_weight_ounces += ($line_weight * $quantity);
		}
	}

	$eligible_rates = array();
	$rejected_rates = array();

	foreach ($rate_rules as $rate) {
		if (!is_array($rate)) {
			continue;
		}

		$rate_code = '';
		if (!empty($rate['code'])) {
			$rate_code = trim((string)$rate['code']);
		}

		$label = $rate_code;
		if (!empty($rate['label'])) {
			$label = trim((string)$rate['label']);
		}

		$price_minor_units = 0;
		if (!empty($rate['price_minor_units'])) {
			$price_minor_units = (int)$rate['price_minor_units'];
		}

		$reason = '';

		if (!empty($rate['countries']) && is_array($rate['countries'])) {
			$allowed_country = false;
			foreach ($rate['countries'] as $country) {
				if (strtoupper(trim((string)$country)) == $destination_country) {
					$allowed_country = true;
				}
			}

			if (!$allowed_country) {
				$reason = 'Destination country is not eligible.';
			}
		}

		if (empty($reason) && !empty($rate['regions']) && is_array($rate['regions'])) {
			$allowed_region = false;
			foreach ($rate['regions'] as $region) {
				if (strtoupper(trim((string)$region)) == $destination_region) {
					$allowed_region = true;
				}
			}

			if (!$allowed_region) {
				$reason = 'Destination region is not eligible.';
			}
		}

		if (empty($reason) && !empty($rate['min_subtotal_minor_units'])) {
			if ($subtotal_minor_units < (int)$rate['min_subtotal_minor_units']) {
				$reason = 'Cart subtotal is below the required minimum.';
			}
		}

		if (empty($reason) && !empty($rate['max_weight_ounces'])) {
			if ($total_weight_ounces > (int)$rate['max_weight_ounces']) {
				$reason = 'Cart weight exceeds the rate limit.';
			}
		}

		$rate_row = array(
			'code' => $rate_code,
			'label' => $label,
			'price_minor_units' => $price_minor_units
		);

		if (empty($reason)) {
			$eligible_rates[] = $rate_row;
		} else {
			$rate_row['reason'] = $reason;
			$rejected_rates[] = $rate_row;
		}
	}

	$selected_rate = array();
	foreach ($eligible_rates as $rate) {
		if (empty($selected_rate)) {
			$selected_rate = $rate;
		} elseif ($rate['price_minor_units'] < $selected_rate['price_minor_units']) {
			$selected_rate = $rate;
		}
	}

	$result['success'] = true;
	$result['message'] = 'Shipping rates evaluated.';
	$result['data'] = array(
		'eligible_rates' => $eligible_rates,
		'rejected_rates' => $rejected_rates,
		'selected_rate' => $selected_rate,
		'total_weight_ounces' => $total_weight_ounces,
		'subtotal_minor_units' => $subtotal_minor_units
	);

	return $result;
}