human_time_diff() │ WP 1.5.0

Determines the difference between two timestamps.

The difference is returned in a human-readable format such as "1 hour", "5 minutes", "2 days".

1 time — 0.00003 sec (very fast) | 50000 times — 0.12 sec (very fast) | PHP 7.4.8, WP 5.6.1

Hooks from the function

human_time_diff

Return

String. Human-readable time difference.

Usage

human_time_diff( $from, $to );

$from(int) (required): Unix timestamp from which the difference begins.
$to(int): Unix timestamp to end the time difference.
Default: becomes time() if not set

Examples

#1 Seconds in human format

Suppose we need to turn (convert) seconds into an understandable format:

echo human_time_diff( 0, 600 );    // 10 min
echo human_time_diff( 0, 6000 );   // 2 hour
echo human_time_diff( 0, 60000 );  // 17 hour
echo human_time_diff( 0, 600000 ); // 7 day

#2 Display the elapsed time since the post was published

It's been a while since the post was published. This example shows how to display the time that has elapsed since the post was published. Usually it is used in the WordPress Loop:

$time_diff = human_time_diff( get_post_time('U'), current_time('timestamp') );
echo "Published $time_diff ago.";
//> Published five years ago.

We specified a second parameter current_time('timestamp') to pass the time tag in the same time zone as get_the_time(). The time zone is specified on the WordPress Settings > General page. All the built-in WordPress functions are oriented to the time zone, including current_time(). Therefore, if you do not specify the second parameter, the default PHP function time() will be used, which will receive the time tag in the standard GMT zone without correction for the time zone specified in the WP settings, and therefore the result will not be correct.

In other words, in human_time_diff() you must specify the time in one time zone.

#3 Time in GMT standard:

$human_time = human_time_diff( get_post_time( 'U', true ) );
echo "Published $human_time ago.";
// Published 2 years ago.

Here get_post_time('U', true ), will display the post field value post_date_gmt, not post_date. And we didn't specify the second parameter because time() gets gmt time by default.

#4 Comment added time in difference format to now

It's been a while since the comment was posted. This example is show difference time from comment was added to now:

$time_diff = human_time_diff( get_comment_time('U'), current_time('timestamp') );
echo "Published $time_diff ago.";

#5 Restrict the function to the next month

By default human_time_diff() will output both months and years. Limit the difference to a month; if the difference is higher, we will output the time in the usual format 5 January 2014:

$time_diff = human_time_diff( get_comment_time('U'), current_time('timestamp') );

if( preg_match('~month|year|month|year|year~iu', $time_diff ) ){
	echo "Published: ". get_the_time();
}
else {
	echo "Published $time_diff ago.";
}

#6 Get posted and last modified time of post

$lastmodified = get_the_modified_time('U');
$posted = get_the_time('U');

echo sprintf( "Posted %s ago", human_time_diff( $posted,current_time( 'U' ) ) );
echo "</br>";

if ( $lastmodified > $posted ) {
	echo sprintf( "Edited %s ago", human_time_diff( $lastmodified, current_time('U') ) );   
}

#7 Localize result

printf( _x( '%s ago', 'human-readable time difference', 'my_textdomain' ),
	human_time_diff( get_the_time( 'U' )
);

Changelog

Since 1.5.0	Introduced.
Since 5.3.0	Added support for showing a difference in seconds.

`human_time_diff() human time diff` code ^{WP 6.7.1}

wp-includes/formatting.php

function human_time_diff( $from, $to = 0 ) {
	if ( empty( $to ) ) {
		$to = time();
	}

	$diff = (int) abs( $to - $from );

	if ( $diff < MINUTE_IN_SECONDS ) {
		$secs = $diff;
		if ( $secs <= 1 ) {
			$secs = 1;
		}
		/* translators: Time difference between two dates, in seconds. %s: Number of seconds. */
		$since = sprintf( _n( '%s second', '%s seconds', $secs ), $secs );
	} elseif ( $diff < HOUR_IN_SECONDS && $diff >= MINUTE_IN_SECONDS ) {
		$mins = round( $diff / MINUTE_IN_SECONDS );
		if ( $mins <= 1 ) {
			$mins = 1;
		}
		/* translators: Time difference between two dates, in minutes. %s: Number of minutes. */
		$since = sprintf( _n( '%s minute', '%s minutes', $mins ), $mins );
	} elseif ( $diff < DAY_IN_SECONDS && $diff >= HOUR_IN_SECONDS ) {
		$hours = round( $diff / HOUR_IN_SECONDS );
		if ( $hours <= 1 ) {
			$hours = 1;
		}
		/* translators: Time difference between two dates, in hours. %s: Number of hours. */
		$since = sprintf( _n( '%s hour', '%s hours', $hours ), $hours );
	} elseif ( $diff < WEEK_IN_SECONDS && $diff >= DAY_IN_SECONDS ) {
		$days = round( $diff / DAY_IN_SECONDS );
		if ( $days <= 1 ) {
			$days = 1;
		}
		/* translators: Time difference between two dates, in days. %s: Number of days. */
		$since = sprintf( _n( '%s day', '%s days', $days ), $days );
	} elseif ( $diff < MONTH_IN_SECONDS && $diff >= WEEK_IN_SECONDS ) {
		$weeks = round( $diff / WEEK_IN_SECONDS );
		if ( $weeks <= 1 ) {
			$weeks = 1;
		}
		/* translators: Time difference between two dates, in weeks. %s: Number of weeks. */
		$since = sprintf( _n( '%s week', '%s weeks', $weeks ), $weeks );
	} elseif ( $diff < YEAR_IN_SECONDS && $diff >= MONTH_IN_SECONDS ) {
		$months = round( $diff / MONTH_IN_SECONDS );
		if ( $months <= 1 ) {
			$months = 1;
		}
		/* translators: Time difference between two dates, in months. %s: Number of months. */
		$since = sprintf( _n( '%s month', '%s months', $months ), $months );
	} elseif ( $diff >= YEAR_IN_SECONDS ) {
		$years = round( $diff / YEAR_IN_SECONDS );
		if ( $years <= 1 ) {
			$years = 1;
		}
		/* translators: Time difference between two dates, in years. %s: Number of years. */
		$since = sprintf( _n( '%s year', '%s years', $years ), $years );
	}

	/**
	 * Filters the human-readable difference between two timestamps.
	 *
	 * @since 4.0.0
	 *
	 * @param string $since The difference in human-readable text.
	 * @param int    $diff  The difference in seconds.
	 * @param int    $from  Unix timestamp from which the difference begins.
	 * @param int    $to    Unix timestamp to end the time difference.
	 */
	return apply_filters( 'human_time_diff', $since, $diff, $from, $to );
}