Guide · 6 min read
How Unix timestamps work
A Unix timestamp is a single number: how many seconds have elapsed since midnight UTC on 1 January 1970. Storing time as one integer removes ambiguity about format and time zone, which is exactly why databases, log files and APIs use it so heavily.
Seconds or milliseconds?
Unix tooling, PHP and most databases use seconds. JavaScript's Date.now() and many JSON APIs use milliseconds. A ten-digit number is almost certainly seconds; a thirteen-digit number is almost certainly milliseconds. Mixing the two produces dates in 1970 or in the year 54,000 — both are instantly recognisable symptoms.
Timestamps have no time zone
The number itself is always UTC. A time zone only enters the picture when you format the timestamp for a person. That is the correct place for it: store the instant, present it in the reader's local zone.
This also means a timestamp cannot tell you what the local wall-clock time was where an event happened. If that matters — for a booking or a calendar entry — store the intended zone alongside the instant.
Leap seconds and the smooth clock
Unix time deliberately pretends every day has exactly 86,400 seconds. Real leap seconds are absorbed rather than represented, which keeps arithmetic simple at the cost of being a fraction of a second away from astronomical time. For application work this is never a problem.
The year 2038 problem
A signed 32-bit integer overflows on 19 January 2038. Modern systems store timestamps in 64-bit integers and are unaffected, but older embedded devices, file formats and some database columns still use 32 bits. If you are choosing a column type today, choose a 64-bit one.
Working with durations
Because timestamps are plain integers, a duration is just a subtraction. Divide by 60 for minutes, 3,600 for hours and 86,400 for days. Months and years cannot be handled this way — they vary in length, so use a calendar-aware calculation instead.