社交動態、評論列表、通知中心常需將時間戳轉為人類易讀的相對時間(如「3分鐘前」、「昨天 14:30」)。本文提供一個健壯、可擴充的 formatFriendlyTime() 函式,處理跨年、閏年、時區等細節。
| 時間差 | 顯示格式 |
|---|---|
| < 60 秒 | 剛剛 / N 秒前 |
| < 60 分鐘 | N 分鐘前 |
| < 24 小時且同一天 | N 小時前 |
| 昨天 | 昨天 HH:MM |
| 前天 | 前天 HH:MM |
| 同一年內 > 3 天 | MM-DD HH:MM |
| 跨年或 > 1 年 | YYYY-MM-DD HH:MM |
<?php
/**
* 友好時間格式化
* @param int|string|DateTime $time 目標時間(時間戳、日期字串或 DateTime 物件)
* @param DateTimeZone|string|null $tz 目標時區,預設系統預設時區
* @return string
*/
function formatFriendlyTime($time, $tz = null): string
{
// 統一轉為 DateTimeImmutable(UTC 存儲最佳)
if ($time instanceof DateTimeInterface) {
$dt = DateTimeImmutable::createFromInterface($time);
} elseif (is_numeric($time)) {
$dt = (new DateTimeImmutable('@' . $time))->setTimezone(new DateTimeZone('UTC'));
} else {
$dt = new DateTimeImmutable($time, new DateTimeZone('UTC'));
}
if ($tz) {
$dt = $dt->setTimezone($tz instanceof DateTimeZone ? $tz : new DateTimeZone($tz));
}
$now = new DateTimeImmutable('now', $dt->getTimezone());
$diff = $now->getTimestamp() - $dt->getTimestamp(); // 秒差
// 未來時間保護
if ($diff < 0) return $dt->format('Y-m-d H:i');
// 同一天判斷(以當地日期為準)
$sameDay = $dt->format('Y-m-d') === $now->format('Y-m-d');
if ($sameDay) {
if ($diff < 60) return $diff . ' 秒前';
if ($diff < 3600) return floor($diff / 60) . ' 分鐘前';
if ($diff < 86400) return floor($diff / 3600) . ' 小時前';
}
$yesterday = (clone $now)->modify('-1 day')->format('Y-m-d');
$beforeYesterday = (clone $now)->modify('-2 day')->format('Y-m-d');
$targetDay = $dt->format('Y-m-d');
if ($targetDay === $yesterday) {
return '昨天 ' . $dt->format('H:i');
}
if ($targetDay === $beforeYesterday) {
return '前天 ' . $dt->format('H:i');
}
// 同一年
if ($dt->format('Y') === $now->format('Y')) {
return $dt->format('m-d H:i');
}
// 跨年
return $dt->format('Y-m-d H:i');
}
?>
<?php
date_default_timezone_set('Asia/Taipei');
echo formatFriendlyTime(time() - 30); // 30 秒前
echo formatFriendlyTime(time() - 3600); // 1 小時前
echo formatFriendlyTime(strtotime('-1 day 14:30')); // 昨天 14:30
echo formatFriendlyTime('2023-12-31 23:59'); // 2023-12-31 23:59 (跨年)
echo formatFriendlyTime('2024-03-15 09:00', 'America/New_York'); // 指定時區
?>
$precision 參數控制是否顯示秒、分鐘。dayjs/date-fns 即時渲染,避免時區不一致。這個函式已在多個高流量專案穩定運行,可直接放入 Helper 或 Trait 複用。