TimezoneHelper
extends Helper
in package
Timezone View Helper for template-friendly datetime formatting.
Provides wrappers for timezone conversion and display methods: format(), date(), time(), forInput(), range(), smartRange(), getUserTimezone(), getAbbreviation().
Integrates with \App\KMP\TimezoneHelper service for actual conversions.
Tags
Table of Contents
Properties
- $Form : FormHelper
- $currentUser : Member|array<string|int, mixed>|null
- Current user/member for timezone resolution
- $helpers : array<string|int, string>
- Helpers used by this helper
Methods
- date() : string
- Format date only (no time)
- forInput() : string
- Format datetime for form input (datetime-local format)
- format() : string
- Format a datetime in the viewer's timezone.
- getAbbreviation() : string
- Get timezone abbreviation for current user or specific timezone
- getOffset() : float
- Get timezone offset in hours
- getTimezoneOptions() : array<string|int, mixed>
- Create a timezone selector dropdown for forms
- getUserTimezone() : string
- Get the current user's timezone
- initialize() : void
- Initialize helper
- notice() : string
- Display a timezone notice for the user
- range() : string
- Format a date range
- smartRange() : string
- Smart date range formatting
- time() : string
- Format time only (no date)
- isGatheringContext() : bool
- Determine if the provided context should be treated as a gathering reference.
- isMemberContext() : bool
- Determine if the provided context should be treated as a member reference.
Properties
$Form
public
FormHelper
$Form
$currentUser
Current user/member for timezone resolution
protected
Member|array<string|int, mixed>|null
$currentUser
= null
$helpers
Helpers used by this helper
protected
array<string|int, string>
$helpers
= []
Methods
date()
Format date only (no time)
public
date(DateTime|string|null $datetime[, string|null $format = null ][, Member|array<string|int, mixed>|null $member = null ][, Gathering|array<string|int, mixed>|null $gathering = null ]) : string
Parameters
- $datetime : DateTime|string|null
-
UTC datetime to format
- $format : string|null = null
-
PHP date format (null = default)
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
- $gathering : Gathering|array<string|int, mixed>|null = null
-
Gathering for event timezone priority
Return values
string —Formatted date string
forInput()
Format datetime for form input (datetime-local format)
public
forInput(DateTime|string|null $datetime[, string|null $format = null ][, Member|array<string|int, mixed>|null $member = null ][, Gathering|array<string|int, mixed>|null $gathering = null ]) : string
Converts UTC to user's timezone (or gathering's timezone) in HTML5 datetime-local format (Y-m-d\TH:i)
Parameters
- $datetime : DateTime|string|null
-
UTC datetime
- $format : string|null = null
-
Format string (default: Y-m-d\TH:i for datetime-local)
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
- $gathering : Gathering|array<string|int, mixed>|null = null
-
Gathering for event timezone priority
Return values
string —Formatted datetime for input field
format()
Format a datetime in the viewer's timezone.
public
format(DateTime|FrozenTime|string|null $datetime, mixed ...$args) : string
This method accepts a flexible argument list so older call signatures are still supported. You may pass arguments in any order and by type they will be assigned as follows:
string→ Custom PHP date format string (e.g.,'Y-m-d H:i')bool→ Whether to append timezone abbreviation\App\Model\Entity\Member→ Member context for timezone resolution\App\Model\Entity\Gathering→ Gathering context for timezone resolutionint(IntlDateFormatter constant) → Date/time style for localized formattingarray→ Options array with any of the keys:format,includeTimezone,member,gathering,intlDateFormat,intlTimeFormat
Examples:
$this->Timezone->format($datetime); // default display format
$this->Timezone->format($datetime, true); // include timezone abbreviation
$this->Timezone->format($datetime, $member, 'Y-m-d'); // member context + format string
$this->Timezone->format($datetime, $gathering, 'M j, Y'); // gathering context + format
$this->Timezone->format($datetime, null, null, IntlDateFormatter::SHORT, IntlDateFormatter::SHORT);
Parameters
- $datetime : DateTime|FrozenTime|string|null
-
UTC datetime/value to format
- $args : mixed
-
Additional context/formatting options
Return values
stringgetAbbreviation()
Get timezone abbreviation for current user or specific timezone
public
getAbbreviation([DateTime|Date|string|null $datetime = null ][, string|null $timezone = null ][, Member|array<string|int, mixed>|null $member = null ]) : string
Parameters
- $datetime : DateTime|Date|string|null = null
-
Datetime for DST calculation (null = now)
- $timezone : string|null = null
-
Specific timezone identifier (null = use member/user timezone)
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
Return values
string —Timezone abbreviation (e.g., "CDT", "EST")
getOffset()
Get timezone offset in hours
public
getOffset([Member|array<string|int, mixed>|null $member = null ][, DateTime|null $datetime = null ]) : float
Parameters
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
- $datetime : DateTime|null = null
-
Datetime for DST calculation (null = now)
Return values
float —Offset in hours (e.g., -6.0 for CST, -5.0 for CDT)
getTimezoneOptions()
Create a timezone selector dropdown for forms
public
getTimezoneOptions([bool $commonOnly = true ]) : array<string|int, mixed>
Parameters
- $commonOnly : bool = true
-
Show only common timezones (default: true)
Return values
array<string|int, mixed> —Options array for Form->control()
getUserTimezone()
Get the current user's timezone
public
getUserTimezone([Member|array<string|int, mixed>|null $member = null ]) : string
Parameters
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
Return values
string —Timezone identifier (e.g., "America/Chicago")
initialize()
Initialize helper
public
initialize(array<string|int, mixed> $config) : void
Parameters
- $config : array<string|int, mixed>
-
Configuration options
notice()
Display a timezone notice for the user
public
notice([string $class = 'text-muted small' ][, Member|array<string|int, mixed>|null $member = null ]) : string
Outputs a small notice showing the user which timezone is being used
Parameters
- $class : string = 'text-muted small'
-
CSS class for the notice
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
Return values
string —HTML for timezone notice
range()
Format a date range
public
range(DateTime|string|null $start, DateTime|string|null $end[, string $separator = ' - ' ][, string|null $format = null ][, Member|array<string|int, mixed>|null $member = null ]) : string
Parameters
- $start : DateTime|string|null
-
Start datetime
- $end : DateTime|string|null
-
End datetime
- $separator : string = ' - '
-
Separator between dates (default: " - ")
- $format : string|null = null
-
Format string for each date
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
Return values
string —Formatted date range
smartRange()
Smart date range formatting
public
smartRange(DateTime|string|null $start, DateTime|string|null $end[, Member|array<string|int, mixed>|null $member = null ]) : string
If same day: "March 15, 2025 9:00 AM - 5:00 PM" If different days: "March 15, 2025 - March 17, 2025"
Parameters
- $start : DateTime|string|null
-
Start datetime
- $end : DateTime|string|null
-
End datetime
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
Return values
string —Smart formatted date range
time()
Format time only (no date)
public
time(DateTime|string|null $datetime[, string|null $format = null ][, Member|array<string|int, mixed>|null $member = null ][, Gathering|array<string|int, mixed>|null $gathering = null ]) : string
Parameters
- $datetime : DateTime|string|null
-
UTC datetime to format
- $format : string|null = null
-
PHP time format (null = default)
- $member : Member|array<string|int, mixed>|null = null
-
Specific member (null = current user)
- $gathering : Gathering|array<string|int, mixed>|null = null
-
Gathering for event timezone priority
Return values
string —Formatted time string
isGatheringContext()
Determine if the provided context should be treated as a gathering reference.
protected
isGatheringContext(mixed $context) : bool
Parameters
- $context : mixed
-
Potential gathering context
Return values
boolisMemberContext()
Determine if the provided context should be treated as a member reference.
protected
isMemberContext(mixed $context) : bool
Parameters
- $context : mixed
-
Potential member context