KMP PHP API Reference

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
see
TimezoneHelper

Core timezone conversion logic

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

$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 resolution
  • int (IntlDateFormatter constant) → Date/time style for localized formatting
  • array → 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
string

getAbbreviation()

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
bool

isMemberContext()

Determine if the provided context should be treated as a member reference.

protected isMemberContext(mixed $context) : bool
Parameters
$context : mixed

Potential member context

Return values
bool

        
On this page

Search results