date_timestamp_get()

Introducción

Las funciones de fecha y hora son una parte fundamental de los lenguajes de programación. En PHP, los desarrolladores frecuentemente necesitan obtener la fecha y hora actuales o realizar operaciones sobre fechas y horas. La función date_timestamp_get() es una de esas funciones, y se utiliza para extraer el timestamp Unix de un objeto DateTime. En este artículo exploraremos la función date_timestamp_get() en detalle y comprenderemos cómo funciona.

Entendiendo date_timestamp_get()

La función date_timestamp_get() es una función integrada de PHP que extrae el timestamp Unix de un objeto DateTime. Un timestamp Unix es un número único que representa un instante en el tiempo: la cantidad de segundos transcurridos desde el 1 de enero de 1970, 00:00:00 UTC (la "época Unix").

Un timestamp siempre es un número basado en UTC. La zona horaria del objeto DateTime de entrada se usa para calcular el valor, pero el timestamp en sí no almacena ninguna zona horaria — dos objetos DateTime que describen el mismo instante en distintas zonas horarias devuelven el mismo timestamp.

Sintaxis

date_timestamp_get(DateTimeInterface $object): int

• $object — una instancia de DateTime o DateTimeImmutable (cualquier cosa que implemente DateTimeInterface). Pasar null o un no-objeto provoca un TypeError en PHP 8+.
• Valor de retorno — un int, el timestamp Unix en segundos. (Los microsegundos de sub-segundo se descartan; usa $date->format('U.u') si los necesitas.)

El objeto DateTime se puede crear con la función date_create() o con el constructor de la clase DateTime. date_timestamp_get($date) es el alias procedimental de la llamada al método $date->getTimestamp().

Ejemplo básico

Creamos un objeto DateTime a partir de una cadena de fecha, lo pasamos a date_timestamp_get() e imprimimos el timestamp Unix devuelto. Para código moderno orientado a objetos, la forma equivalente (y generalmente preferida) es $date->getTimestamp().

La zona horaria afecta el resultado

Dado que un timestamp es un instante UTC absoluto, la misma cadena de hora produce un timestamp diferente dependiendo de la zona horaria del objeto:

<?php
$utc = new DateTime('2023-03-03 10:30:00', new DateTimeZone('UTC'));
$tokyo = new DateTime('2023-03-03 10:30:00', new DateTimeZone('Asia/Tokyo'));

echo date_timestamp_get($utc);   // 1677839400
echo "\n";
echo date_timestamp_get($tokyo); // 1677807000 (32400s = 9h earlier in UTC)

Las 10:30 en Tokio ocurren 9 horas antes que las 10:30 en UTC, por lo que su timestamp es 32400 segundos menor. Consulta date_default_timezone_set() para controlar la zona horaria predeterminada.

Uso del timestamp en cálculos

El valor real de un timestamp está en la aritmética — una vez que una fecha es un entero simple, puedes restar, comparar y convertirlo libremente:

<?php
$start = date_timestamp_get(date_create('2023-03-03 10:30:00'));
$end   = date_timestamp_get(date_create('2023-03-03 12:00:00'));

$diffSeconds = $end - $start;
echo $diffSeconds / 60 . " minutes elapsed"; // 90 minutes elapsed

Para convertir un timestamp de vuelta a una cadena formateada, pásalo a date(), o construye un nuevo objeto con setTimestamp(). Para diferencias de fecha más ricas (años, meses, días), prefiere date_diff().

Casos de uso comunes y advertencias

• Almacenar fechas en una base de datos como entero mantiene las consultas de ordenación y rango rápidas e independientes de la zona horaria.
• Comparar dos momentos es una simple comparación de enteros una vez que ambos son timestamps.
• Advertencia — float vs int: el tipo de retorno es int. Si necesitas precisión de microsegundos (establecida mediante el constructor o date_create() con un segundo fraccionario), getTimestamp() lo trunca; usa format('U.u') en su lugar.
• Advertencia — fechas anteriores a 1970 producen timestamps negativos, lo cual es válido pero sorprende al código que asume un número positivo.
• Operación inversa: para establecer el tiempo de un objeto a partir de un timestamp, usa date_timestamp_set().

Conclusión

date_timestamp_get() ofrece a los desarrolladores PHP una forma sencilla y precisa de reducir un objeto DateTime a un único timestamp Unix UTC — ideal para almacenamiento, comparación y aritmética. Para el código orientado a objetos cotidiano, utiliza $date->getTimestamp(); ambos son intercambiables.

Práctica