函數簡介

getdate() 將 UNIX 時間戳轉換為包含完整日期時間元件的關聯陣列。對比 date() 返回字串，getdate() 返回結構化數據，適合需單獨訪問年、月、日、星期等元件的場景。

語法與參數

getdate(?int $timestamp = null): array

• $timestamp：可選 UNIX 時間戳，預設為當前時間 time()
• 返回：關聯陣列，鍵名固定（見下表）

返回陣列鍵值完整對照表

鍵名	類型	說明	範例值
seconds	int	秒 (0-59)	59
minutes	int	分鐘 (0-59)	14
hours	int	小時 (0-23)	7
mday	int	月份中的第幾天 (1-31)	26
wday	int	星期中的第幾天 (0=Sunday - 6=Saturday)	6
mon	int	月份數字 (1-12)	12
year	int	完整年份 (4 位數)	2024
yday	int	年份中的第幾天 (0-365)	359
weekday	string	星期名稱 (完整英文)	Saturday
month	string	月份名稱 (完整英文)	December
0	int	UNIX 時間戳 (同 $timestamp)	1706271059

代碼範例

基本用法

<?php
$now = getdate();

echo "=== getdate() 返回陣列結構 ===\n";
foreach ($now as $key => $value) {
    echo "{$key} => {$value}\n";
}

/* 輸出範例：
seconds => 59
minutes => 14
hours => 7
mday => 26
wday => 6
mon => 12
year => 2024
yday => 359
weekday => Saturday
month => December
0 => 1706271059
*/
?>

指定時間戳

<?php
// 解析特定時間戳
$ts = strtotime('2024-02-29 12:00:00'); // 閏年
$dateInfo = getdate($ts);

echo "指定時間戳 {$ts}:\n";
echo "日期: {$dateInfo['year']}-{$dateInfo['mon']}-{$dateInfo['mday']}\n";
echo "星期: {$dateInfo['weekday']}\n";
echo "年間第幾天: {$dateInfo['yday']}\n";
?>

實戰應用場景

1. 動態生成日期選單（年/月/日）

<?php
function buildDateSelectors(int $startYear = 2000, int $endYear = null): array {
    $endYear ??= (int)date('Y') + 1;
    $now = getdate();
    
    $years = range($startYear, $endYear);
    $months = range(1, 12);
    $days = range(1, 31); // 實際需根據年月動態計算
    
    return [
        'years'   => array_combine($years, $years),
        'months'  => array_combine($months, array_map(fn($m) => sprintf('%02d', $m), $months)),
        'days'    => array_combine($days, array_map(fn($d) => sprintf('%02d', $d), $days)),
        'current' => [
            'year'  => $now['year'],
            'month' => $now['mon'],
            'day'   => $now['mday'],
        ]
    ];
}

// 前端直接用於 <select> options
$selectors = buildDateSelectors();
?>

2. 判斷日期屬性（週末、月末、季度等）

<?php
function analyzeDate(?int $timestamp = null): array {
    $d = getdate($timestamp);
    
    // 當月天數
    $daysInMonth = cal_days_in_month(CAL_GREGORIAN, $d['mon'], $d['year']);
    
    return [
        'is_weekend'   => in_array($d['wday'], [0, 6], true),
        'is_month_end' => $d['mday'] === $daysInMonth,
        'is_month_start' => $d['mday'] === 1,
        'quarter'      => (int)ceil($d['mon'] / 3),
        'week_of_year' => (int)date('W', $timestamp ?? time()),
        'day_of_year'  => $d['yday'] + 1, // yday 從 0 開始
        'days_in_month' => $daysInMonth,
    ];
}

print_r(analyzeDate(strtotime('2024-12-31')));
/*
Array
(
    [is_weekend] => 
    [is_month_end] => 1
    [is_month_start] => 
    [quarter] => 4
    [week_of_year] => 53
    [day_of_year] => 366
    [days_in_month] => 31
)
*/
?>

3. 本地化星期/月份名稱

<?php
function getLocalizedDateInfo(?int $timestamp = null, string $locale = 'zh_TW'): array {
    $d = getdate($timestamp);
    
    $weekdays = [
        'zh_TW' => ['星期日','星期一','星期二','星期三','星期四','星期五','星期六'],
        'zh_CN' => ['周日','周一','周二','周三','周四','周五','周六'],
        'en'    => ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday','Saturday'],
    ];
    $months = [
        'zh_TW' => ['','一月','二月','三月','四月','五月','六月','七月','八月','九月','十月','十一月','十二月'],
        'zh_CN' => ['','一月','二月','三月','四月','五月','六月','七月','八月','九月','十月','十一月','十二月'],
        'en'    => ['','January','February','March','April','May','June','July','August','September','October','November','December'],
    ];
    
    $w = $weekdays[$locale] ?? $weekdays['en'];
    $m = $months[$locale] ?? $months['en'];
    
    return [
        'weekday' => $w[$d['wday']],
        'month'   => $m[$d['mon']],
        'year'    => $d['year'],
        'mday'    => $d['mday'],
    ];
}

print_r(getLocalizedDateInfo(time(), 'zh_TW'));
/*
Array
(
    [weekday] => 星期一
    [month] => 一月
    [year] => 2024
    [mday] => 15
)
*/
?>

getdate() vs 替代方案

方法	返回類型	適用場景	效能
getdate()	array	需多個日期元件、本地化名稱、結構化處理	中等（內部調用 localtime）
date() 多次調用	string	僅需 1-2 個格式化字串	快（單次格式化）
DateTime 物件	object	需日期運算、比較、時區轉換、格式化	較慢（物件開銷）但功能最全
localtime()	array (索引)	底層 C 函數映射，無名稱鍵	最快

注意事項

• getdate() 使用系統本地時區（受 `date_default_timezone_set()` 影響）。需 UTC 時間請用 `gmdate()` 配合手動構建陣列，或 `new DateTime('@' . $ts, new DateTimeZone('UTC'))`。
• 返回陣列鍵名固定且區分大小寫（全部小寫，除了數字鍵 `0`）。
• wday 0=Sunday，符合美式習慣；中文環境常需映射為 1=Monday（ISO-8601）。
• PHP 8.0+ 若傳入無效時間戳（負數、超出範圍）會拋出 ValueError，舊版本返回 false/空陣列。

總結

getdate() 是快速獲取結構化日期元件的便捷函數，特別適合生成表單選單、判斷日期屬性、本地化顯示等場景。現代專案中，若涉及複雜日期運算、時區處理、不可變性需求，建議遷移至 DateTimeImmutable 物件導向 API，但 getdate() 在簡單腳本、模板渲染、舊代碼維護中依然實用高效。