TimezoneHelper
in package
Timezone Helper - centralized timezone handling for KMP.
Manages timezone conversions for display (UTC -> User TZ) and input (User TZ -> UTC) with priority resolution: User -> App Default -> UTC.
Tags
Table of Contents
Constants
- COMMON_TIMEZONES = ['America/Chicago' => 'Central Time (US)', 'America/New_York' => 'Eastern Time (US)', 'America/Denver' => 'Mountain Time (US)', 'America/Los_Angeles' => 'Pacific Time (US)', 'America/Phoenix' => 'Arizona (MST - No DST)', 'America/Anchorage' => 'Alaska Time (US)', 'Pacific/Honolulu' => 'Hawaii Time (US)', 'UTC' => 'UTC (Coordinated Universal Time)']
- Common US timezones for kingdom events
- DEFAULT_DATE_FORMAT = 'Y-m-d'
- DEFAULT_DATETIME_FORMAT = 'Y-m-d H:i:s'
- Default timezone format for display
- DEFAULT_TIME_FORMAT = 'H:i:s'
- DISPLAY_DATE_FORMAT = 'F j, Y'
- DISPLAY_DATETIME_FORMAT = 'F j, Y g:i A'
- DISPLAY_TIME_FORMAT = 'g:i A'
Properties
- $appTimezoneCache : string|null
- Cached application default timezone
- $timezoneListCache : array<string|int, mixed>|null
- Cached timezone list for performance
Methods
- clearCache() : void
- Clear cached values (useful for testing)
- convertBetweenTimezones() : DateTime
- Convert datetime between timezones
- formatDate() : string
- Format date only (no time)
- formatDateTime() : string
- Format datetime with standard format
- formatForDisplay() : string
- Format a datetime for display in user's timezone
- formatTime() : string
- Format time only (no date)
- getAppTimezone() : string|null
- Get application default timezone from AppSettings
- getCommonTimezones() : array<string|int, mixed>
- Get list of common timezones for UI dropdowns
- getContextTimezone() : string
- Get timezone for display purposes with context awareness
- getGatheringTimezone() : string
- Get the timezone for a specific gathering/event
- getTimezoneAbbreviation() : string
- Get timezone abbreviation (e.g., CDT, EST, PST)
- getTimezoneList() : array<string|int, mixed>
- Get list of all valid PHP timezones
- getTimezoneOffset() : float
- Get timezone offset in hours
- getUserTimezone() : string
- Get the timezone for a specific user/member
- isValidTimezone() : bool
- Validate if a string is a valid timezone identifier
- toUserTimezone() : DateTime|null
- Convert a UTC datetime to user's timezone (or gathering's timezone if provided)
- toUtc() : DateTime|null
- Convert a datetime from a specific timezone to UTC
Constants
COMMON_TIMEZONES
Common US timezones for kingdom events
public
mixed
COMMON_TIMEZONES
= ['America/Chicago' => 'Central Time (US)', 'America/New_York' => 'Eastern Time (US)', 'America/Denver' => 'Mountain Time (US)', 'America/Los_Angeles' => 'Pacific Time (US)', 'America/Phoenix' => 'Arizona (MST - No DST)', 'America/Anchorage' => 'Alaska Time (US)', 'Pacific/Honolulu' => 'Hawaii Time (US)', 'UTC' => 'UTC (Coordinated Universal Time)']
DEFAULT_DATE_FORMAT
public
mixed
DEFAULT_DATE_FORMAT
= 'Y-m-d'
DEFAULT_DATETIME_FORMAT
Default timezone format for display
public
mixed
DEFAULT_DATETIME_FORMAT
= 'Y-m-d H:i:s'
DEFAULT_TIME_FORMAT
public
mixed
DEFAULT_TIME_FORMAT
= 'H:i:s'
DISPLAY_DATE_FORMAT
public
mixed
DISPLAY_DATE_FORMAT
= 'F j, Y'
DISPLAY_DATETIME_FORMAT
public
mixed
DISPLAY_DATETIME_FORMAT
= 'F j, Y g:i A'
DISPLAY_TIME_FORMAT
public
mixed
DISPLAY_TIME_FORMAT
= 'g:i A'
Properties
$appTimezoneCache
Cached application default timezone
private
static string|null
$appTimezoneCache
= null
$timezoneListCache
Cached timezone list for performance
private
static array<string|int, mixed>|null
$timezoneListCache
= null
Methods
clearCache()
Clear cached values (useful for testing)
public
static clearCache() : void
convertBetweenTimezones()
Convert datetime between timezones
public
static convertBetweenTimezones(DateTime|string $datetime, string $fromTimezone, string $toTimezone) : DateTime
Note: DateTime instances retain their original timezone (are cloned and preserved), while strings are parsed using $fromTimezone.
Parameters
- $datetime : DateTime|string
-
Source datetime
- $fromTimezone : string
-
Source timezone (only used when $datetime is a string)
- $toTimezone : string
-
Target timezone
Tags
Return values
DateTime —Converted datetime
formatDate()
Format date only (no time)
public
static formatDate(DateTime|null $datetime[, string $format = self::DISPLAY_DATE_FORMAT ]) : string
Parameters
- $datetime : DateTime|null
-
Datetime to format
- $format : string = self::DISPLAY_DATE_FORMAT
-
PHP date format string
Return values
string —Formatted date string
formatDateTime()
Format datetime with standard format
public
static formatDateTime(DateTime|null $datetime[, string $format = self::DEFAULT_DATETIME_FORMAT ]) : string
Parameters
- $datetime : DateTime|null
-
Datetime to format
- $format : string = self::DEFAULT_DATETIME_FORMAT
-
PHP date format string
Return values
string —Formatted string
formatForDisplay()
Format a datetime for display in user's timezone
public
static formatForDisplay(DateTime|string|null $datetime[, Member|array<string|int, mixed>|null $member = null ][, string $format = self::DISPLAY_DATETIME_FORMAT ][, bool $includeTimezone = false ]) : string
Parameters
- $datetime : DateTime|string|null
-
UTC datetime
- $member : Member|array<string|int, mixed>|null = null
-
Member entity
- $format : string = self::DISPLAY_DATETIME_FORMAT
-
PHP date format string
- $includeTimezone : bool = false
-
Include timezone abbreviation
Return values
string —Formatted datetime string
formatTime()
Format time only (no date)
public
static formatTime(DateTime|null $datetime[, string $format = self::DISPLAY_TIME_FORMAT ]) : string
Parameters
- $datetime : DateTime|null
-
Datetime to format
- $format : string = self::DISPLAY_TIME_FORMAT
-
PHP date format string
Return values
string —Formatted time string
getAppTimezone()
Get application default timezone from AppSettings
public
static getAppTimezone() : string|null
Return values
string|null —Application default timezone or null
getCommonTimezones()
Get list of common timezones for UI dropdowns
public
static getCommonTimezones() : array<string|int, mixed>
Return values
array<string|int, mixed> —Common timezone identifiers with display names
getContextTimezone()
Get timezone for display purposes with context awareness
public
static getContextTimezone([Gathering|array<string|int, mixed>|null $gathering = null ][, Member|array<string|int, mixed>|null $member = null ][, string|null $default = null ]) : string
This method intelligently determines which timezone to use based on context:
- If a gathering/event is provided, use its timezone
- Otherwise, use the user's timezone
Parameters
- $gathering : Gathering|array<string|int, mixed>|null = null
-
Gathering entity or array
- $member : Member|array<string|int, mixed>|null = null
-
Member entity or array
- $default : string|null = null
-
Default timezone override
Return values
string —Valid timezone identifier
getGatheringTimezone()
Get the timezone for a specific gathering/event
public
static getGatheringTimezone([Gathering|array<string|int, mixed>|null $gathering = null ][, Member|array<string|int, mixed>|null $member = null ][, string|null $default = null ]) : string
Resolves timezone in priority order:
- Gathering's timezone field (event location)
- Member's timezone field
- Application default timezone
- UTC fallback
This is useful for displaying event times in the event's local timezone regardless of where the user is located.
Parameters
- $gathering : Gathering|array<string|int, mixed>|null = null
-
Gathering entity or array
- $member : Member|array<string|int, mixed>|null = null
-
Member entity or array
- $default : string|null = null
-
Default timezone override
Return values
string —Valid timezone identifier
getTimezoneAbbreviation()
Get timezone abbreviation (e.g., CDT, EST, PST)
public
static getTimezoneAbbreviation(DateTime|string $datetime, string $timezone) : string
Parameters
- $datetime : DateTime|string
-
Datetime in the timezone or string to convert
- $timezone : string
-
Timezone identifier
Return values
string —Timezone abbreviation
getTimezoneList()
Get list of all valid PHP timezones
public
static getTimezoneList([bool $grouped = false ]) : array<string|int, mixed>
Parameters
- $grouped : bool = false
-
Group by region
Return values
array<string|int, mixed> —List of timezones
getTimezoneOffset()
Get timezone offset in hours
public
static getTimezoneOffset(string $timezone[, DateTime|null $datetime = null ]) : float
Parameters
- $timezone : string
-
Timezone identifier
- $datetime : DateTime|null = null
-
Optional datetime (for DST calculation)
Return values
float —Offset in hours (e.g., -6.0 for CST, -5.0 for CDT)
getUserTimezone()
Get the timezone for a specific user/member
public
static getUserTimezone([Member|array<string|int, mixed>|null $member = null ][, string|null $default = null ]) : string
Resolves timezone in priority order:
- Member's timezone field
- Application default timezone
- UTC fallback
Parameters
- $member : Member|array<string|int, mixed>|null = null
-
Member entity, array with timezone, or null
- $default : string|null = null
-
Default timezone if member has none (overrides app default)
Return values
string —Valid timezone identifier
isValidTimezone()
Validate if a string is a valid timezone identifier
public
static isValidTimezone(string $timezone) : bool
Parameters
- $timezone : string
-
Timezone identifier to validate
Return values
bool —True if valid, false otherwise
toUserTimezone()
Convert a UTC datetime to user's timezone (or gathering's timezone if provided)
public
static toUserTimezone(DateTime|string|null $datetime[, Member|array<string|int, mixed>|null $member = null ][, string|null $fallbackTimezone = null ][, Gathering|array<string|int, mixed>|null $gathering = null ]) : DateTime|null
Parameters
- $datetime : DateTime|string|null
-
UTC datetime
- $member : Member|array<string|int, mixed>|null = null
-
Member entity or array
- $fallbackTimezone : string|null = null
-
Fallback timezone if member has none
- $gathering : Gathering|array<string|int, mixed>|null = null
-
Optional gathering for event timezone priority
Return values
DateTime|null —Datetime in user's timezone or null if input is null
toUtc()
Convert a datetime from a specific timezone to UTC
public
static toUtc(DateTime|string|null $datetime[, string|null $sourceTimezone = null ][, Member|array<string|int, mixed>|null $member = null ]) : DateTime|null
Used when receiving user input that's in their local timezone
Parameters
- $datetime : DateTime|string|null
-
Datetime in source timezone this field should not be timezone aware as it should be a user input.
- $sourceTimezone : string|null = null
-
Source timezone (defaults to user timezone)
- $member : Member|array<string|int, mixed>|null = null
-
Member for timezone resolution
Return values
DateTime|null —Datetime converted to UTC or null if input is null