時間數據系列：入門PHP Zmanim

教學
PHP

致謝

在本篇部落格中，我將解釋與所謂的“猶太時間”（zmanim）計算相關的概念和技術；以及使用PHP Zmanim 庫所需的技巧——這是一個讓您能輕鬆計算猶太時間的函數庫。

PHPZmanim 庫由 Zachary Weixelbaum 維護。如同當今科技界的許多事物，PHP Zmanim 本身是基於 Eliyahu Hershfeld 所創建的基礎Kosher Java 庫。我對 Zachary 和 Eliyahu 深表感激——不僅因為他們在開發這些庫上投入的工作，也因為在我學習使用這些庫所需技術和猶太宗教規範（halacha）時所給予的支持。

引言

“本週下午祈禱（Mincha）的時間是什麼時候？”這個問題看似簡單卻頗為複雜。它的複雜之處在於“下午祈禱”看似不言自明，但（如同涉及猶太宗教規則（halacha）的許多事物一樣，需要大量的背景、評論和具體細節。

注意：如果您已熟悉猶太時間概念（zmanim），請隨意跳至標有“安裝 PHP Zmanim”的章節。我不會因此感到被冒犯或對您有所不滿。

要理解猶太宗教日、週及生活中精確計時的重要性並非易事。它影響著從禁食開始與結束的時刻，到何時說某些禱告已太晚（或太早），乃至擁有（更別說食用）麵包被禁止的瞬間。

換個說法，我想分享拉比亞伯拉罕·約書亞·赫舍爾在其著作《安息日》中的一段引言。

安息日的意義在於慶祝時間而非空間。我們六天生活在空間事物的專制之下；在安息日，我們試圖調整自己，感受時間中的神聖。

Rabbi Abraham Joshua Heschel, “The Sabbath”

即便有此解釋，一些讀者或許仍會疑惑：“為何對此大驚小怪？難道上帝會因你差了五分鐘而怪罪你嗎？”

這是個值得探討的問題，因為若不如此，本博客（及其所描述的技巧與技術）的需求與影響將被削弱。

當然，上帝並不在意。正如我的田徑教練不會“在意”我是否在跑步前熱身、進行休賽期訓練或攝取足夠水分。說實話，無論我訓練多刻苦，教練的健康狀況不會因此改變。然而，那位超越我下一場比賽表現、關心我的教練，希望我自己在意。他們希望我全心投入，只因他們知道這樣我的經歷會更加充實。

同樣地，上帝並不“關心”。但我們透過《托拉》和《塔木德》的文本知道，上帝希望我們去關心。因此，歷代猶太學者試圖——根據文本中呈現的證據——避免簡單和過於簡化的答案，深入挖掘以揭示更多細節。

回歸眼前問題：“下午祈禱的時間是什麼時候？”要理解這一點，我們首先需明白何謂“日”（相對於“夜”）；如何界定“早晨”與“下午”的分隔；如何有效地將一天劃分為各個部分；以及更多相關事宜。

雖然本博客將在必要時介紹這些概念和術語，但絕非詳盡無遺。

毫不意外，計算機已迅速解決了計算這些時間的問題，現有多種網站和應用程序隨時為我們效勞。即便有人希望自行編寫程序來進行這些計算，也有如KosherJava及其眾多端口（包括PHP、Swift、.Net、JavaScript、Python等）這類節省時間的解決方案。

儘管如此，理解這些工具背後的理論至關重要。任何希望建立網站或應用程式的人都必須確保其程式不會意外提供錯誤的時間。雖然如前所述，沒有人會因為在錯誤的時間祈禱而“下地獄”（姑且這麼說），但有一條嚴格的戒律：

וְלִפְנֵ֣י עִוֵּ֔ר לֹ֥א תִתֵּ֖ן מִכְשֹׁ֑ל וְיָרֵ֥אתָ מֵּאֱלֹהֶ֖יךָ
“lifnei iver lo titein michshol v’yareita mei-elohecha”
“勿在盲人面前放置絆腳石”

(Leviticus 19:14)

個人偶然犯錯是一回事，提供錯誤資訊導致他人（或更糟，許多人）犯錯，則是另一回事，他們相信從你的應用程式獲得的資訊是準確可信的。

基本時間

考慮到這一點，我們將從理解那些相對直接且受猶太傳統變化影響最小的時間開始：

  • 日出（Netz Hachma）是傳統的海上日出——太陽圓盤頂部接觸地平線的瞬間。
  • 日落（Shkia）則是每日循環的另一面——太陽頂部剛好落入地平線下的瞬間。
  • A “seasonal hour” (sha’ah) refers to the even division of daylight, the time between sunrise and sunset. There are always 12 seasonal hours, but they may be longer or shorter than a regular (on your clock) hour because the amount of daylight fluctuates with the season.
    • 請注意，某些傳統將一個sha’ah視為從黎明（alot hashachar，或簡稱“alot”，即日出前地平線上可見光線的時刻）到夜晚（tzeis hakochavim，或簡稱“tzeis”，即日落後地平線上無光線的時刻）時間的12等分。我們將在後續的部落格文章中更深入地探討黎明（alot）和夜晚（tzeit）。
  • 季節分（sha’ot zmaniyot）是季節小時的1/60，與季節小時一樣，可能比您的時鐘上的分鐘大或小。

