Skip to main content
Let’s get started!
View all Services
Development
Design
Product
Team and Processes
View all Services
View all Resources
Development
The business of great software
View all Resources

It's About Time (Zones)

Elle Meredith

This is the first article of a 2-part series. The second article is about a case study in multiple time zones.

Ruby provides two classes to manage time: Time and DateTime. Since Ruby 1.9.3 there are fewer differences between the two libraries, with Time covering concepts of leapseconds and daylight saving time. For the rest of this article, Time will be used in all the examples.

TZInfo is another time zone library, which provides daylight-saving-aware transformations between times in different time zones. It is available as a gem and includes data on 582 different time zones.

Time zones in Rails

Rails’ ActiveSupport::TimeZone is a wrapper around TZInfo that limits the set of zones provided by TZInfo to a meaningful subset of 146 zones. It displays zones with a friendlier name (e.g. “Eastern Time (US & Canada)” instead of “America/New_York”). And together with ActiveSupport::TimeWithZone, Rails provides the same API as Ruby Time instances, so that Time and ActiveSupport::TimeWithZone instances are interchangeable, and you should never need to create a TimeWithZone instance directly via new.

In Rails, to see all the available time zones, run:

$ rake time:zones:all
* UTC -11:00 *
American Samoa
International Date Line West
Midway Island
Samoa

* UTC -10:00 *
Hawaii

* UTC -09:00 *
Alaska
...

To check for the current set time zone, in console:

> Time.zone
=> #<ActiveSupport::TimeZone:0x007fbf46947b38
 @current_period=#<TZInfo::TimezonePeriod: nil,nil,#<TZInfo::TimezoneOffset: 0,0,UTC>>>,
 @name="UTC",
 @tzinfo=#<TZInfo::TimezoneProxy: Etc/UTC>,
 @utc_offset=nil>

Still in console, to temporarily set a different time zone:

# in console
> Time.zone = "Perth"

We can also permanently change our application time zone by setting a config option in config/application.rb:

# config/application.rb
config.time_zone = "Perth"

The default time zone in Rails is UTC. As tempting as it may seem, it is best to leave the application-wide time zone as UTC and instead allow each individual user to set their own time zone. Check a case study in multiple time zones to see an example why.

With user time zones

Let’s decide that each of our users have their time zone defined. This can be done by adding :time_zone attribute to the User model. Our migration might look like so:

create_table :users do |t|
  t.string :time_zone, default: "UTC"
  ...
end

We want to store the time zone as a string because most of Rails’ time-zone-related methods use strings. Above all, avoid storing time zones as :enums.

We can allow a user to set their own desired time zone when editing their profile. SimpleForm supports :time_zone and provides a form helper so the user can select a time zone option from a select menu.

<%= f.input :time_zone %>

We can then use an around_action in ApplicationController to apply our user’s preferred time zone.

# app/controllers/application_controller.rb
around_action :set_time_zone, if: :current_user

private

def set_time_zone(&block)
  Time.use_zone(current_user.time_zone, &block)
end

We pass the current user’s time zone to use_zone method on the Time class (a method which was added by ActiveSupport). This method expects a block to be passed to it and sets the time zone for the duration of that block, so that when the request completes, the original time zone is set back.

If you are using Rails 3.2.13 or lower, instead of using around_action you will need to use around_filter.

And lastly, to display times in a specific user’s time zone, we can use Time‘s in_time_zone method:

<%= time.in_time_zone(current_user.time_zone) %>

Working with APIs

When working with APIs, it is best to use the ISO8601 standard, which represents date/time information as a string. ISO8601’s advantages are that the string is unambiguous, human readable, widely supported, and sortable. The string looks like:

> timestamp = Time.now.utc.iso8601
=> "2015-07-04T21:53:23Z"

The Z at the end of the string indicates that this time is in UTC, not a local time zone. To convert the string back to a Time instance, we can say:

> Time.iso8601(timestamp)
=> 2015-07-04 21:53:23 UTC

Three time zones

In a Rails app, we have three different time zones:

  • system time,
  • application time, and
  • database time.

Say we set our time zone to be Fiji. Let’s see what happens:

# This is the time on my machine, also commonly described as "system time"
> Time.now
=> 2015-07-04 17:53:23 -0400

# Let's set the time zone to be Fiji
> Time.zone = "Fiji"
=> "Fiji"

# But we still get my system time
> Time.now
=> 2015-07-04 17:53:37 -0400

# However, if we use `zone` first, we finally get the current time in Fiji
> Time.zone.now
=> Sun, 05 Jul 2015 09:53:42 FJT +12:00

# We can also use `current` to get the same
> Time.current
=> Sun, 05 Jul 2015 09:54:17 FJT +12:00

# Or even translate the system time to application time with `in_time_zone`
> Time.now.in_time_zone
=> Sun, 05 Jul 2015 09:56:57 FJT +12:00

# Let's do the same with Date (we are still in Fiji time, remember?)
# This again is the date on my machine, system date
> Date.today
=> Sat, 04 Jul 2015

# But going through `zone` again, and we are back to application time
> Time.zone.today
=> Sun, 05 Jul 2015

# And gives us the correct tomorrow according to our application's time zone
> Time.zone.tomorrow
=> Mon, 06 Jul 2015

# Going through Rails' helpers, we get the correct tomorrow as well
> 1.day.from_now
=> Mon, 06 Jul 2015 10:00:56 FJT +12:00

Rails saves timestamps to the database in UTC time zone. We should always use Time.current for any database queries, so that Rails will translate and compare the correct times.

Post.where("published_at > ?", Time.current)
# SELECT "posts".* FROM "posts" WHERE (published_at > '2015-07-04 17:45:01.452465')

A summary of do’s and don'ts with time zones

DON’T USE 

* Time.now
* Date.today
* Date.today.to_time
* Time.parse("2015-07-04 17:05:37")
* Time.strptime(string, "%Y-%m-%dT%H:%M:%S%z")

DO USE 

* Time.current
* 2.hours.ago
* Time.zone.today
* Date.current
* 1.day.from_now
* Time.zone.parse("2015-07-04 17:05:37")
* Time.strptime(string, "%Y-%m-%dT%H:%M:%S%z").in_time_zone

Testing time zones

Rails 4.1 added a ActiveSupport::Testing::TimeHelpers module, with three useful methods: travel, travel_back, and travel_to. We can use these methods to freeze time within blocks in our tests.

If using an older version of Rails, there are three gems to help us set and freeze the time in our tests: Timecop, Delorean, and Zonebie. As much as I love the reference to go back_to_the_present, I usually use Timecop.

new_time = Time.zone.parse("2014-10-19 1:00:00")

# With Timecop, we can freeze the time,
Timecop.freeze new_time

# or
Timecop.travel new_time

# but will need to clean up after the spec, and return to current time
Timecop.return

# Alternatively we can use blocks, which only freeze the time inside our block
Time.use_zone("Sydney") do
end

# With Delorean, the syntax is a touch different
Delorean.time_travel_to("1 month ago") do
end
Delorean.back_to_the_present

# And Zonebie sets the time zone to a random one each time we run our tests
Zonebie.set_random_timezone

If you want to learn how to persist future datetimes: check out How to save datetimes for future events article by Lau Taarnskov.

In summary

  • Always work with UTC.
  • Use Time.current or Time.zone.today.
  • Use testing helper methods of your choice to freeze the time in your tests, preferably by using a block.

Also remember to check out the second part of this article at a case study in multiple time zones.