时间数据序列：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”

即便有此解释，一些读者或许仍会疑惑：“为何对此大惊小怪？你是说，如果时间差了5分钟，上帝就会怪罪于你吗？”

这是个合理的问题，值得探讨片刻，否则本博客（及其所描述的技术与技巧）的必要性乃至影响力都将大打折扣。

当然，上帝并不在意。正如我的田径教练不会“关心”我是否在跑步前热身，是否进行淡季训练，或是否喝足够的水。坦白说，无论我训练得多刻苦，我的教练都不会因此更健康。然而，那位超越下一场比赛成绩关心我的教练，希望我自己在乎。他们希望我全情投入，只因为他们知道，这样我的经历将因之更加充实。

同样，上帝并不“关心”。但我们通过《托拉》和《塔木德》的文本知道，上帝希望我们去关心。因此，犹太学者们历经千年，尝试利用文本中的证据，摒弃简单和过于简化的答案，深入挖掘以揭示细节。

回到当前的问题：“下午祈祷是什么时间？”要理解这一点，我们首先需要明白何为“日”（相对于“夜”）；如何区分“早晨”与“下午”的界限；如何有效地将一天划分成若干部分；以及其他许多相关内容。

虽然本博客会在必要时介绍这些概念和术语，但绝不应被视为详尽无遗的指南。

毫不意外，计算机已迅速解决了这些时间的计算问题，现在有大量网站和应用程序随时准备为我们服务。即使有人希望编写自己的程序来完成这些计算，也有节省时间的解决方案，如代码库KosherJava及其众多端口，包括PHP、Swift、.Net、JavaScript、Python等。

尽管如此，理解这些工具背后的理论至关重要。任何希望创建网站或应用程序的人都必须确保其程序不会错误地显示错误的时间。如前所述，虽然不会因为祷告时间错误而“下地狱”（打个比方），但有一条严格的诫命：

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

(Leviticus 19:14)

。如果个人无意中犯了错误是一回事，而提供错误信息导致他人（或更糟的是，许多人）基于从你的应用程序获得的准确可信信息而犯错，则是另一回事。

考虑到这一点，我们将从理解那些相对直接且受犹太传统变化影响最小的时刻开始：

日出（Netz Hachma）是传统的航海日出——太阳圆盘顶部边缘触及地平线的瞬间。

  • 日落（Shkia）则是这一天的另一面——太阳顶部边缘刚好降至地平线以下的时刻。

  • 需要注意的是，有些传统将时间分为12个单位，从黎明（alot hashachar，或简称为“alot”，即日出前地平线上的可见光）到夜晚（tzeis hakochavim，或简称为“tzeis”，即日落后地平线上无可见光）。我们将在博客后续部分更深入地探讨黎明（alot）和夜晚（tzeit）。

  • 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’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