Time Data Series: Working with PHP Zmanim

Acknowledgements

This post continues my exploration of concepts and techniques related to both the way so-called “Jewish times” (zmanim) are calculated; as well as the techniques needed to use the PHP Zmanim library – a library of functions that let you easily calculate Jewish times. Once again I owe a huge debt of gratitude to several folks – including Eliyahu Hershfeld, creator of the Kosher Java library, Zachary Weixelbaum (owner of the PHP Zmanim library, a port of Kosher Java), Elyahu Jacobi (who built RoyZmanim.com with those tools and patiently explained so many concepts to me), and Maor Neim, who offered explanations that turned theory into practice.

Introduction

In my last post I explored both the foundational concepts of Jewish time calculations (zmanim) and also the initial steps needed to install and use PHP Zmanim. We got as far as calculating sunrise with that library.

By itself, this isn’t particularly impressive. The fact is that, with the same information (latitude, longitude, time zone, and a specific date) you can get the same information using PHP’s built-in functions.

In this post, we’re going to get into the types of calculations you CAN’T get with built-in PHP tools, not only because they require some “interesting” time manipulations, but because there are so many ways to calculate the same religiously significant moment, based on various Rabbinic opinions and traditions.

The Answer to Every Jewish Question Starts with “Well, it depends…”

Let me take a minute to unpack that idea in a little more detail.

In the last post, I started to get into this idea:

Dawn is the moment when light (but not the sun) is visible over the horizon. Unfortunately, whether or not there is or isn’t “light” is highly subjective, and therefore the way it’s come to be calculated ranges all over the map.

Some traditions use a fixed number of clock minutes before sunrise or after sunset.
Others will use astronomy to identify the time when the sun is below the horizon by a specific number of degrees.
Others will use a formula, such as taking the amount of daylight (from sunrise to sunset), dividing that into 10 equal parts, and then subtracting that amount from sunrise or adding it to sunset.
Still others will take the time the sun is below the horizon on an “equal” day (meaning the spring or fall equinox, when the amount of sunshine and darkness are exactly the same), calculate the difference (in clock minutes) between that time and sunrise, normalize those minutes against “seasonal minutes” (“sha’ot zmaniyot”) for the specific day in question, and finally subtract that amount from sunrise (or add THAT to sunset) for the day in question.

One moment of the day, but a wide variety of ways to determine it.

It may be hard for those outside of mainstream orthodox Judaism to understand, and is definitely the subject of a completely different type of blog post, but the answer is to embrace the understanding that all of the calculations above (and many others) are capital-T “True”. Not just in a “well, it’s how I feel about it so it’s true to me” kind of way, but as being absolutely, factually, empirically true even when one method stands in opposition to another (or several others).

Like I said, THAT is the topic of a completely different blog post.

For now, I mention this to explain why, in creating the Kosher Java library, Eliyahu Hershfeld took the route of enabling the ability to easily calculate times using ANY of those methods, rather than trying to espouse a single method and coding exclusively for that. And ports – such as Zachary Weixelbaum’s PHP Zmanim library – simply continue with that ideal.

Which brings us back to the nitty-gritty of using the PHP Zmanim library.

Making Time Pretty

In the last post we left off with this snippet of code:

Which produced a result that looked something like this:

2024-12-20 07:48:52

It works, but it’s not what I’d want to see on a page when I’m just expecting a simple “7:48 am”.

Which brings me to the next interesting insight for the PHP Zmanim library: You can format the output using another function, rather than hammering through PHP’s built-in options. You’ll still use the PHP time/date formatting codes but getting what you want is easier.

Let’s say I want to only display the hour, minute, and am/pm for the sunrise output. I’d add a line like this:

Which would look like this when printed to the screen:

7:48 am

Getting your first actual real time – Mincha Gedola

The problem with using sunrise/sunset as an example is that PHP has built-in options to do the exact same thing. So let’s look at getting a time that is more relevant to Jewish religious times: the earliest time for afternoon prayers (Mincha Gedola).

Once again, it’s somewhat anti-climactic in that it’s a single command:

$gedolah = $zmanim->minchaGedola;

Which outputs a time like this:

2024-12-20 12:46:55

HOWEVER, as I mentioned earlier in this post, there are several ways to calculate this time. Here are all the methods supported by the PHP Zmanim library:

