timezone_name_get()

Introduction

This article covers the timezone_name_get function in PHP. We will explore its syntax, parameters, and return values, along with real-world examples. This function reads the identifier back out of a DateTimeZone object, which is handy when you store a time zone object and later need its name for logging, display, or comparison.

timezone_name_get is the procedural alias of the DateTimeZone::getName method. The two are interchangeable, so use whichever style fits your codebase.

Availability: timezone_name_get is part of PHP's built-in date/time extension. It is always available — no extra extension (such as intl) needs to be installed.

Syntax

The timezone_name_get function takes a single DateTimeZone object and returns the name of the time zone it represents. Here is the signature:

The syntax of PHP timezone_name_get() function

timezone_name_get(DateTimeZone $object): string

Let's break down the parameters:

• $object: This is a DateTimeZone object that represents a time zone.

Parameters

As mentioned above, the timezone_name_get function takes only one parameter: a DateTimeZone object. This object represents a specific time zone, and is created using the DateTimeZone class. Here is an example of creating a DateTimeZone object:

Example of creating DateTimeZone object in PHP

<?php

$timezone = new DateTimeZone('America/New_York');

In this example, we create a DateTimeZone object that represents the Eastern Time Zone in the United States.

Note: In PHP 8+, strict type checking is enforced. Passing an argument that is not a DateTimeZone object will throw a TypeError.

Return Values

The timezone_name_get function returns a string that represents the name of the time zone represented by the DateTimeZone object passed in as a parameter. Here is an example of how it can be used:

Example of using timezone_name_get() function in PHP

In this example, we create a DateTimeZone object representing the Eastern Time Zone, and then pass it into the timezone_name_get function. The function then returns the string "America/New_York", which we output using the echo statement.

The function always echoes back the canonical identifier the object was built with. If you create the object from an offset or abbreviation, the returned name reflects that:

Names for offset and abbreviation based zones

<?php

echo timezone_name_get(new DateTimeZone('+05:00')), PHP_EOL; // Output: +05:00
echo timezone_name_get(new DateTimeZone('GMT')), PHP_EOL;    // Output: GMT
echo timezone_name_get(new DateTimeZone('UTC')), PHP_EOL;    // Output: UTC

For named zones the result is the same string you can pass to functions like date_default_timezone_set, which makes it a safe round-trip identifier.

Real-world Examples

Now that we have covered the basics of the timezone_name_get function, let's explore some real-world examples of how it can be used.

Example 1: Displaying Time Zones in a Dropdown Menu

Suppose we want to create a form that allows users to select their time zone. We can use the DateTimeZone class along with the timezone_name_get function to populate a dropdown menu with all available time zones. Here is an example:

Displaying Time Zones in a Dropdown Menu in PHP

<select name="timezone">
  <?php foreach(DateTimeZone::listIdentifiers() as $timezone): ?>
    <option value="<?php echo $timezone; ?>">
      <?php echo $timezone; ?>
    </option>
  <?php endforeach; ?>
</select>

In this example, we use the listIdentifiers method of the DateTimeZone class to get a list of all available time zones. Since listIdentifiers already returns the canonical time zone names, we can directly use $timezone for both the value and the label, making the code more efficient.

Example 2: Converting a Date to Another Time Zone

Suppose we have a date that is in the Pacific Time Zone, and we want to convert it to the Eastern Time Zone. We can use the DateTime class along with the DateTimeZone and timezone_name_get functions to accomplish this. Here is an example:

Converting a Date to Another Time Zone in PHP

In this example, we create a DateTime object representing a date and time in the Pacific Time Zone, using the America/Los_Angeles time zone identifier. We then create a clone of this object and use the setTimezone method to convert it to the Eastern Time Zone, using the America/New_York time zone identifier. Finally, we output the dates in both time zones using the format method, and verify the active time zone names using timezone_name_get.

Notice the Eastern time reads 12:00:00 against the Pacific 09:00:00 — three hours ahead, exactly as expected.

Object-oriented alternative

Because timezone_name_get is just a wrapper around DateTimeZone::getName, you can call the method directly:

Procedural vs. object-oriented style

<?php

$timezone = new DateTimeZone('Europe/Berlin');

echo timezone_name_get($timezone), PHP_EOL; // Procedural
echo $timezone->getName(), PHP_EOL;          // Object-oriented
// Both output: Europe/Berlin

Both forms return the same string. The object-oriented method chains nicely when you already hold a DateTimeZone instance.

Related functions

• timezone_open — create a DateTimeZone object whose name you can later read.
• date_timezone_get — get the DateTimeZone attached to a DateTime object.
• timezone_offset_get — get a zone's offset (in seconds) from UTC for a given moment.
• timezone_identifiers_list — list every valid time zone identifier.

For a broader overview, see the PHP Timezones chapter.

Conclusion

This article has covered the timezone_name_get function in PHP, including its syntax, parameters, return values, and practical use cases. It returns the canonical identifier stored in a DateTimeZone object, is available without any extra extension, and mirrors the DateTimeZone::getName method. We hope these insights help you handle time zone conversions more reliably in your projects.

Practice