萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 友善相對時間格式化函式:從「剛剛」到「X天前」完整實作

需求場景

社群動態、留言板、通知系統常需顯示「5分鐘前」、「3小時前」、「昨天 14:30」等人類易讀的相對時間,而非冰冷的「2024-01-15 14:30:00」。本文提供一個功能完整、多語系支援、時區感知的格式化函式。

核心功能特性

  • 多粒度相對時間:秒/分/半小時/小時/天/週
  • 特殊詞彙:剛剛、昨天、前天
  • 時區支援:預設 UTC+8 (北京/台北),可自訂偏移
  • 語系陣列:易擴展多語言 (繁/簡/英/日...)
  • HTML 安全輸出:含 title 屬性顯示完整時間
  • 自訂格式:支援傳統 date() 格式字串

完整函式實作

<?php
/**
 * 格式化時間為人類友善相對字串
 * 
 * @param int    $timestamp   Unix 時間戳
 * @param string $format      'dt'=日期時間, 'd'=日期, 't'=時間, 'u'=相對時間, 其他=自訂格式
 * @param int    $timeoffset  時區偏移小時 (預設 8 = UTC+8),9999 表使用預設
 * @param string $custom_format 自訂 date() 格式字串 (當 $format 非預設值時)
 * @return string 格式化後的 HTML 字串
 */
function friendlyDate($timestamp, $format = 'u', $timeoffset = 9999, $custom_format = '') {
    // 語系包 (可外部化為語系檔)
    $lang = [
        'before' => '前',
        'day'    => '天',
        'yday'   => '昨天',
        'byday'  => '前天',
        'hour'   => '小時',
        'half'   => '半',
        'min'    => '分鐘',
        'sec'    => '秒',
        'now'    => '剛剛',
        'week'   => '週',
    ];
    
    // 格式預設值
    $date_fmt   = 'Y-n-j';
    $time_fmt   = 'H:i:s';
    $datetime_fmt = $date_fmt . ' ' . $time_fmt;
    
    // 時區處理
    $offset = ($timeoffset === 9999) ? 8 : (int)$timeoffset;
    $now = time();
    $timestamp += $offset * 3600;
    $now_adj = $now + $offset * 3600;
    
    // 非相對時間模式:直接使用 gmdate
    if ($format !== 'u') {
        switch ($format) {
            case 'dt': $format = $datetime_fmt; break;
            case 'd':  $format = $date_fmt; break;
            case 't':  $format = $time_fmt; break;
        }
        return gmdate($format ?: $custom_format, $timestamp);
    }
    
    // 相對時間模式
    $full_date = gmdate($datetime_fmt, $timestamp);
    $diff = $now_adj - $timestamp; // 秒差
    
    // 未來時間 (容差 60 秒)
    if ($diff < -60) {
        return '<span title="' . htmlspecialchars($full_date) . '">' . gmdate($datetime_fmt, $timestamp) . '</span>';
    }
    
    // 今日內
    $today_start = $now_adj - ($now_adj % 86400);
    if ($timestamp >= $today_start) {
        if ($diff >= 3600) {           // 1小時以上
            $h = (int)($diff / 3600);
            return '<span title="' . htmlspecialchars($full_date) . '">' . $h . $lang['hour'] . $lang['before'] . '</span>';
        } elseif ($diff >= 1800) {     // 30分鐘以上
            return '<span title="' . htmlspecialchars($full_date) . '">' . $lang['half'] . $lang['hour'] . $lang['before'] . '</span>';
        } elseif ($diff >= 60) {       // 1分鐘以上
            $m = (int)($diff / 60);
            return '<span title="' . htmlspecialchars($full_date) . '">' . $m . $lang['min'] . $lang['before'] . '</span>';
        } elseif ($diff > 0) {         // 1分鐘內
            return '<span title="' . htmlspecialchars($full_date) . '">' . $diff . $lang['sec'] . $lang['before'] . '</span>';
        } else {                       // 剛剛
            return '<span title="' . htmlspecialchars($full_date) . '">' . $lang['now'] . '</span>';
        }
    }
    
    // 過去 7 天內
    $days = (int)(($today_start - $timestamp) / 86400);
    if ($days >= 0 && $days < 7) {
        $time_part = gmdate($time_fmt, $timestamp);
        if ($days === 0) {
            return '<span title="' . htmlspecialchars($full_date) . '">' . $lang['yday'] . ' ' . $time_part . '</span>';
        } elseif ($days === 1) {
            return '<span title="' . htmlspecialchars($full_date) . '">' . $lang['byday'] . ' ' . $time_part . '</span>';
        } else {
            return '<span title="' . htmlspecialchars($full_date) . '">' . ($days + 1) . $lang['day'] . $lang['before'] . '</span>';
        }
    }
    
    // 超過一週:顯示完整日期
    return '<span title="' . htmlspecialchars($full_date) . '">' . gmdate($date_fmt, $timestamp) . '</span>';
}

