Formatting Date & Time

LiveWhale uses PHP’s date formatting functions. You can use the following date formatting characters below to build date format strings to use in LiveWhale widgets. See the formatting options with examples below:

Date Variables

Variable Description Values
%d Day of month, with leading zeros 01-31
%j Day of month, without leading zero 1-31
%S The English suffix for the day of the month st, nd, or th in the 1st, 2nd, or 15th
%l Day of week, full name (lowercase ‘L’) Sunday – Saturday
%D Day of week, three letter name Mon – Sun
%m Month, numeric, with leading zeros 01–12
%n Month, numeric, without leading zeros 1–12
%F Month, full text January – December
%M Month, three letter name Jan – Dec
%Y Year, 4 digits 1999, 2019
%y Year, 2 digits 99, 19
%c Full date-time, ISO 8601 2004-02-14T15:19:25+00:00
%r Full date-time, RFC 2822 Sat, 14 Feb 2015 16:01 +0200

Time Variables

Variable Description Values
%g Hour, 12-hour, without leading zeros 1-12
%h Hour, 12-hour, with leading zeros 01-12
%G Hour, 24-hour, without leading zeros 0-23
%H Hour, 24-hour, with leading zeros 00-23
%i Minutes, with leading zeros 00-59
%s Seconds, with leading zeros 00-59
%a Lowercase am, pm
%A Uppercase AM, PM
%T Timezone abbreviation Ex., EST, PST

Note: The PHP date formats don’t natively allow for dots in am/pm (e.g., a.m. and p.m.), but for calendar events in LiveWhale you can choose to display them with dots by enabling <arg id="ampm_with_dots">true</arg> in your calendar widget settings.


Here are some examples of date format strings and result output that can be used in LiveWhale widgets.

The % sign means that the format character should represent a format variable and not a string that would display “as-is”.

Example Code Value
%F %j, %Y January 16, 2020
%F, %Y January, 2020
%l, %F %j%S, %Y Thursday, January 16, 2020
%g:%i %a 12:50 am
%Y/%m/%d 2020/01/16
%Y/%m/%d %g:%i %A 2020/01/16 10:26 AM
%M %j, %Y Jan 16, 2020
Current Date: %F %j%S Current Date: January 16th

Customizing the timezone display

In general, LiveWhale shows you a timezone abbreviation when an event’s time differs from your local timezone. (This can be removed globally from the calendar by using the disable_timezone widget argument.)

These use the PHP system abbreviation if known (e.g. “EST, PST”) or the GMT offset if not (“+05”). In certain cases these abbreviations may be confusing, for instance if you have events happening in both US Central Standard Time and China Standard Time, both use “CST.”

Therefore, in LiveWhale 2.0.0+, you can add the following to livewhale/client/global.config.php to override the abbreviations for individual locations and provide a fully spelled-out timezone:

// override timezone abbreviations for specific locations, applies to front-end and back-end views
'Asia/Macau' => 'China Standard Time',
'Asia/Shanghai' => 'China Standard Time'

The first value in each pairing is the PHP timezone (full list), and the second is the string you’d like to display in place of its default abbreviation. If you find yourself needing to customize a timezone display but are uncertain of what values to use in the above array, feel free to reach out to support for assistance.

Using AP Style for dates and times

In LiveWhale 2.9.0+ you can use AP Style date/time formatting sitewide by adding this to livewhale/client/global.config.php:

$_LW->CONFIG['USE_AP_STYLE'] = true; // Use AP style date and time formatting site-wide

This will make the following changes to all calendars, details pages, widgets, and API results:

  • Abbreviate certain month names—Jan., Feb., Aug., Sept., Oct., Nov., and Dec.—when used with a date. (When used with only a year, don’t abbreviate.)
  • Use a.m./p.m. instead of am/pm
  • Remove :00 when listing times (e.g., 2 pm)
  • Use noon/midnight instead of 12 p.m./12 a.m.
  • Don’t repeat the same a.m./p.m. in a time range (e.g., 4:30 – 6 p.m.)
  • Remove leading zeroes from date/month when used in date format
  • Add comma after date when format includes full date (e.g., January 1, 2024)

Certain cases (for instance, UTC timestamps in API results) will bypass the use of AP Style in order to preserve functionality.

Formatting start_date and end_date in widget settings and API requests

In general, when setting start_date or end_date in your widget settings or API requests, LiveWhale supports any PHP-readable date string. This allows for great flexibility, for example:

Example Date Widget Setting LiveWhale Calendar – Inline Widget Setting API Request
-24 hours <arg id="start_date">-24 hours</arg> data-options="id=123&start_date=-24 hours" /live/json/events/start_date/-24%20hours
-4 weeks <arg id="start_date">-4 weeks</arg> data-options="id=123&start_date=-4 weeks" /live/json/events/start_date/-4%20weeks
last Friday <arg id="start_date">last Friday</arg> data-options="id=123&start_date=last Friday" /live/json/events/start_date/last%20Friday
Sunday 11:59pm <arg id="end_date">Sunday 11:59pm</arg> data-options="id=123&end_date=Sunday 11:59pm" /live/json/events/end_date/Sunday%2011:59pm
Saturday +4 weeks <arg id="end_date">Saturday +4 weeks</arg> data-options="id=123&end_date=Saturday +4 weeks" /live/json/events/end_date/Saturday%20%2B4%20weeks
+1 year <arg id="end_date">+1 year</arg> data-options="id=123&end_date=+1 year" /live/json/events/end_date/+1%20year

Using DD-MM vs MM/DD

However, when using specific date strings like 01-01-2024 or 04/03/2022, the default PHP date parsing works differently depending on the use of dashes vs slashes:

  • 04/06/2023 is interpreted month-first as April 6, 2023 (MM/DD/YYYY)
  • 04-06-2023 is interpreted day-first as June 4, 2023 (DD-MM-YYYY)

This can cause confusion since some LiveWhale contexts allow using either dashes or slashes (e.g., widget settings) and others require dashes (e.g., the REST API). One way around this ambiguity is to use YYYY-MM-DD when setting up API integrations or overriding widget settings.

However, we don’t want developers thinking hard about the difference between 04-06 and 04/06. So, in LiveWhale 2.10.0 we’ve added a configuration setting which, when enabled, bypasses this dashes-vs-slashes question and always use one format across all settings and filters.

$_LW->CONFIG['FILTER_USING_LOCAL_DATE_FORMAT']=true; // When true, widgets and API requests will treat all start and end dates as MM-DD-YYY (in US timezones) and DD-MM-YYYY in (European/Australian timezones), regardless of whether dashes or slashes were used.

With this setting enabled in global.config.php, all date strings will be treated as:

  • US timezones: month-first, i.e., MM-DD-YYYY or MM/DD/YYYY
  • European/Australian timezones: day-first, i.e., DD-MM-YYYY or DD/MM/YYYY

We expect this to become the default behavior in LiveWhale 3.0 but have implemented it as a configurable setting in the meantime to preserve backwards-compatibility for existing widgets and API requests across LiveWhale 2.x.