PHP DateTimeZone

La clase DateTimeZone se encarga de representar una zona horaria (timezone).

A continuación podemos ver la descripción de la clase, la cual muestra sus constantes como también sus métodos.

 class DateTimeZone {
/* Constants */
const int AFRICA = 1;
const int AMERICA = 2;
const int ANTARCTICA = 4;
const int ARCTIC = 8;
const int ASIA = 16;
const int ATLANTIC = 32;
const int AUSTRALIA = 64;
const int EUROPE = 128;
const int INDIAN = 256;
const int PACIFIC = 512;
const int UTC = 1024;
const int ALL = 2047;
const int ALL_WITH_BC = 4095;
const int PER_COUNTRY = 4096;
/* Methods */
public __construct(string $timezone)
public getLocation(): array|false
public getName(): string
public getOffset(DateTimeInterface $datetime): int
public getTransitions(int $timestampBegin = PHP_INT_MIN, int $timestampEnd = PHP_INT_MAX): array|false
public static listAbbreviations(): array
public static listIdentifiers(int $timezoneGroup = DateTimeZone::ALL, ?string $countryCode = null): array
}

Constantes

Hagamos un pequeño ejemplo con una constante:

<?php
$zone = DateTimeZone::AFRICA;
echo $zone;

OK, pero esto no parece demasiado útil, ¿en qué usamos las constantes?

Hagamos un segundo ejemplo, esta vez creando un nuevo DateTimeZone.

<?php
$d = new DateTimeZone("Africa/Abidjan");
$thelist=$d->listIdentifiers(DateTimeZone::AFRICA);
echo var_dump($thelist);

array(52) {
  [0]=>
  string(14) "Africa/Abidjan"
  [1]=>
  string(12) "Africa/Accra"
  [2]=>
  string(18) "Africa/Addis_Ababa"
  [3]=>
  string(14) "Africa/Algiers"
  [4]=>
  string(13) "Africa/Asmara"
  [5]=>
  string(13) "Africa/Bamako"
  [6]=>
  string(13) "Africa/Bangui"
  [7]=>
  string(13) "Africa/Banjul"
  [8]=>
  string(13) "Africa/Bissau"
  [9]=>
  string(15) "Africa/Blantyre"
  [10]=>
  string(18) "Africa/Brazzaville"
  [11]=>
  string(16) "Africa/Bujumbura"
  [12]=>
  string(12) "Africa/Cairo"
  [13]=>
  string(17) "Africa/Casablanca"
  [14]=>
  string(12) "Africa/Ceuta"
  [15]=>
  string(14) "Africa/Conakry"
  [16]=>
  string(12) "Africa/Dakar"
  [17]=>
  string(20) "Africa/Dar_es_Salaam"
  [18]=>
  string(15) "Africa/Djibouti"
  [19]=>
  string(13) "Africa/Douala"
  [20]=>
  string(15) "Africa/El_Aaiun"
  [21]=>
  string(15) "Africa/Freetown"
  [22]=>
  string(15) "Africa/Gaborone"
  [23]=>
  string(13) "Africa/Harare"
  [24]=>
  string(19) "Africa/Johannesburg"
  [25]=>
  string(11) "Africa/Juba"
  [26]=>
  string(14) "Africa/Kampala"
  [27]=>
  string(15) "Africa/Khartoum"
  [28]=>
  string(13) "Africa/Kigali"
  [29]=>
  string(15) "Africa/Kinshasa"
  [30]=>
  string(12) "Africa/Lagos"
  [31]=>
  string(17) "Africa/Libreville"
  [32]=>
  string(11) "Africa/Lome"
  [33]=>
  string(13) "Africa/Luanda"
  [34]=>
  string(17) "Africa/Lubumbashi"
  [35]=>
  string(13) "Africa/Lusaka"
  [36]=>
  string(13) "Africa/Malabo"
  [37]=>
  string(13) "Africa/Maputo"
  [38]=>
  string(13) "Africa/Maseru"
  [39]=>
  string(14) "Africa/Mbabane"
  [40]=>
  string(16) "Africa/Mogadishu"
  [41]=>
  string(15) "Africa/Monrovia"
  [42]=>
  string(14) "Africa/Nairobi"
  [43]=>
  string(15) "Africa/Ndjamena"
  [44]=>
  string(13) "Africa/Niamey"
  [45]=>
  string(17) "Africa/Nouakchott"
  [46]=>
  string(18) "Africa/Ouagadougou"
  [47]=>
  string(17) "Africa/Porto-Novo"
  [48]=>
  string(15) "Africa/Sao_Tome"
  [49]=>
  string(14) "Africa/Tripoli"
  [50]=>
  string(12) "Africa/Tunis"
  [51]=>
  string(15) "Africa/Windhoek"
}

Lista de Constantes

• DateTimeZone::AFRICA
  • Africa time zones.
• DateTimeZone::AMERICA
  • America time zones.
• DateTimeZone::ANTARCTICA
  • Antarctica time zones.
• DateTimeZone::ARCTIC
  • Arctic time zones.
• DateTimeZone::ASIA
  • Asia time zones.
• DateTimeZone::ATLANTIC
  • Atlantic time zones.
• DateTimeZone::AUSTRALIA
  • Australia time zones.
• DateTimeZone::EUROPE
  • Europe time zones.
• DateTimeZone::INDIAN
  • Indian time zones.
• DateTimeZone::PACIFIC
  • Pacific time zones.
• DateTimeZone::UTC
  • UTC time zones.
• DateTimeZone::ALL
  • All time zones.
• DateTimeZone::ALL_WITH_BC
  • All time zones including backwards compatible.
• DateTimeZone::PER_COUNTRY
  • Time zones per country.