使用範例

<?php
// 基本用法 (預設相對時間)
echo friendlyDate(time() - 30);           // 剛剛
echo friendlyDate(time() - 90);           // 1分鐘前
echo friendlyDate(time() - 3600);         // 1小時前
echo friendlyDate(time() - 7200);         // 2小時前
echo friendlyDate(time() - 86400);        // 昨天 HH:MM:SS
echo friendlyDate(time() - 172800);       // 前天 HH:MM:SS
echo friendlyDate(time() - 259200);       // 3天前
echo friendlyDate(time() - 604800);       // 7天前
echo friendlyDate(time() - 1209600);      // 2024-1-1 (完整日期)

// 指定時區 (UTC+0)
echo friendlyDate(time(), 'u', 0);        // 以 UTC 時間計算相對時間

// 傳統格式模式
echo friendlyDate(time(), 'dt');          // 2024-1-15 14:30:00
echo friendlyDate(time(), 'd');           // 2024-1-15
echo friendlyDate(time(), 't');           // 14:30:00
echo friendlyDate(time(), 'Y/m/d H:i');   // 自訂格式 2024/01/15 14:30

// 整合資料庫查詢
$stmt = $pdo->query("SELECT content, created_at FROM posts ORDER BY id DESC LIMIT 10");
while ($row = $stmt->fetch()) {
    echo '<div class="post">';
    echo '<p>' . htmlspecialchars($row['content']) . '</p>';
    echo '<time>' . friendlyDate(strtotime($row['created_at'])) . '</time>';
    echo '</div>';
}

前端配合:時間戳自動更新

相對時間隨時間流逝需更新,建議配合 JavaScript 定期重新計算:

<!-- HTML 輸出 data-timestamp 屬性 -->
<time class="friendly-time" data-timestamp="<?php echo $timestamp; ?>">
    <?php echo friendlyDate($timestamp); ?>
</time>

<script>
// 每 30 秒更新一次
setInterval(() => {
    document.querySelectorAll('.friendly-time').forEach(el => {
        const ts = parseInt(el.dataset.timestamp);
        const diff = Math.floor(Date.now() / 1000) - ts;
        let text = '';
        
        if (diff < 60) text = diff + '秒前';
        else if (diff < 3600) text = Math.floor(diff/60) + '分鐘前';
        else if (diff < 86400) text = Math.floor(diff/3600) + '小時前';
        else text = new Date(ts * 1000).toLocaleDateString();
        
        el.textContent = text;
        el.title = new Date(ts * 1000).toLocaleString();
    });
}, 30000);
</script>

進階擴充:多語系支援

// 全域語系設定 (可從資料庫/設定檔載入)
$GLOBALS['FRIENDLY_DATE_LANG'] = [
    'zh-TW' => ['before'=>'前','day'=>'天','yday'=>'昨天','byday'=>'前天','hour'=>'小時','half'=>'半','min'=>'分','sec'=>'秒','now'=>'剛剛'],
    'zh-CN' => ['before'=>'前','day'=>'天','yday'=>'昨天','byday'=>'前天','hour'=>'小时','half'=>'半','min'=>'分','sec'=>'秒','now'=>'刚刚'],
    'en'    => ['before'=>'ago','day'=>'d','yday'=>'yesterday','byday'=>'day before yesterday','hour'=>'h','half'=>'half','min'=>'m','sec'=>'s','now'=>'just now'],
];

function friendlyDateI18n($timestamp, $format='u', $timeoffset=9999, $custom='', $locale='zh-TW') {
    $lang = $GLOBALS['FRIENDLY_DATE_LANG'][$locale] ?? $GLOBALS['FRIENDLY_DATE_LANG']['zh-TW'];
    // ... 將 $lang 區域化傳入核心邏輯 ...
}

效能與快取建議

  • 靜態頁面:產生靜態 HTML 時直接輸出完整時間,由前端 JS 計算相對時間 (SEO 友善)
  • 動態頁面:搭配 Redis/Memcached 快取格式化結果,Key 含 timestamp + 語系
  • 批次處理:大量資料一次格式化,避免重複呼叫 gmdate()

總結

本函式提供開箱即用的相對時間格式化,涵蓋時區、語系、HTML 安全、前端同步等實務考量。可直接複製到專案工具類中,或封裝為 Composer 套件 (composer require yourname/friendly-date) 供多專案共用。

copyright © 萬盛學電腦網 all rights reserved