minchaGedola: Returns a time 6.5 halachic hours (shaos zmaniyos) after sunrise.
minchaGedola30Minutes: Returns the time 30 standard (clock) minutes after the half-day calculation (chatzot).
minchaGedola72Minutes: Calculates according to the Magen Avraham (Abraham Abele Gombiner, 1635-1682) with the day starting 72 minutes before sunrise and ending 72 minutes after sunset.
minchaGedola16Point1Degrees: Calculated according to the Magen Avraham with the day starting and ending when the sun is 16.1 degrees below the horizon.
minchaGedolaAhavatShalom: Calculated based on the opinion of Rabbi Yaakov Moshe Hillel as half a seasonal hour (shaah) after mid-day (chatzos) with seasonal minutes (shaos zmaniyos) calculated based on a day starting 72 minutes before sunrise and ending 13.5 minutes after sunset.
minchaGedolaGreaterThan30: This is a convenience method that returns the later of the standard “minchaGedola” function or ‘minchaGedola30Minutes. In the winter when 1/2 of a seasonal hour (sha’ah) is less than 30 minutes, then minchaGedola30Minutes will be returned, otherwise the regular minchaGedola will be returned.
minchaGedolaAteretTorah: This method returns the time of mincha ketana according to the Magen Avraham with the day starting and ending when the sun is 16.1 degrees below the horizon.
minchaGedolaBaalHatanya: This calculation is based on the opinion of the Baal Hatanya

minchaGedolaBaalHatanyaGreaterThan30: This is a convenience method that returns the later of either minchaGedolaBaalHatanya or minchaGedola30Minutes. In the winter when 1/2 of a seasonal hour (sha’ah) is less than 30 minutes, then minchaGedola30Minutes will be returned, otherwise minchaGedolaBaalHatanya will be returned.
minchaGedolaGRAFixedLocalChatzos30Minutes: This method returns a time based on Rav Moshe Feinstein’s opinion.

As you can see, there are a number of opinions. Determining which one you want/need to use is outside the scope of this blog post, and will likely require some conversations with the users of the app or website, as well as a Rabbi. Or two. Or several.

But the good news is that to use any of them, it’s as simple as:

Getting something complicated – Nightfall (Tzais Hakochavim)

Now that you’ve seen how we get one time, you should understand that even times that my prvious post labeled as “complicated” aren’t that that complicated. Furthermore, it should reinforce your understanding of just how powerful a tool like PHP Zmanim is, because of what it enables you to do in such a short time.

Calculating nightfall (tzais hakochavim) is as simple as the command

$tzais = $zmanim->tzais;

If there is any challenge at all, it’s the sheer number of variations to consider. I’m listing them here without explanation, just so you have a sense of how many there are. That’s right, there are 32 different options for calculating this one time. I list them here without detailed explanation simply to underscore my point:

tzais
tzais72
tzaisGeonim3Point7Degrees
tzaisGeonim3Point8Degrees
tzaisGeonim5Point95Degrees
tzaisGeonim3Point65Degrees
tzaisGeonim3Point676Degrees
tzaisGeonim4Point61Degrees
tzaisGeonim4Point37Degrees
tzaisGeonim5Point88Degrees
tzaisGeonim4Point8Degrees
tzaisGeonim6Point45Degrees
tzaisGeonim7Point083Degrees
tzaisGeonim7Point67Degrees
tzaisGeonim8Point5Degrees
tzaisGeonim9Point3Degrees
tzaisGeonim9Point75Degrees
tzais60
tzaisAteretTorah
tzais72Zmanis
tzais90Zmanis
tzais96Zmanis
tzais90
tzais120
tzais120Zmanis
tzais16Point1Degrees
tzais26Degrees
tzais18Degrees
tzais19Point8Degrees
tzais96
tzaisBaalHatanya
tzais50

Time (and this blog series) Marches On

Armed with the information in this post, you could probably make decent headway simply by looking through the main README on Zachary’s PHP Zmanim page itself, and selecting the best (for your purposes) calculations for:

Sunrise and Sunset (no, do not sing That Song)
A “seasonal” hour (Sha’ah Zmanim)
Dawn (alos hashachar)
The earliest time to put on tallit and tefillin (misheyakir)
The latest time to say Shema (sof zman kria shema)
The latest time for morning prayers (sof zman tefillah)
When Passover begins
Halfway through the day (chatzos)
The earliest time for afternoon prayers (mincha gedola)
The “best” time for afternoon prayers (mincha ketana)
The latest time for afternoon prayers (plag hamincha)
The time to light Shabbat candles
Dusk – the time between sunset and night (bain hashmashot)
Night (tzais hakochavim)
Halfway through the night (chatozs halayla)

But there is still more to cover. In upcoming articles I’ll talk about:

Taking these standard times and adjusting them for synagogue specific needs (“Mincha starts 25 minutes before Shkia each day”).
Using the PHP Zmanim library to display non-time calculations such as the weekly Torah Portion, Rosh Chodesh, and the Molad.
Leveraging the build-in astronomy functions for time calculations that aren’t built into the library itself.

I hope you’ll continue on this journey with me. As always if you have questions, comments, or kudos, please leave them in the comments.