{datediff:start_timestamp:end_timestamp:format}

Description

Returns the difference between two dates given as Unix timestamps. By default it reports whole completed years, which makes it handy for ages. The end date defaults to the current time, so a single timestamp gives the years elapsed since then. The third parameter is a PHP date_diff format string. Common codes: %y whole years, %m remaining months (0 to 11), %d remaining days, %a total days across the whole span, %h %i %s remaining hours/minutes/seconds, %R a sign that is + or -, %r a sign that is - or empty, and %% a literal percent. Upper-case codes (%Y %M %D %H %I %S) are the zero-padded forms of their lower-case counterparts. Each part is one slice of the decomposed interval, so %m never exceeds 11; use %a when you want the total number of days. The order of the two timestamps does not change the magnitude; only %R or %r reveals which date came first.

Parameters

start_timestamp required

Unix timestamp of the start date. A non-numeric value counts as 0, which is 1970-01-01.

end_timestamp optional default current time (now)

Unix timestamp of the end date. Leave it out to use the current time, which makes the result count up to now.

format optional default %y

PHP date_diff format string. %y years, %m months, %d days, %a total days, %h %i %s remaining hours/minutes/seconds, %R or %r the sign, %% a literal percent. Upper-case codes are zero-padded.

Examples

test{datediff:946684800:1704067200}

Expected24

Actual24

With no format the result is the number of whole completed years between the two timestamps. Here 946684800 is 2000-01-01 and 1704067200 is 2024-01-01 (both UTC), so the answer is 24.

test{datediff:946684800:1704067200:%a}

Expected8766

Actual8766

The format string %a gives the total number of days across the whole span, not just the day part. 24 years including 6 leap days is 8766 days.

test{datediff:946684800:1704067200:%R%a}

Expected+8766

Actual+8766

%R prints the sign of the difference (+ or -) and %a the total days. When the end date is later than the start the sign is +.

test{datediff:1704067200:1710028800:%y years %m months %d days}

Expected0 years 2 months 9 days

Actual0 years 2 months 9 days

Each interval part counts only what is left after the larger parts. From 2024-01-01 (1704067200) to 2024-03-10 (1710028800) is 0 years, 2 months and 9 days. %m stays in the 0 to 11 range.

test{datediff:1704067200:946684800:%R%a}

Expected-8766

Actual-8766

The size of the difference does not depend on the order of the timestamps, but %R reveals direction. Here the start is later than the end, so the sign is minus.

virtual{datediff:946684800}

Expected(years elapsed since 2000-01-01, e.g. 26 in 2026)

Actual26

With a single timestamp the end date defaults to the current time, so the result counts up to today. This is the typical age calculation. The output changes every year, so it is shown as illustrative rather than a fixed test.

← All expressions