Locale 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 locale strings such as en-US against an approved list.
 *
 * Primary use case: Multilingual content and formatting preferences.
 * Typical inputs: raw locale, allowed locales.
 * Typical output: locale string or fallback.
 *
 * Implementation note: Use allowlists; do not trust arbitrary locale paths.
 *
 * @param string $locale Raw locale value.
 * @param array $allowed_locales Approved locale codes.
 * @param string $fallback_locale Fallback locale used when the raw value is not accepted.
 * @return array Structured validation result with locale, fallback flag, and validity state.
 */
function ogValidateLocaleCode($locale, $allowed_locales = array(), $fallback_locale = 'en-US') {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$locale = trim((string)$locale);
	$fallback_locale = trim((string)$fallback_locale);

	if (empty($fallback_locale)) {
		$fallback_locale = 'en-US';
	}

	if (empty($allowed_locales)) {
		$allowed_locales = array($fallback_locale);
	}

	$normalized_allowed = array();
	foreach ($allowed_locales as $allowed_locale) {
		$allowed_locale = trim((string)$allowed_locale);
		if (preg_match('/^[a-z]{2,3}([-_][A-Z]{2})?$/', $allowed_locale)) {
			$normalized_allowed[] = str_replace('_', '-', $allowed_locale);
		}
	}

	if (empty($normalized_allowed)) {
		$normalized_allowed[] = $fallback_locale;
	}

	$locale = str_replace('_', '-', $locale);
	if (!preg_match('/^[a-z]{2,3}(-[A-Z]{2})?$/', $locale)) {
		$result['success'] = true;
		$result['message'] = 'Locale rejected; fallback applied.';
		$result['data'] = array(
			'locale' => $fallback_locale,
			'is_fallback' => true,
			'valid' => false
		);
		return $result;
	}

	if (!in_array($locale, $normalized_allowed, true)) {
		$result['success'] = true;
		$result['message'] = 'Locale is not allowlisted; fallback applied.';
		$result['data'] = array(
			'locale' => $fallback_locale,
			'is_fallback' => true,
			'valid' => false
		);
		return $result;
	}

	$result['success'] = true;
	$result['message'] = 'Locale accepted.';
	$result['data'] = array(
		'locale' => $locale,
		'is_fallback' => false,
		'valid' => true
	);

	return $result;
}