From 67642a3b6ccb7806ba383c8d06f1d9e298644d0e Mon Sep 17 00:00:00 2001
From: David Stone <david@nnucomputerwhiz.com>
Date: Thu, 26 Mar 2026 19:45:32 -0600
Subject: [PATCH] docs(tax): document wu_cart_applicable_tax_rates filter and
 universal fallback behaviour
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cherry-pick of a3f97e82 and 7738dce8 from closed PR #277 produced empty
commits — the universal tax fallback feature is already fully implemented
in main via PR #506 (wildcard '*' country approach).

This commit adds a docblock to the wu_cart_applicable_tax_rates filter
application in class-cart.php, documenting:
- The filter's parameters and purpose
- The '*' (Apply to all countries) universal fallback mechanism
- How to configure a universal fallback rate via the Tax Rates UI

The feature as implemented:
- views/taxes/list.php: 'Apply to all countries' (*) option in country dropdown
- inc/functions/tax.php: wildcard fallback in wu_get_applicable_tax_rates()
- inc/checkout/class-cart.php: wu_cart_applicable_tax_rates filter hook
- tests/: comprehensive wildcard fallback test coverage

Closes #521
---
 inc/checkout/class-cart.php | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/inc/checkout/class-cart.php b/inc/checkout/class-cart.php
index 561acc6c5..58b162526 100644
--- a/inc/checkout/class-cart.php
+++ b/inc/checkout/class-cart.php
@@ -2792,6 +2792,23 @@ public function apply_taxes_to_item($line_item) {
 			return $line_item;
 		}
 
+		/**
+		 * Filters the applicable tax rates for a cart line item.
+		 *
+		 * Rates with country set to '*' (Apply to all countries) act as a universal
+		 * fallback and are applied when no country-specific rate matches the customer's
+		 * country. Country-specific rates always take precedence.
+		 *
+		 * To configure a universal fallback rate, go to Tax Rates and select
+		 * 'Apply to all countries' from the country dropdown on any rate row.
+		 *
+		 * @since 2.0.0
+		 *
+		 * @param array  $tax_rates    The applicable tax rates.
+		 * @param string $country      The customer's country code.
+		 * @param string $tax_category The tax category slug.
+		 * @param Cart   $cart         The current cart object.
+		 */
 		$tax_rates = apply_filters('wu_cart_applicable_tax_rates', wu_get_applicable_tax_rates($this->country, $tax_category, $this->state, $this->city), $this->country, $tax_category, $this);
 
 		if (empty($tax_rates)) {