timezone_offset_get()

The timezone_offset_get() function in PHP returns the timezone offset in seconds from Coordinated Universal Time (UTC) for a given DateTimeInterface object. This guide covers its syntax, parameters, and practical usage.

Understanding timezone_offset_get()

The timezone_offset_get() function returns the offset of the timezone in seconds from Coordinated Universal Time (UTC) for a specified date and time. It is a built-in PHP function that allows developers to manipulate dates and times according to specific timezones.

Syntax

The syntax for the timezone_offset_get() function in PHP is as follows:

The syntax of timezone_offset_get() function in PHP

<?php
timezone_offset_get(DateTimeZone $object, DateTimeInterface $datetime): int

Procedurally, the function takes a DateTimeZone and the DateTimeInterface you want the offset for, and returns the offset in seconds. Most people use the object-oriented equivalent, DateTimeZone::getOffset(), which reads more naturally:

<?php
$tz   = new DateTimeZone('America/Los_Angeles');
$date = new DateTime('2019-01-01 12:00:00', $tz);

// These two calls are equivalent:
$offset = timezone_offset_get($tz, $date);
$offset = $tz->getOffset($date);

Parameters

The timezone_offset_get() function takes two parameters:

1. $object - A DateTimeZone object whose offset you want to read.
2. $datetime - A DateTimeInterface object (a DateTime or DateTimeImmutable) representing the moment in time for which the offset is calculated.

The moment matters: because of Daylight Saving Time, the same timezone can have a different offset in summer than in winter, so you must tell the function which instant you mean.

Return Value & Notes

• Return Value: Returns an integer offset in seconds. It is negative for timezones west of UTC (the Americas) and positive for those east of it.
• PHP Version: Available since PHP 5.2.0.
• DST Handling: The offset automatically accounts for Daylight Saving Time. For America/Los_Angeles, a winter date returns -28800 (UTC-8) while a summer date returns -25200 (UTC-7).
• Hours, not seconds: To turn the result into hours, divide by 3600 (e.g. -28800 / 3600 = -8).

Practical Applications

The timezone_offset_get() function in PHP is a powerful tool for working with dates and times in specific timezones. Some practical applications of this function include:

1. Displaying date and time information according to the user's timezone preference.
2. Converting date and time information from one timezone to another.
3. Performing date and time calculations with accurate timezone offsets.

Example Usage

Here is an example usage of the timezone_offset_get() function in PHP:

Example of PHP timezone_offset_get() function

The January date falls outside DST, so the offset is -28800 seconds (UTC-8):

-28800

Seeing DST in action

Calling the same timezone with a summer date returns a different offset, because Pacific Daylight Time is UTC-7. Formatting the offset as hours makes the result easy to read:

<?php
$tz = new DateTimeZone('America/Los_Angeles');

foreach (['2019-01-01 12:00:00', '2019-07-01 12:00:00'] as $when) {
    $date    = new DateTime($when, $tz);
    $seconds = $tz->getOffset($date);
    $hours   = $seconds / 3600;
    echo "$when => $seconds seconds (UTC$hours)\n";
}

2019-01-01 12:00:00 => -28800 seconds (UTC-8)
2019-07-01 12:00:00 => -25200 seconds (UTC-7)

Conclusion

timezone_offset_get() (and its object-oriented twin DateTimeZone::getOffset()) gives you a timezone's exact distance from UTC in seconds for a specific moment, with Daylight Saving Time already factored in. Divide by 3600 when you need hours, and remember to pass the date that matters so DST is resolved correctly.

To go further, see date_default_timezone_set() for setting the script's default timezone, timezone_name_get() to read a timezone's name, and the full list of PHP timezones.

Practice