如您所見，日出和日落構成了所有其他時間計算的基本核心，並且一天中有許多重要的猶太時間直接從這些時間衍生而來。例如，在某些傳統中，您會發現：

  • 安息日始於週五晚上，日落前18分鐘（shkia）
  • 安息日結束於週六晚上，日落後45（或50，或72）分鐘（shkia）
  • …依此類推。

計算中的“複雜情況”

一旦確定了日出和日落，下一步是識別黎明和夜晚這兩個關鍵時刻。黎明（Alot haShachar，或簡稱“Alot”）和夜晚（Tzeis hakochavim，或簡稱“Tzeis”）如同日出和日落一樣相互映照。黎明是地平線上可見光（但非太陽）的時刻。夜晚是光不再可見的時刻。

不幸的是，是否有“光”是非常主觀的，因此其計算方法五花八門。

  • 一些傳統使用日出前或日落後固定的時鐘分鐘數。
  • 其他則使用天文學來確定太陽在地平線以下特定度數的時間。
  • 還有一些使用公式，例如取從日出到日落的日光量，將其分為10個相等部分，然後從日出中減去或加到日落上。
  • 然而，還有一些人會選擇在太陽低於地平線的「等長」日（即春分或秋分，此時日照與黑暗時間完全相同），計算出該時間與日出之間的差異（以時鐘分鐘為單位），將這些分鐘對照特定日期的「季節分鐘」（「sha’ot zmaniyot」）進行標準化，最後從當天的日出時間中減去該數量（或將其添加到日落時間）。

聽起來很複雜嗎？正如本節標題所說，「這很複雜」。

我描述這些的目的並不是要確定一個「正確」的計算方法，而是幫助你理解每種計算方式的最終目標——同時讓你明白，不同的猶太傳統有多種方法來進行這些計算。

複雜的時刻

一旦你有了黎明（alot）、日出（netz）、日落（shkia）和夜晚（tzeis），就可以計算其他重要的每日時刻。這些包括：

  • 下午祈禱的最早時間（Mincha Gedola），通常計算為黎明或日出後一定數量的季節小時（sha’ah）。這個時間的意義在於，它是「下午」（字面上，過了中午）開始的最早時刻。
  • 下午祈禱的理想時間（Mincha ketana），計算為日出（netz）或黎明（alot）後更多數量的季節小時（sha’ah）。這裡的重點是，它明顯超過了當天3/4的時間，顯然已是下午——但又不至於不小心進入夜晚（tzeis）。
  • 最新下午禱告時間（Plag haMincha，或稱“plag”）通常計算為下午最佳禱告時間（mincha ketana）至夜晚（tzeis）之間的時段。

雖然還有其他幾個關鍵時間點，我們將在另一篇博客中討論，但這些足以讓我們開始。

安裝PHP Zmanim庫

處理完這些技術細節後，我們現在可以轉向…更多的技術細節！只不過這次是真正的技術細節。（對於那些從引言直接跳到這一部分的讀者，歡迎回來！很高興再次見到你們！）

PHP Zmanim是一個複雜的庫，不僅包含將Kosher Java引入PHP語言，還包括一些支持模塊，如Carbon（一個幫助加快日期和時間轉換、使其更簡單和更精確的工具）；Symfony（一個網頁設計框架）；以及一些其他較小的實用工具。

重點是，所有這些模塊都與PHP Zmanim協同工作，你需要安裝所有這些才能使任何功能運作。最簡單的安裝方法就是使用PHP的“composer”工具來管理依賴。

如果你需要在網絡服務器上運行PHP Zmanim，但無法在命令行上運行安裝程序，你仍然幸運。只需從本地安裝中複製./vendor目錄，並且——在某些注意事項下——它將能夠運作。

有哪些注意事項呢？最主要的一點是，確保你的主機供應商支援的PHP版本與你透過Composer安裝時使用的版本相匹配。

接下來，讓我們來看看實際的Composer安裝指令。我知道我們還沒開始實際編碼，但首先我們要設定一個用於存放腳本的目錄。在這篇部落格中，我將其命名為/phpzmanim_test。

在終端機視窗中，移動到該目錄：

cd /php zmanim_test

現在輸入以下指令：

composer -V

(注意，那是一個大寫的V)

這將確認Composer是否已安裝。如果未安裝，請快速搜索以找出在你的作業系統上安裝它的最佳方法。

接著，輸入以下指令：
composer require zachweix/php-zmanim

