Efficient User Timezone Handling in Laravel

Last Updated on May 27, 2023

In today’s world, web applications often cater to users from various timezones. Whether it’s scheduling events, displaying accurate timestamps, or managing user interactions, correctly handling time zones is crucial for delivering a seamless user experience.

However, managing time zones can be a complex task, especially when dealing with different regions, daylight-saving time changes, and user preferences.

When building an application, it is almost a given that you will be storing DateTime and other timestamp-related data. Laravel creates a created_at and updated_at column in each of the migration files by default and handles the process of adding them correctly in the database.

Most of us are in different time zones and as a result, we need to store all dates in UTC. This is a primary time standard that the world regulates clocks and time. It is useful in that it is universally accepted as the default time standard because it lies at 0° longitude.

Most applications store dates and times in this format. While this is good, it brings rise to another set of problems. Since most of us are in different time zones, we might need to reference our local time in reference to the UTC timezone.

This is no different in many applications. We need to factor in that users of our applications are in different timezones and therefore we need to display data for them in the frontend based on their timezone. You can find a list of all timezones here.

Earlier, I created an article on Date Scopes that allowed us to fetch data from the database using date ranges. This results in Laravel fetching data from the database using the default app timezone(UTC). We might need to change the logic to factor in the user’s timezone. For example, a user in Sydney Australia is in UTC +10 timezone meaning that they are 10 hours ahead of UTC. Therefore if we want to correctly display records for them, fetching based on UTC only will be of no value to them as today for them might be the previous day in UTC.

How do we fetch data based on the user’s timezone? In this article, we will explore how to properly manage user time zones in Laravel. Laravel provides robust support for date and time manipulation using the Carbon Library. Carbon can be used to convert date and time values to the correct timezone for the user.

Storing Dates in UTC

In software development, storing dates and times consistently and accurately is a fundamental aspect of building reliable applications. One widely adopted best practice is to store dates in Coordinated Universal Time (UTC) within your application’s database. Storing dates in UTC brings numerous benefits and helps overcome the complexities associated with timezones and daylight-saving time changes.

When dates are stored in UTC, you establish a common reference point for all operations across different time zones. UTC is a standardized global time, unaffected by local variations such as daylight saving time adjustments or regional timezone differences. This consistency ensures that regardless of the user’s location, the stored date and time values will remain the same.

By using UTC as the internal representation of dates in your database, you eliminate ambiguities that arise when storing dates in local timezones. Consider a scenario where a user creates an appointment in their local timezone. If the date and time are stored as-is without conversion, complications can arise when users in different time zones access and interpret that information. Storing dates in UTC mitigates this issue by providing a universal reference for calculations and comparisons.

Carbon to the Rescue.

As we have seen, there are many complexities that arise when dealing with multiple time zones. We have established that storing date and time in UTC is the best approach as it provides a central reference point. This not only helps us maintain consistency in our application but also does not suffer from time adjustments during various seasons such as during winter or summer.

Carbon library is a powerful tool that simplifies the manipulation and management of datetime values in Laravel. It provides various utility functions such as Carbon::now() or Carbon::today() and this helps in working with dates and times.

Carbon helps us parse dates and convert them to various formats and thus you can display the date objects in human-readable formats.

One of the key strengths of Carbon is its seamless support for working with time zones. It simplifies timezone conversions by providing various ways of setting the timezone of Carbon objects.

The first way is to use the setTimezone() method. This method allows you to convert a Carbon object to a different timezone while preserving the underlying datetime value.

Carbon::now()->setTimezone(‘Australia/Sydney’);

This snippet will get the current time in UTC and convert it to Sydney’s local time.

The next way is to set the Timezone directly in the object instance

Carbon::now(‘Australia/Sydney’);

This approach automatically sets the timezone of the newly created Carbon object to the specified timezone. This means that the Carbon will not preserve the underlying datetime value as it is instantiated with the DateTime for that timezone which in our case is getting the current local time for Sydney.

When should you use one or the other?

now($timezone)

The now($timezone) method is ideal when you need to work with the current datetime in a specific timezone and doesn’t require any subsequent timezone conversions. It creates a Carbon object directly in the desired timezone, ensuring that any further operations performed on that object are in the specified timezone. This approach is concise and convenient, particularly in scenarios where you want to isolate datetime operations within a specific timezone.

now()->setTimezone($timezone)

Using now()->setTimezone($timezone) is suitable when you already have a Carbon object and need to perform conversions between different timezones. For example, if you have a Carbon object representing the current datetime in the application’s timezone, you can use now()->setTimezone(‘Australia/Sydney’’) to convert it to the “Australia/Sydney” timezone.

This is useful when you are working with a lot of timezones and you need to instantiate a date object in UTC and then convert it to other timezones.

Sync with the database (MYSQL).

All this effort will be useless if we have not configured our database server to be aware of various time zones.

I will use MYSQL as an example but there should be guides on other database engines.

