Tax Region Resolver
Determines the tax region from shipping/billing address and configured rules.
Function signature
ogResolveTaxRegion(input = array(), options = array())
Categories
- Ecommerce Workflows
Parameters
inputStructured workflow input array documented by this helper.optionsOptional documented policy controls for the helper.Return value
Public-safe status string returned by the function for controller branching or logging.
- success
- message
- data
Compatibility
Existing function name, slug, path, and call order preserved; advertised metadata corrected to the actual source behavior.
Minimum PHP version: 7.4
Security notes
Use caller-owned allowlists and context-specific escaping; validate file paths, routes, email tokens, cart totals, discount rules, and tax-region rules before production use.
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.
*/
/**
* Determines the tax region from shipping/billing address and configured rules.
*
* Primary use case: Checkout tax calculation prep.
* Typical inputs: address, region rules.
* Typical output: tax region key.
*
* Implementation note: Do not calculate legal tax without verified rules/provider.
*
* @param array $input Structured input values for this helper contract.
* @param array $options Optional policy and formatting controls.
* @return array Structured result data with success, message, and data keys.
*/
function ogResolveTaxRegion($input = array(), $options = array()) {
$result = array(
'success' => false,
'message' => '',
'data' => array()
);
if (!is_array($input)) {
$result['message'] = 'Input must be an array.';
return $result;
}
if (!is_array($options)) {
$options = array();
}
$address = array();
if (!empty($input['address']) && is_array($input['address'])) {
$address = $input['address'];
}
$rules = array();
if (!empty($input['rules']) && is_array($input['rules'])) {
$rules = $input['rules'];
}
$country = '';
if (!empty($address['country'])) {
$country = strtoupper(trim((string)$address['country']));
}
$state = '';
if (!empty($address['state'])) {
$state = strtoupper(trim((string)$address['state']));
}
$postal_code = '';
if (!empty($address['postal_code'])) {
$postal_code = strtoupper(trim((string)$address['postal_code']));
}
if (empty($country)) {
$result['message'] = 'Country is required to resolve a tax region.';
return $result;
}
$region_key = 'default';
$matched_rule = array();
foreach ($rules as $rule) {
if (!is_array($rule)) {
continue;
}
$rule_country = '';
if (!empty($rule['country'])) {
$rule_country = strtoupper(trim((string)$rule['country']));
}
$rule_state = '';
if (!empty($rule['state'])) {
$rule_state = strtoupper(trim((string)$rule['state']));
}
$rule_postal_prefix = '';
if (!empty($rule['postal_prefix'])) {
$rule_postal_prefix = strtoupper(trim((string)$rule['postal_prefix']));
}
if (!empty($rule_country) && $rule_country != $country) {
continue;
}
if (!empty($rule_state) && $rule_state != $state) {
continue;
}
if (!empty($rule_postal_prefix) && strpos($postal_code, $rule_postal_prefix) !== 0) {
continue;
}
if (!empty($rule['region_key'])) {
$region_key = preg_replace('/[^a-zA-Z0-9_-]/', '', (string)$rule['region_key']);
$matched_rule = $rule;
break;
}
}
$result['success'] = true;
$result['message'] = 'Tax region resolved. Tax calculation must still use verified tax rules or provider data.';
$result['data'] = array(
'region_key' => $region_key,
'matched_rule' => $matched_rule
);
return $result;
}