date_timestamp_get()

Purpose

date_timestamp_get() reads a date-time object and returns its Unix timestamp: the number of whole seconds between the Unix epoch (1970-01-01 00:00:00 UTC) and the moment the object represents. It is the procedural alias of DateTime::getTimestamp(). The two forms do the same job, so choose whichever matches the style of the surrounding code. If you already work with objects, $date->getTimestamp() is usually the more natural call.

A timestamp is useful when you need to compare instants, store a compact value, calculate a difference in seconds, or pass a moment to an API that expects an integer.

Signature

Parameters and defaults

$object is the only parameter and it has no default. It must be an object that implements DateTimeInterface. In practice that means a DateTime or a DateTimeImmutable, including values created by date_create(), date_create_immutable() or the createFromFormat() family.

The function never changes the object. It only reads the stored instant.

Return value and failure cases

The function returns an int. The value is negative for moments before the epoch and 0 for the epoch itself. Fractional seconds are not part of the result, because the timestamp is an integer count of whole seconds.

The time zone attached to the object does not change the number. A timestamp identifies one instant, and the zone only decides how that instant is written as a wall-clock time.

If you pass something that is not a DateTimeInterface, such as a string, an integer or false, PHP throws a TypeError. This matters when you pass the result of date_create() straight in: that function returns false for input it cannot parse, and false is not an acceptable argument.

Example 1: Timestamp for a fixed UTC date

This creates a date with an explicit UTC zone and reads its timestamp.

<?php
date_default_timezone_set('UTC');
$date = date_create('2024-01-15 12:00:00', new DateTimeZone('UTC'));
echo date_timestamp_get($date) . "\n";

1705320000

Example 2: Same instant, different zones

Noon in UTC and 07:00 in New York on this winter date are the same instant, so they give the same timestamp. The example also shows that an immutable object is accepted.

<?php
date_default_timezone_set('UTC');
$utc = date_create('2024-01-15 12:00:00', new DateTimeZone('UTC'));
$ny = date_create_immutable('2024-01-15 07:00:00', new DateTimeZone('America/New_York'));
$a = date_timestamp_get($utc);
$b = date_timestamp_get($ny);
echo json_encode(['utc' => $a, 'ny' => $b, 'same' => $a === $b]);
echo "\n";

{"utc":1705320000,"ny":1705320000,"same":true}

Example 3: Epoch, negative values and fractions

The epoch gives 0, one second earlier gives -1, and microseconds are dropped from the integer result. The fraction is still stored in the object and can be read with format('u').

<?php
date_default_timezone_set('UTC');
$zone = new DateTimeZone('UTC');
$epoch = date_create('1970-01-01 00:00:00', $zone);
$before = date_create('1969-12-31 23:59:59', $zone);
$fraction = DateTime::createFromFormat('Y-m-d H:i:s.u', '2024-01-15 12:00:00.987654', $zone);
echo json_encode([
    'epoch' => date_timestamp_get($epoch),
    'before' => date_timestamp_get($before),
    'fraction' => date_timestamp_get($fraction),
    'micro' => $fraction->format('u'),
]);
echo "\n";

{"epoch":0,"before":-1,"fraction":1705320000,"micro":"987654"}

Edge cases

• Dates before 1970 produce negative integers. This is valid and not an error.
• Fractional seconds are not rounded. The microsecond part is not included in the returned integer.
• Time zone offsets are already accounted for when the object is created. The timestamp is not shifted again when you read it.
• Daylight saving transitions can make a local time ambiguous or nonexistent. The timestamp reflects whatever instant PHP resolved when it built the object, so compare the result against what you expect for those hours.
• Immutable and mutable objects behave the same way here. Because the function only reads, it does not matter which class you use.

Common mistakes

1. Passing the result of a failed date_create(). The function returns false for unparseable input, and date_timestamp_get(false) throws a TypeError. Check the result before using it.
2. Passing a string. The function wants an object, not '2024-01-15'. If you have a string and want a timestamp, create an object first or use strtotime() where its behavior suits you.
3. Expecting a timestamp to include the zone. Two objects in different zones can share one timestamp. If you need the zone later, store it separately.
4. Treating the integer as milliseconds. The value counts seconds. JavaScript-style millisecond values are 1000 times larger.
5. Relying on the default time zone. Inputs without an explicit zone use the current default zone, so the same text can mean different instants on different configurations. Set a zone explicitly for reproducible results.

Related functions

• DateTime::getTimestamp(): the method form that this function aliases.
• date_timestamp_set(): sets an object's moment from a timestamp.
• date_create() and date_create_immutable(): build objects from text.
• date_format(): writes the same instant as formatted text.
• strtotime(): parses a string directly into a timestamp.

Recap

date_timestamp_get() takes a DateTimeInterface object and returns its Unix timestamp as an integer count of whole seconds. It is the alias of DateTime::getTimestamp(). The result is independent of the object's time zone, may be negative, and ignores microseconds. Always make sure the argument is a real date object, not false or a string.