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
Time zone related querying
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
orTime.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.