這將執行兩項操作：

  1. 首先，它會在當前目錄中建立一個composer.json文件，指示應安裝PHP Zmanim。
  2. 實際上，它會將PHP Zmanim安裝到當前目錄下的./vendor目錄中，無需額外步驟。

另一個與Composer相關的注意事項是，如果你需要更新，可以輕鬆地進入/phpzmanim_test目錄（或你命名的任何目錄）並輸入composer update指令。這將讀取composer.json文件中的信息，並更新其中找到的所有內容。

(劇透：這意味著你不應該刪除composer.json文件。然而，如果你不想的話，也無需將它複製到你的遠端站點與應用程序的其他部分一起。)

完成此步驟後，您需要在每個將使用PHP Zmanim庫的PHP腳本中包含以下行：

PHP

  

require 'vendor/autoload.php';

開始使用PHP Zmanim

現在PHP Zmanim已安裝，您可以開始使用它編寫代碼了。

為此，您首先需要創建一個PHP對象——一個集合（實際上是數組），其中包含傳遞給各種函數的數據。此對象包含您將要提取的時間的特定日期以及精確的位置信息。

使用“Zmanim::Create()”創建對象

在開始之前，您需要了解有關您請求時間的位置的一些信息：

  • 緯度和經度。
  • 時區，使用tz數據庫格式化。（例如：“America/New_York”）。
  • 該位置的海拔高度，如果您選擇使用它。（劇透：海拔高度很少影響這些計算。）
  • 您將計算的時間的年、月和日。

創建對象的格式如下：

PHP

  

$VARNAME = Zmanim::create(YEAR, MONTH, DAY, "NAME OF LOCATION", LATITUDE, LONGITUDE, ELEVATION, "TIME ZONE");

這裡有一個具體的例子：

PHP

  

$zmanim = Zmanim::create(2019, 2, 21, "New York City", 40.850519, -73.929214, 200, "America/New_York");

作為腳本，其中一些變量替換了字面輸入的樣子：

PHP

  

<?php
require 'vendor/autoload.php';
use PhpZmanim\Zmanim;
use PhpZmanim\Calendar\ComplexZmanimCalendar;
use PhpZmanim\Geo\GeoLocation;

$getdate = date('Y-m-d');
$getyear = date('Y', strtotime($getdate));
$getmonth = date('m', strtotime($getdate));
$getday = date('d', strtotime($getdate));

$locname = "Beit Knesset Chochmat Shlomo, Beachwood, OH";
$lat = 41.4939407;
$long = -81.516709;
$elev = 0;
$tz = 'America/New_York';

$zmanim = Zmanim::create($getyear, $getmonth, $getday, $locname, $lat, $long, $elev, $tz);

有了這段代碼，您就為指定位置的今天日期創建了一個對象。您甚至可以使用PHP的print_r()函數將其打印出來：

PHP

  

print_r($zmanim);

這應該會給您類似這樣的輸出：

PHP

  

PhpZmanim\Zmanim Object
(
    [calendar:PhpZmanim\Calendar\AstronomicalCalendar:private] => Carbon\Carbon Object
        (
            [endOfTime:protected] => 
            [startOfTime:protected] => 
            [constructedObjectId:protected] => 00000000000000080000000000000000
            [localMonthsOverflow:protected] => 
            [localYearsOverflow:protected] => 
            [localStrictModeEnabled:protected] => 
            [localHumanDiffOptions:protected] => 
            [localToStringFormat:protected] => 
            [localSerializer:protected] => 
            [localMacros:protected] => 
            [localGenericMacros:protected] => 
            [localFormatFunction:protected] => 
            [localTranslator:protected] => 
            [dumpProperties:protected] => Array
                (
                    [0] => date
                    [1] => timezone_type
                    [2] => timezone
                )

(還有更多，但您應該已經明白了).

獲取您的首個即時資訊 – 日出時間（Netz HaHachma）

一旦您創建了一個對象，使用 PHP Zmanim 來獲取特定時間幾乎是反高潮的。獲取日出時間就像這樣簡單：

PHP

  

$sunrise = $zmanim->sunrise;

如果您不熟悉它或以前沒有使用過，-> 表示您正在查詢一個對象（再次，一組數據元素）或使用一個內置方法

這將返回類似這樣的結果：

PHP

  

2024-12-20 07:48:52

對於那些跟隨學習的人，到目前為止完整的代碼看起來像這樣：

PHP

  

sunrise;
echo "$sunrise\n";
?>

總結

PHP Zmanim 還有很多內容需要涵蓋，我計劃在接下來的幾週內進行。但這至少可以讓您開始構建一個基於 PHP 的腳本或網站，並展示猶太時刻的準確時間。

一如既往，我歡迎在下面的評論中提出問題、更正和讚賞。

Source:
https://dzone.com/articles/time-data-series-getting-started-with-php-zmanim