PHP 日期時間格式化工具函式：支援中文星期、時間戳/字串雙模式

前言

專案常需將時間戳（1388678400）或日期字串（2012-11-03 00:46:22）格式化為「2012-11-03 週六」等顯示格式。本文提供一個 formatDate() 靜態方法，整合 自動偵測輸入類型、支援中文星期替換、格式字串相容 date() 語法，可直接納入共用工具類。

完整實作程式碼

<?php
class DateHelper {
    /** 中文星期對照表 */
    private static $weekNames = ['日', '一', '二', '三', '四', '五', '六'];

    /**
     * 格式化日期時間
     * @param string $format  格式字串，相容 date()，支援 'w' 為中文星期
     * @param int|string $datetime 時間戳或可被 strtotime 解析的字串
     * @param bool $useChineseWeek 是否將 'w' 替換為中文星期
     * @return string
     */
    public static function formatDate(string $format, $datetime, bool $useChineseWeek = false): string {
        // 1. 統一轉為時間戳
        // 若輸入為純數字且 > 3000 視為時間戳（避免誤判年份如 2024）
        if (is_numeric($datetime) && $datetime > 3000) {
            $ts = (int)$datetime;
        } else {
            $ts = strtotime($datetime);
            if ($ts === false) {
                throw new InvalidArgumentException("無法解析日期時間：$datetime");
            }
        }

        // 2. 處理中文星期替換
        if ($useChineseWeek && strpos($format, 'w') !== false) {
            $weekIndex = (int)date('w', $ts); // 0-6
            $format = str_replace('w', self::$weekNames[$weekIndex], $format);
        }

        // 3. 格式化輸出
        return date($format, $ts);
    }
}

// ---------- 使用範例 ----------
echo DateHelper::formatDate('Y-m-d w', '2012-11-03 00:46:22', true) . "\n"; // 2012-11-03 六
echo DateHelper::formatDate('Y-m-d w', '1388678400', true) . "\n";         // 2014-01-03 五

// 更多格式組合
echo DateHelper::formatDate('Y/m/d (w) H:i:s', '2024-01-15 14:30:00', true); // 2024/01/15 (一) 14:30:00
echo DateHelper::formatDate('Y年m月d日', '2024-01-15');                       // 2024年01月15日

進階擴充：支援完整中文日期格式

public static function formatChinese(string $datetime, string $pattern = 'Y年m月d日 (w) H:i'): string {
    return self::formatDate($pattern, $datetime, true);
}

常見格式字元速查表

效能與快取建議

• 若同一請求中重複格式化相同時間，可在函式內加入 static $cache = [] 以 $format.$datetime.$useChineseWeek 為鍵快取結果。
• 大量資料（>1 萬筆）格式化時，建議先取得時間戳陣列，再批次 array_map 處理，減少函式呼叫開銷。

結語

DateHelper::formatDate() 以 20 行核心程式碼解決「輸入類型不一、需中文星期、格式彈性」三大痛點。建議專案統一引用此工具，避免散落在各處的 date('Y-m-d', strtotime(...)) 造成維護困難。若專案使用 Laravel，可直接使用 Carbon 並擴充 ->isoFormat('YYYY年MM月DD日 dddd') 獲得更強大的國際化支援。