date_timestamp_get()

Introduction

Date and time functions are a crucial part of programming languages. In PHP, developers often need to retrieve the current date and time or perform operations on dates and times. The date_timestamp_get() function is one such function that is used to extract the Unix timestamp from a DateTime object. In this article, we will explore the date_timestamp_get() function in detail and understand how it works.

Understanding date_timestamp_get()

The date_timestamp_get() function is a built-in PHP function that extracts the Unix timestamp from a DateTime object. A Unix timestamp is a single number representing a moment in time: the count of seconds elapsed since January 1, 1970, 00:00:00 UTC (the "Unix epoch").

A timestamp is always a UTC-based number. The input DateTime object's timezone is used to calculate the value, but the timestamp itself stores no timezone — two DateTime objects describing the same instant in different timezones return the identical timestamp.

Syntax

date_timestamp_get(DateTimeInterface $object): int

• $object — a DateTime or DateTimeImmutable instance (anything implementing DateTimeInterface). Passing null or a non-object triggers a TypeError in PHP 8+.
• Return value — an int, the Unix timestamp in seconds. (Sub-second microseconds are dropped; use $date->format('U.u') if you need them.)

The DateTime object can be created with the date_create() function or the DateTime class constructor. date_timestamp_get($date) is the procedural alias of the method call $date->getTimestamp().

Basic example

We create a DateTime object from a date string, pass it to date_timestamp_get(), and print the returned Unix timestamp. For modern, object-oriented code the equivalent (and usually preferred) form is $date->getTimestamp().

Timezone affects the result

Because a timestamp is an absolute UTC instant, the same wall-clock string produces a different timestamp depending on the object's timezone:

<?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)

10:30 in Tokyo happens 9 hours before 10:30 in UTC, so its timestamp is 32400 seconds smaller. See date_default_timezone_set() for controlling the default timezone.

Using the timestamp in calculations

The real value of a timestamp is arithmetic — once a date is a plain integer you can subtract, compare, and convert it freely:

<?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

To turn a timestamp back into a formatted string, pass it to date(), or build a new object with setTimestamp(). For richer date-to-date differences (years, months, days), prefer date_diff().

Common use cases and gotchas

• Storing dates in a database as an integer keeps sorting and range queries fast and timezone-agnostic.
• Comparing two moments is a simple integer comparison once both are timestamps.
• Gotcha — float vs int: the return type is int. If you need microsecond precision (set via the constructor or date_create() with a fractional second), getTimestamp() truncates it; use format('U.u') instead.
• Gotcha — pre-1970 dates produce negative timestamps, which is valid but surprises code that assumes a positive number.
• Reverse operation: to set an object's time from a timestamp, use date_timestamp_set().

Conclusion

date_timestamp_get() gives PHP developers a simple, accurate way to reduce a DateTime object to a single UTC Unix timestamp — ideal for storage, comparison, and arithmetic. For everyday object-oriented code, reach for $date->getTimestamp(); the two are interchangeable.

Practice