Skip to content

Date and Time Manipulation

Supported date and time formats

In WebhookScript, dates are not a specific type, but rather expressed as strings that WebhookScript will attempt to parse using a very powerful date parsing engine.

WebhookScript supports a variety of date formats, and functions taking a date will attempt to guess the format of the input string in order to parse the date into a ISO-8601 format

If possible, it's recommended to use the ISO-8601 format, for example 2020-05-27T04:00:00.000000Z.

Special format examples

In addition to date strings, these special formats can also be used to generate dates.

  • now
  • +4 day, -2 month - adds or subtracts to the current date and time, can be suffixed to other dates
  • Other units supported: second, minute, hour, day, fortnight, week, month, year
  • next Thursday
  • last Monday
  • first day of January 2008
  • first Saturday of July 2008
  • Monday next week
  • @1215282385 - UNIX timestamp

Date format characters

Click here for a list of possible date format characters for the to_date and date_format functions.

Date locales available

Click here for a list of possible locales/translations available for date display functions.

now(?string timezone) : string

Returns the current date in ISO-8601 format, using timezone, if specified.

to_date(string date, ?string format, ?locale locale, ?string timezone, bool keep_timezone = false): string

Returns a ISO-8601 formatted date string in UTC time from the provided date string. For more information about the accepted dates, see Supported date formats. If specified, format is used to parse the date without having to guess the format (see the Date Format Characters specification.) If the keep_timezone parameter is set to true, the resulting date string will keep the timezone. The locale parameter will attempt to parse the date using the specified locale.

If the date is invalid or could not be guessed, null is returned.

// Current date and time
// -> 2020-11-25T00:00:00.000000Z

// Relative formats
'first monday august 2019'.to_date()

// Automatic format guessing
'2020-01-01 23:02:01'.to_date()

// Timezone handling
'2020-01-01 23:02:01'.to_date(null, null, 'GMT-5')
// -> "2020-01-02T04:02:01.000000Z", interpreted as GMT-5 and converted to UTC

'2020-01-01 23:02:01'.to_date(null, null, 'GMT-5', true)
// -> "2020-01-01T23:02:01.000000-05:00", date keeps timezone

// Unix timestamp

// Custom date format
'2/4/12 06:03'.to_date('M/D/YY HH:mm')
// -> 2012-02-04T06:03:00.000000Z

// To escape characters in the format string, backslashes can be used
'2020-01-05 12h30m15s'.to_date('YYYY-MM-DD HH\\hmm\\mss\\s')
// -> 2020-01-05T12:30:15.000000Z

date_format(string date, ?string format, ?string locale, ?string timezone): string

Returns a date parsed to the format specified in format. For more information about the accepted dates, see Supported date formats. For a full list of date format characters, see the Date Format Characters specification.

date_format('2008-07-05T18:26:25.000000Z', 'YYYY-MM-DD') 
// -> 2008-07-05

date_format('2008-07-05T18:26:25.000000Z', 'LLLL', 'da') 
// -> lørdag d. 5. juli 2008 kl. 18:26

date_format('2020-01-01T23:02:01.000000-05:00', 'LLLL', null, 'GMT+2') 
// -> Thursday, January 2, 2020 6:02 AM

// If no format is specified, a default human readable readable string is returned
// -> Sat Jul 05 2008 18:26:25 GMT+0000

// -> 1606329669220 (current date in UNIX timestamp with microseconds)

// Add 1 hour to an existing date (see Special format examples above)
date_format('2021-10-28 11:28:55 +1 hour', 'YYYY-MM-DD HH:mm:ss')
// -> 2021-10-28 12:28:55

date_to_array(string): array

Returns an array containing all the components of a given date.


// [
//   "year": 2008,
//   "month": 7,
//   "day": 5,
//   "dayOfWeek": 6,
//   "dayOfYear": 187,
//   "hour": 18,
//   "minute": 26,
//   "second": 25,
//   "micro": 324542,
//   "timestamp": 1215282385,
//   "formatted": "2008-07-05 18:26:25",
//   "timezone": "Z"
// ]

date_interval(string date1, ?string date2, ?string format): string/int

Calculates the interval between date1 and date2. When date2 is unspecified/null, now is used.

If no format string is specified, the interval is returned as the number of seconds between the dates, with the number being negative if date2 is before date1.

Note that for the format string, this function does not use the ISO format, but rather the uses the PHP DateInterval format specification.

date_interval('2008-07-16T23:13:26.234212Z', '2008-07-05T18:26:25.324542Z') 
// -> -967620

    '%d days, %h hours, %i minutes'
// -> 11 days, 4 hours, 47 minutes

date_interval_human(string date1, ?string date2, ?string locale): string/int

Formats the difference between 2 dates in a way that's easy to read for humans.

If no locale is specified, English is used. When date2 is unspecified/null, now is used.

// -> 1 week after

// -> 1 semana después