Skip to content

Date Manipulation

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.

However, if possible, we recommend using either a specific date format like ISO-8601, or specifying the date format precisely using the to_date function, which removes the risk of misparsing.

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.

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

Will attempt to parse a string to a ISO-8601 formatted date string in UTC time. 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 specified, format is used to parse the date without having to guess the format (see the Date Format Characters specification.)

Many formats are supported, like relative dates and various specified date formats.

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

// Relative formats
to_date('last wednesday 4 am')         // 2020-05-27T04:00:00.000000Z
'first monday august 2019'.to_date()   // 2019-08-05T00:00:00.000000Z

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

// 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
'@1215282385'.to_date()                // 2008-07-05T18:26:25.000000Z

// 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 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
date_format('2008-07-05T18:26:25.000000Z') // Sat Jul 05 2008 18:26:25 GMT+0000

date_to_array(string): array

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

dump(date_to_array('2008-07-05T18:26:25.324542Z'))

// [
//   "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.

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

date_interval(
    '2008-07-16T23:13:26.234212Z',
    '2008-07-05T18:26:25.324542Z',
    '%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.

date_interval_human(
    '2008-07-16T23:13:26.234212Z',
    '2008-07-05T18:26:25.324542Z'
)
// 1 week after

date_interval_human(
    '2008-07-16T23:13:26.234212Z',
    '2008-07-05T18:26:25.324542Z',
    'es'
)
// 1 semana después