Creo que es suficiente para las constantes, veamos ahora los métodos.

Métodos

En esta sección veremos los diferentes métodos que posee DateTimeZone

__construct

El método constructor posee un argumento, el cual es obligatorio, este crea un nuevo objeto DateTimeZone, $timezone debe ser un string, el cual puede ser de los siguientes valores: nombre de zona horaria(timezone name), un valor offset por ejemplo "+0200", "-0100" u otos y por último, abreviaciones de zona horaria Ejemplo "BST", "CEST", etc.

public DateTimeZone::__construct(string $timezone)

No daje ejemplos, ya que di ejemplos antes en constantes.

getLocation()

Retorna información para una zona horaria (timezone)

public DateTimeZone::getLocation(): array

$obj->getLocation()

Retorna un array con la información o false en caso de fallo.

<?php
$tz = new DateTimeZone("America/Costa_Rica");
print_r($tz->getLocation());
?>

Array
(
    [country_code] => CR
    [latitude] => 9.93333
    [longitude] => -84.08334
    [comments] => 
)

Este método puede que no le parezca útil, pero saber el código del país es realmente útil

getName

Devuelve el nombre de la zona horaria como un string

public DateTimeZone::getName(): string

$obj->getName()

<?php
$tz = new DateTimeZone("America/Costa_Rica");
print_r($tz->getName());
?>

America/Costa_Rica

getOffset

Devuelve el índice de la zona horaria (timestamp) de GMT, siendo GMT (Greenwich Mean Time) en otras palabras es el índice con respecto a GMT.

public DateTimeZone::getOffset(DateTime $datetime): int

$obj->getOffset($datetime)

En la página de PHP hay un ejemplo sobre esto, he cambiado un poco el ejemplo, para utilizar a Uruguay y España como países de referencia. España posee 2 horas mas que GMT y por su parte Uruguay posee 3 horas menos en el momento de escribir este post.

<?php

$dateTimeZoneMontevideo = new DateTimeZone("America/Montevideo");
$dateTimeZoneMadrid = new DateTimeZone("Europe/Madrid");

$dateTimeMontevideo = new DateTime("now", $dateTimeZoneMontevideo);
$dateTimeMadrid = new DateTime("now", $dateTimeZoneMadrid);

$timeOffset = $dateTimeZoneMadrid->getOffset($dateTimeMontevideo);
$timeOffset2= $dateTimeZoneMontevideo->getOffset($dateTimeMadrid);


var_dump($timeOffset);
var_dump($timeOffset2);

int(7200)
int(-10800)

Podemos darnos cuenta de que este entero son las horas de España y Uruguay escritas en segundos, ya que 7200 ÷ 60 ÷ 60 = 2 y -10800 ÷ 60 ÷ 60 = -3

getTransitions

Este método devuelve las transiciones de la timezone o zona horaria. Tenga en cuenta que muchos paises tiene varias zonas horarias debido al ahorro energético. Por ejemplo, Uruguay tiene 3 horas menos que el GMT, pero en verano este horario cambia.

public DateTimeZone::getTransitions(int $timestampBegin = PHP_INT_MIN, int $timestampEnd = PHP_INT_MAX): array|false

$obj->getTransitions($timestampBegin,$timestampEnd)

En la descripción del método podemos ver que tenemos un timestamp de inicio y un timestamp de fin. Con ellos definimos el periodo en el cual queremos obtener las transiciones.

<?php
$zona_horaria = new DateTimeZone("America/Montevideo");
$transiciones = $zona_horaria->getTransitions(631152000,PHP_INT_MAX);//631152000 se refiere al año 1990
print_r(array_slice($transiciones, 0, 3));
?>

Estos serian las 3 primeras transiciones desde 1990.

DateTimeZone::listAbbreviations

Devuelve un array asociativo conteniendo el DST, offset y e el nombre de la zona horaria.

public static DateTimeZone::listAbbreviations(): array

DateTimeZone::listAbbreviations()

Veamos un ejemplo.

<?php
$timezone_abbreviations = DateTimeZone::listAbbreviations();
print_r($timezone_abbreviations["acst"]);
?>

En este ejemplo se obtendrán todas las abreviaciones acst(Australian Central Standard Time).

DateTimeZone::listIdentifiers

Devuelve un array indexado numéricamente que contiene todos los identificadores de zonas horarias(timezones) definidos

public static DateTimeZone::listIdentifiers(int $timezoneGroup = DateTimeZone::ALL, ?string $countryCode = null)

DateTimeZone::listIdentifiers($timezoneGroup,$countryCode)

Ya hemos hecho un ejemplo de listidentifiers antes en constantes, pero cometí un error que no debes realizar y es que llame el método con -> en vez de :: aunque de todos modos funciono esto no siempre funciona.

Veamos un ejemplo sencillo con los identificadores de Australia.

<?php
$timezone_identifiers = DateTimeZone::listIdentifiers(DateTimeZone::AUSTRALIA);
var_dump($timezone_identifiers)
?>

array(11) {
  [0]=>
  string(18) "Australia/Adelaide"
  [1]=>
  string(18) "Australia/Brisbane"
  [2]=>
  string(21) "Australia/Broken_Hill"
  [3]=>
  string(16) "Australia/Darwin"
  [4]=>
  string(15) "Australia/Eucla"
  [5]=>
  string(16) "Australia/Hobart"
  [6]=>
  string(18) "Australia/Lindeman"
  [7]=>
  string(19) "Australia/Lord_Howe"
  [8]=>
  string(19) "Australia/Melbourne"
  [9]=>
  string(15) "Australia/Perth"
  [10]=>
  string(16) "Australia/Sydney"
}