human_time_diff()

💡 云策文档标注

概述

human_time_diff() 是 WordPress 核心函数，用于计算两个 Unix 时间戳之间的差异，并以人类可读的格式（如“1 小时”、“5 分钟”）返回字符串。它支持可选的第二个参数，默认使用当前时间。

关键要点

函数返回两个时间戳之间的差异，格式化为易于理解的字符串。
参数 $from 是必需的起始时间戳，$to 是可选的结束时间戳，默认为 time()。
支持通过 apply_filters('human_time_diff', ...) 钩子过滤输出。
在 WordPress 5.3.0 版本中增加了对秒级差异的支持。
常用于显示文章、评论或修改时间的相对时间信息。

代码示例

// 基本用法：计算从指定时间到当前时间的差异
echo human_time_diff( get_the_time('U') ) . ' ago';

// 国际化和更安全的用法示例
printf( 
    esc_html__( '%s ago', 'textdomain' ), 
    human_time_diff( get_the_modified_time('U'), strtotime( wp_date('Y-m-d H:i:s') ) ) 
);

注意事项

确保传入的时间戳是 Unix 格式，否则可能导致错误结果。
使用国际化函数（如 esc_html__ 或 _x）包装输出，以支持多语言站点。
注意函数内部使用 MINUTE_IN_SECONDS、HOUR_IN_SECONDS 等常量进行时间单位转换。

📄 原文内容

Determines the difference between two timestamps.

Description

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

Parameters

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

Return

string Human-readable time difference.

Source

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 );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘human_time_diff’, string $since, int $diff, int $from, int $to ): Filters the human-readable difference between two timestamps.

Uses	Description
_n()`wp-includes/l10n.php`	Translates and retrieves the singular or plural form based on the supplied number.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Used by	Description
WP_REST_Block_Directory_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php`	Parse block metadata for a block, and prepare it for an API response.
wp_get_auto_update_message()`wp-admin/includes/update.php`	Determines the appropriate auto-update message to be displayed.
WP_Recovery_Mode_Email_Service::maybe_send_recovery_mode_email()`wp-includes/class-wp-recovery-mode-email-service.php`	Sends the recovery mode email if the rate limit has not been sent.
WP_Recovery_Mode_Email_Service::send_recovery_mode_email()`wp-includes/class-wp-recovery-mode-email-service.php`	Sends the Recovery Mode email to the site admin email address.
WP_Privacy_Requests_Table::get_timestamp_as_date()`wp-admin/includes/class-wp-privacy-requests-table.php`	Converts a timestamp for display.
WP_Media_List_Table::column_date()`wp-admin/includes/class-wp-media-list-table.php`	Handles the date column output.
install_plugin_information()`wp-admin/includes/plugin-install.php`	Displays plugin information in dialog box form.
WP_Plugin_Install_List_Table::display_rows()`wp-admin/includes/class-wp-plugin-install-list-table.php`	Generates the list table rows.
wp_prepare_revisions_for_js()`wp-admin/includes/revision.php`	Prepare revisions for JavaScript.
wp_post_revision_title_expanded()`wp-includes/post-template.php`	Retrieves formatted date timestamp of a revision (linked to that revisions’s page).

Show 5 more Show less

Changelog

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

User Contributed Notes

Skip to note 6 content

kommasri

9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Get posted and last modified time
```
";
  if ($lastmodified > $posted) {
	  echo "Edited " . human_time_diff($lastmodified,current_time('U')) . " ago";   
  } 
?>
```
Log in to add feedback
Skip to note 7 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
To print an entry’s time (“2 days ago”):
Log in to add feedback
Skip to note 8 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Internationalized version:
```
printf( _x( '%1$s ago', '%2$s = human-readable time difference', 'wpdocs_textdomain' ),
	human_time_diff( get_the_time( 'U' ),
	current_time( 'timestamp' )
);
```
Log in to add feedback

Skip to note 9 content

nasimnet

6 years ago

/* don’t retrieve time as WP timestamp */
printf(
    /* translators: time */
    esc_html__( '%s ago', 'textdomain' ),
    human_time_diff( get_the_modified_time( 'U' ), strtotime( wp_date( 'Y-m-d H:i:s' ) ) )
);

Skip to note 10 content

Codex

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
For comments:
```
printf( _x( '%1$s ago', '%2$s = human-readable time difference', 'wpdocs_textdomain' ),
	human_time_diff( get_comment_time( 'U' ),
	current_time( 'timestamp' )
);
```
Log in to add feedback

云策 WordPress 开发者社区

函数文档