To effectively manage time zones in your Laravel application, it is essential to have access to accurate and comprehensive timezone data. MySQL, the widely used database management system, provides built-in support for timezone data. By importing the appropriate timezone data into your MySQL server, you can ensure accurate conversions and consistent handling of DateTime values.

Understanding Timezone Data in MySQL

MySQL utilizes the timezone database, which contains a vast collection of timezone information, including geographical locations, daylight saving time rules, historical timezone changes, and more. This data is crucial for accurate timezone conversions and calculations.

Importing Timezone Data into MySQL

To import the timezone data into your MySQL server, you can use the mysql_tzinfo_to_sql utility provided by MySQL. This utility converts the timezone data files, usually located in the MySQL installation directory, into SQL statements that can be executed to populate the time_zone table in the MySQL database.

You can run the mysql_tzinfo_to_sql command from the command line, specifying the path to the timezone data files and the desired output file.

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql 

This command populates the time_zone table in the MySQL database, making the timezone data available for use within MySQL.

We can now use raw SQL to convert various columns to the user’s timezone.

SELECT CONVERT_TZ('2030-05-15 12:00:00','UTC','Australia/Sydney');

You can then prepare an Eloquent query that will be able to fetch records in the correct timezone.

Guessing/Requesting User Timezones

We have seen the benefits of giving users a personalized experience and providing this as the feature will allow them to see the value your application is providing to them. While the backend logic might be done, we still need to handle the frontend side of things.

Luckily, there are various ways we can request the user’s timezone.

User Preferences

This is an easy approach as users may explicitly provide their timezone preferences within their account settings or profile. This allows them to explicitly define their desired timezone, ensuring an accurate representation of dates and times throughout the application.

This can be in the form of a dropdown where a user is required to set their preferred timezones. You can then store this timezone in the database or as cookies.

Client-Side Timezone Guessing

At times the first approach might be limiting especially if your app is handling team support. An example is a user might hire contractors and invite them as team members into their account. In such as case, the contractors might be in different timezones from the user and as a result, if they were hired to provide insights on various data, the first approach might be limiting depending on their application use case.

We can employ certain techniques which would involve trying to guess the timezone of the current user. There are libraries such as moment-timezone that can help with that.

import moment from 'moment-timezone';

const timezone = moment.tz.guess();

While not accurate, the library will try and guess the timezone and you can attach the timezone as a header or body when making requests to the backend. This helps give a personalized approach to all users in the system.

IP Geolocation

This is probably my least recommended approach. It involves getting the ip of the user and using it to try and get the user’s timezone. I recommend it the least because using the user’s IP might not yield the correct result simply because users might be using VPNs and as a result can lead to skewed results.

I would use it as a backup in case the first two approaches are not yielding any good results.

if ($request->hasHeader('X-Timezone')) {
     $timezone = $request->header('X-Timezone');
} else {         
    $ip = $request->ip();
    $url = "http://ip-api.com/json/$ip";

    $tz = file_get_contents($url);
    $timezone = json_decode($tz, true)['timezone'];
  }
}

With that, you can get the user’s timezone which you can use in the backend to fetch the correct results.

Tying it all up.

Once we have handled the logic for both the front end and the back end, we can tie it all up.

php artisan make:controller AnalyticsController -r

I will set the timezone as a header and as a result, I will use Axios interceptors to set the timezone for the user.

//customAxios.js

import axios from "axios";
import moment from 'moment-timezone';

const instance = axios.create();

instance.interceptors.request.use( function (config) {
    const timezone = moment.tz.guess();
    config.headers['X-Timezone'] = timezone;
    return config;
});

export default instance;

Each request from the front end should have the X-Timezone header which we can retrieve in the backend.

//App/Http/Controllers/AnalyticsController

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Carbon;
use App\Models\Analytics;
use Illuminate\Http\Request;

class AnalyticsController extends Controller
{
  public function index(Request $request)
    {
        if ($request->hasHeader('X-Timezone')) {
            $timezone = $request->header('X-Timezone');
        } else {
            $ip = $request->ip();
            $url = "http://ip-api.com/json/$ip";
            $tz = file_get_contents($url);
            $timezone = json_decode($tz, true)['timezone'];
        }

        $startDate = $request->query('start');
        $endDate = $request->query('end');

        $start = Carbon::parse($startDate, $timezone)->startOfDay();
        $end = Carbon::parse($endDate, $timezone)->endOfDay();

        $query = DB::raw("CONVERT_TZ(`created_at`, 'UTC', '$timezone')");

        $analytics = Analytics::whereBetween($query, [$start, $end])
->get();

        return $analytics;
    }
}

We will use date ranges in this case to fetch records that are between a specific range.

And that’s pretty much it.

Conclusion

Managing user time zones in Laravel is a critical aspect of building applications that provide accurate and personalized experiences. By utilizing the powerful features of Laravel and the Carbon library, you can handle time-related operations efficiently and ensure consistent representation of dates and times across different time zones.

Throughout this article, we have explored various concepts and techniques to help you effectively manage user time zones in your Laravel application. I hope this article was insightful. Thank you for reading