Postal Code Validator

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.
 */

/**
 * Validates postal codes against country-specific patterns when configured.
 *
 * Primary use case: Ecommerce addresses and local service forms.
 * Typical inputs: postal code, country code.
 * Typical output: valid flag and normalized value.
 *
 * Implementation note: Use allowlist country rules; avoid rejecting unknown formats too aggressively.
 *
 * @param string $postal_code Raw postal code.
 * @param string $country_code Country code such as US, CA, GB, or AU.
 * @param array $custom_patterns Optional country regex map.
 * @return array Structured postal-code validation result.
 */
function ogValidatePostalCode($postal_code, $country_code = 'US', $custom_patterns = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array('valid' => false, 'postal_code' => '')
	);

	$postal_code = strtoupper(trim((string)$postal_code));
	$postal_code = preg_replace('/\s+/', ' ', $postal_code);
	$country_code = strtoupper(trim((string)$country_code));
	if (!is_array($custom_patterns)) {
		$custom_patterns = array();
	}

	if (empty($postal_code)) {
		$result['message'] = 'Missing postal code.';
		return $result;
	}

	$patterns = array(
		'US' => '/^[0-9]{5}(?:-[0-9]{4})?$/',
		'CA' => '/^[A-Z][0-9][A-Z] ?[0-9][A-Z][0-9]$/',
		'GB' => '/^[A-Z]{1,2}[0-9][A-Z0-9]? ?[0-9][A-Z]{2}$/',
		'UK' => '/^[A-Z]{1,2}[0-9][A-Z0-9]? ?[0-9][A-Z]{2}$/',
		'AU' => '/^[0-9]{4}$/'
	);

	foreach ($custom_patterns as $code => $pattern) {
		$code = strtoupper(trim((string)$code));
		$pattern = (string)$pattern;
		if (!empty($code) && !empty($pattern)) {
			$patterns[$code] = $pattern;
		}
	}

	if (empty($patterns[$country_code])) {
		$result['success'] = true;
		$result['message'] = 'Postal code accepted without a country-specific pattern.';
		$result['data'] = array(
			'valid' => true,
			'postal_code' => $postal_code,
			'country_code' => $country_code,
			'pattern_checked' => false
		);
		return $result;
	}

	if (!preg_match($patterns[$country_code], $postal_code)) {
		$result['message'] = 'Postal code does not match the configured country pattern.';
		$result['data'] = array(
			'valid' => false,
			'postal_code' => $postal_code,
			'country_code' => $country_code,
			'pattern_checked' => true
		);
		return $result;
	}

	$result['success'] = true;
	$result['message'] = 'Postal code validated.';
	$result['data'] = array(
		'valid' => true,
		'postal_code' => $postal_code,
		'country_code' => $country_code,
		'pattern_checked' => true
	);

	return $result;
}