Timezone 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 timezone identifiers and returns a safe DateTimeZone name.
 *
 * Primary use case: Scheduling, reports, user profiles.
 * Typical inputs: raw timezone, fallback.
 * Typical output: timezone string.
 *
 * Implementation note: Use timezone_identifiers_list in implementation.
 *
 * @param string $timezone Raw timezone name.
 * @param string $fallback_timezone Fallback timezone used when the raw value is invalid.
 * @return array Structured validation result with timezone, fallback flag, and offset metadata.
 */
function ogValidateTimezoneName($timezone, $fallback_timezone = 'UTC') {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$timezone = trim((string)$timezone);
	$fallback_timezone = trim((string)$fallback_timezone);

	if (empty($fallback_timezone)) {
		$fallback_timezone = 'UTC';
	}

	$available_timezones = timezone_identifiers_list();
	if (!in_array($fallback_timezone, $available_timezones, true)) {
		$fallback_timezone = 'UTC';
	}

	$accepted_timezone = $fallback_timezone;
	$is_fallback = true;
	if (!empty($timezone) && in_array($timezone, $available_timezones, true)) {
		$accepted_timezone = $timezone;
		$is_fallback = false;
	}

	$timezone_object = new DateTimeZone($accepted_timezone);
	$offset_seconds = $timezone_object->getOffset(new DateTimeImmutable('now', $timezone_object));

	$result['success'] = true;
	if ($is_fallback) {
		$result['message'] = 'Timezone rejected; fallback applied.';
	} else {
		$result['message'] = 'Timezone accepted.';
	}
	$result['data'] = array(
		'timezone' => $accepted_timezone,
		'is_fallback' => $is_fallback,
		'offset_seconds' => $offset_seconds
	);

	return $result;
}