PHP 中date_sunset 函數返回的數據格式是什麼？該怎麼正確解析它？

gitbox 2025-08-15

PHP 中的date_sunset函數是用來獲取某個日期和位置的日落時間。它基於給定的緯度、經度以及日期計算出日落時間。通常，這個函數返回的是一個Unix 時間戳，也就是從1970年1月1日到指定時間的秒數。

date_sunset 函數簡介

date_sunset函數的基本語法如下：

 <span><span><span class="hljs-title function_ invoke__">date_sunset</span></span><span>(time, format, latitude, longitude, zenith, gmt_offset);
</span></span>

time : 可選，時間戳，默認為當前時間。
format : 結果格式。可以是SUNFUNCS_RET_TIMESTAMP （Unix 時間戳，默認值）、 SUNFUNCS_RET_STRING （返回一個字符串格式的時間，如'6:00 PM'）、 SUNFUNCS_RET_DOUBLE （返回日落角度）。
latitude和longitude : 必須提供，分別是日落地點的緯度和經度。
zenith : 可選，太陽的天頂角度，通常為90.5度，表示日落時太陽的角度。
gmt_offset : 可選，時區偏移量，默認為0。

返回格式

SUNFUNCS_RET_TIMESTAMP（默認）

如果format參數設置為SUNFUNCS_RET_TIMESTAMP （或者不傳），則函數會返回一個Unix 時間戳，即從1970年1月1日午夜開始到日落時刻的秒數。

示例：

 <span><span><span class="hljs-variable">$sunset</span></span><span> = </span><span><span class="hljs-title function_ invoke__">date_sunset</span></span><span>(</span><span><span class="hljs-title function_ invoke__">time</span></span><span>(), SUNFUNCS_RET_TIMESTAMP, </span><span><span class="hljs-number">40.7128</span></span><span>, -</span><span><span class="hljs-number">74.0060</span></span><span>);
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-variable">$sunset</span></span><span>;
</span></span>

返回結果將是一個數字，表示Unix 時間戳。

SUNFUNCS_RET_STRING

如果format參數設置為SUNFUNCS_RET_STRING ，則返回一個格式化的時間字符串，通常是12小時制的時間表示（例如'6:00 PM'）。

示例：

 <span><span><span class="hljs-variable">$sunset</span></span><span> = </span><span><span class="hljs-title function_ invoke__">date_sunset</span></span><span>(</span><span><span class="hljs-title function_ invoke__">time</span></span><span>(), SUNFUNCS_RET_STRING, </span><span><span class="hljs-number">40.7128</span></span><span>, -</span><span><span class="hljs-number">74.0060</span></span><span>);
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-variable">$sunset</span></span><span>;
</span></span>

輸出結果可能類似於6:30 PM ，表示紐約市的日落時間。

SUNFUNCS_RET_DOUBLE

如果format參數設置為SUNFUNCS_RET_DOUBLE ，則返回一個浮動的小數值，表示太陽的高度角度。返回值一般為負數，表示太陽位於地平線以下，且值的絕對值越大，表示太陽越低。

示例：

 <span><span><span class="hljs-variable">$sunset</span></span><span> = </span><span><span class="hljs-title function_ invoke__">date_sunset</span></span><span>(</span><span><span class="hljs-title function_ invoke__">time</span></span><span>(), SUNFUNCS_RET_DOUBLE, </span><span><span class="hljs-number">40.7128</span></span><span>, -</span><span><span class="hljs-number">74.0060</span></span><span>);
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-variable">$sunset</span></span><span>;
</span></span>

返回值可能是一個浮動的小數，例如-0.934 ，表示太陽在地平線以下的角度。

如何正確解析date_sunset的返回值？

由於date_sunset返回的結果可能是不同格式的數據，正確的解析方法取決於你所使用的format參數。

1.解析Unix 時間戳

如果你使用的是SUNFUNCS_RET_TIMESTAMP ，即返回的結果是Unix 時間戳，可以通過date函數來將其轉換為可讀的日期和時間格式。

示例：

 <span><span><span class="hljs-variable">$sunset_timestamp</span></span><span> = </span><span><span class="hljs-title function_ invoke__">date_sunset</span></span><span>(</span><span><span class="hljs-title function_ invoke__">time</span></span><span>(), SUNFUNCS_RET_TIMESTAMP, </span><span><span class="hljs-number">40.7128</span></span><span>, -</span><span><span class="hljs-number">74.0060</span></span><span>);
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-title function_ invoke__">date</span></span><span>(</span><span><span class="hljs-string">"Y-m-d H:i:s"</span></span><span>, </span><span><span class="hljs-variable">$sunset_timestamp</span></span><span>);
</span></span>

這將輸出一個標準的日期時間格式，如2025-06-16 19:45:00 。

2.解析時間字符串

如果你使用的是SUNFUNCS_RET_STRING ，返回的是一個格式化的時間字符串，你可以直接將其輸出或者進一步處理。

示例：

 <span><span><span class="hljs-variable">$sunset_string</span></span><span> = </span><span><span class="hljs-title function_ invoke__">date_sunset</span></span><span>(</span><span><span class="hljs-title function_ invoke__">time</span></span><span>(), SUNFUNCS_RET_STRING, </span><span><span class="hljs-number">40.7128</span></span><span>, -</span><span><span class="hljs-number">74.0060</span></span><span>);
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"The sunset time is: "</span></span><span> . </span><span><span class="hljs-variable">$sunset_string</span></span><span>;
</span></span>

這將輸出類似The sunset time is: 6:30 PM的結果。

3.解析太陽高度角

如果你使用的是SUNFUNCS_RET_DOUBLE ，可以通過返回的浮動值來判斷太陽的高度角度。這個值通常是負數，代表太陽已經下落。

示例：

 <span><span><span class="hljs-variable">$sunset_angle</span></span><span> = </span><span><span class="hljs-title function_ invoke__">date_sunset</span></span><span>(</span><span><span class="hljs-title function_ invoke__">time</span></span><span>(), SUNFUNCS_RET_DOUBLE, </span><span><span class="hljs-number">40.7128</span></span><span>, -</span><span><span class="hljs-number">74.0060</span></span><span>);
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"Sunset angle: "</span></span><span> . </span><span><span class="hljs-variable">$sunset_angle</span></span><span>;
</span></span>

返回值會是一個小數，比如-0.934 ，表示太陽的角度。

總結

date_sunset函數非常有用，尤其是在需要根據某個地點的緯度和經度來獲取日落時間時。它返回的數據格式取決於format參數的值，可以是Unix 時間戳、格式化時間字符串或者太陽的高度角度。為了正確解析返回值，需要根據你選擇的格式，使用合適的函數進行轉換或顯示。

通過掌握這些基本用法，你可以在PHP 中更方便地處理日落時間的相關數據，無論是進行日落提醒、天氣預報、還是天文計算，都能提供有效的幫助。