timezone_name_get()

Purpose

timezone_name_get() is the procedural form of DateTimeZone::getName(). You give it a DateTimeZone object and it returns that zone's name as a string. The manual lists it as an alias, so the two forms do the same job. Which one you use is a matter of style. Code that already uses procedural date functions such as timezone_open() tends to read more consistently with timezone_name_get(). Object-oriented code usually calls $tz->getName().

Typical uses are logging which zone a value was created with, building a dropdown value from a zone object, and storing the zone next to a timestamp so it can be rebuilt later.

Signature

Parameters and defaults

• $object: a DateTimeZone instance. It is required and has no default. You can get one from new DateTimeZone(), from timezone_open(), or from getTimezone() on a DateTime or DateTimeImmutable.

Return value and failure cases

The function returns a string. What the string looks like depends on how the zone was created:

• For an identifier zone such as Europe/Paris or UTC, you get that identifier.
• For a fixed-offset zone such as +05:30, you get the offset text.

The function does not return false for ordinary use. The one failure case is passing something that is not a DateTimeZone. In PHP 8 that throws a TypeError, for example when you pass the string 'UTC' instead of an object. A string is not converted to a zone automatically. Creating a zone from an invalid name fails earlier, when the DateTimeZone constructor runs, not inside timezone_name_get().

Example 1: names from different kinds of zones

This builds three zones and maps the function over them. The identifier zones keep their identifiers, and the offset zone keeps its offset text.

<?php
$zones = [new DateTimeZone('Europe/Paris'), new DateTimeZone('UTC'), new DateTimeZone('+05:30')];
echo json_encode(array_map('timezone_name_get', $zones), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

["Europe/Paris","UTC","+05:30"]

Example 2: reading the zone from a date object

A date object remembers the zone it was created with. getTimezone() returns a DateTimeZone, which you can pass straight to the function. The example also confirms that the procedural call and the method return the same string.

<?php
date_default_timezone_set('UTC');
$date = new DateTimeImmutable('2024-07-01 12:00:00', new DateTimeZone('America/New_York'));
$tz = $date->getTimezone();
echo json_encode([
    'procedural' => timezone_name_get($tz),
    'method' => $tz->getName(),
    'same' => timezone_name_get($tz) === $tz->getName(),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"procedural":"America/New_York","method":"America/New_York","same":true}

Example 3: passing the wrong type

The parameter must be an object. A plain string is rejected with a TypeError, which you can catch if you accept untrusted input.

<?php
try {
    echo timezone_name_get('UTC');
} catch (TypeError $e) {
    echo get_class($e), "\n";
}

TypeError

Edge cases

• The name is not an offset for a point in time. For an identifier zone such as America/New_York, the name stays the same all year even though the UTC offset changes with daylight saving time. To see the offset at a specific moment, use getOffset() with a date object.
• Offset zones return offset text. A zone created from +05:30 has no region name, so there is no city identifier to retrieve from it.
• The default zone is not involved. The function reports the zone stored in the object you pass. It does not look at the value set by date_default_timezone_set(). To read the default zone name, use date_default_timezone_get().
• It is a copy of information, not a handle. The returned string is a plain value. Changing it has no effect on the zone object.

Common mistakes

1. Passing a string instead of an object. timezone_name_get('Europe/Paris') throws a TypeError. Create the zone first with new DateTimeZone('Europe/Paris') or timezone_open().
2. Passing a date object instead of its zone. A DateTime is not a DateTimeZone. Call getTimezone() on it first.
3. Expecting an abbreviation or offset for identifier zones. The result for Europe/Paris is not CET or +01:00. Use format('T') or format('P') on a date object for those.
4. Assuming the alias behaves differently. There is no behavioral difference to plan around. If you switch between the function and the method, the result is the same.
5. Validating user input too late. Wrap the DateTimeZone constructor in try/catch, because an unknown name fails there. Only after that can you safely pass the object on.

Related functions

• DateTimeZone::getName(): the method this function aliases.
• timezone_open(): procedural way to create a DateTimeZone.
• date_default_timezone_get(): returns the default zone name used by date functions.
• date_timezone_get(): returns the zone of a date object.
• timezone_offset_get(): returns the offset in seconds for a given date.
• timezone_identifiers_list(): lists the available zone identifiers.

Recap

timezone_name_get() takes a DateTimeZone and returns its name as a string. It is an alias of DateTimeZone::getName(). Identifier zones return their identifier and offset zones return their offset text. A non-object argument throws a TypeError, and the name alone tells you nothing about the offset at a given moment.