TIL: The Timezone parameter in CFML Date/Time Functions

The applications I’ve built up to this point haven’t needed to account for time zones (and for that I consider myself fairly fortunate), which is probably one of the reasons that I only just discovered that ColdFusion’s date/time functions can accept a timezone parameter.

Well, that’s not exactly true. Both Adobe ColdFusion (10+) and Lucee have a dateTimeFormat function, which can optionally accept a timezone parameter. Here’s what it looks like:

// writing this example at 6:42 AM
datetime = now();
mask = "mm/dd/yyyy HH:nn zzz";

east = datetime.dateTimeFormat(mask, "EST");
// 11/30/2020 06:42 EST

west = datetime.dateTimeFormat(mask, "PST");
// 11/25/2020 03:42 PST

A few things to note here:

Now there are two questions that you might be asking yourself. First, how do I create a DateTime object that I can use with dateTimeFormat? For this, you can use createDateTime, as shown here:

datetime = createDateTime(2020, 11, 30, 6, 42);
west = datetime.dateTimeFormat(mask, "PST");
// 11/30/2020 03:42 PST

Second, and perhaps more importantly… what is the default time zone for these DateTime objects that we’re creating? That is, if you use now() or createDateTime(), what is the time zone that you’re starting from? You can find this out by using another function that I just learned about: getTimezoneInfo, which retrieves the time zone information for the machine it is running on. The specific information returned by Lucee and Adobe ColdFusion differs slightly, but both let you know the UTC time offset:


Additional Lucee Support

While writing this, I also learned that Lucee supports the timezone parameter in nearly all of its DateTime methods. So, you can explicitly set the time zone in dateFormat, timeFormat, createDateTime, and more. That’s really helpful!

Additional Resources

After writing this article, I found two other resources that cover the same topic. They’re linked from the Lucee docs, but somehow I missed them:

Happy time-zoning!

  1. While technically I only need one z, I’m using three so that the mask and output more closely resemble each other. The date masks follow Java’s SimpleDateFormat class. When masking time zones, lower case z is used for time zone abbreviations, zzzz is used for the full time zone name, and Z produces the RFC 822 time zone; for me, -0500