DEV Community

Cover image for Time Data Series: Written In Our Stars
Leon Adato
Leon Adato

Posted on • Originally published at adatosystems.com

Time Data Series: Written In Our Stars

#php #time #jewish

Once upon a time (i.e. way back in October 2024) I wrapped up a blog in this series with:

Believe it or not, there’s still more to cover. In the coming weeks whenever I get to it, I’d like to cover ways to leverage the built-in astronomy functions for time calculations. Believe it or not, it can really matter in terms of having truly accurate times for things like the start and end of Shabbat and holidays, along with other observances.

And here we are in 2025, when it’s finally time for me to fulfill that promise, and talk about how the KosherJava library (and by extension, the PHP Zmanim port I’ll be using in this blog) can help you calculate and display what amount to straight astronomy in your application or web page.

Once again I need to begin by expressing my deep gratitude to Zachary Weixelbaum and Eliyahu Hershfeld, who both continue to answer so many of my persistent (and often basic) questions with patience, care, and good humor.

The House of the Rising Sun

The core aspect of what I’m showing is fairly simple: For a specific location (latitude/longitude, plus timezone) and date, find the time of day that the sun will be at a given elevation point.

Or to be even more specific: At what time will the sun be at 20 degrees above the horizon on June 10, 2025 in Cleveland? So let’s break down the key elements of PHP Zmanim we’ll be focusing on today.

These two lines load the parts of the PHP library we’ll be using.

use PhpZmanim\Geo\GeoLocation; use PhpZmanim\Calendar\ComplexZmanimCalendar;
Enter fullscreen mode Exit fullscreen mode

Next, we set up a location object (using variables for location name, latitude, longitude, elevation, and time zone); and a calendar object (using the location object we just instantiated along with the year, month, and day):

$location = new GeoLocation($locname, $lat, $long, $elev, $tz); $zmanim = new ComplexZmanimCalendar($location, $getyear, $getmonth, $getday);
Enter fullscreen mode Exit fullscreen mode

Finally, the code that calculates and displays the results:

$sunrise = $zmanim->getsunrise(); $twenty = $zmanim->getSunriseOffsetByDegrees(70); print("sunrise: $sunrise\n20 degrees: $twenty\n");
Enter fullscreen mode Exit fullscreen mode

If playing along at home, I should explain that I grabbed both the regular sunrise simply as a reference to the time at which the sun is 20 degrees up in the sky.

I also need to explain that yes, I know that 70 is not 20, so how does THAT work out? The getSunriseOffsetByDegrees function “thinks” of the sun as being at 0 degrees when it’s at its zenith, and 90 degrees at the horizon line. So for the purposes of this function going up (higher in the sky) causes the degree value to go down.

The full code looks like this:

use PhpZmanim\Zmanim; use Carbon\Carbon; use PhpZmanim\Calendar\ComplexZmanimCalendar; use PhpZmanim\Geo\GeoLocation; # Set variables: #41.4939407, -81.516709; $locname = "Beit Knesset Chochmat Shlomo, Beachwood, OH"; $lat = 41.4939407; $long = -81.516709; $elev = 0; $tz = 'America/New_York'; $getyear = "2025"; $getmonth = "06"; $getday = "10"; $location = new GeoLocation($locname, $lat, $long, $elev, $tz); $zmanim = new ComplexZmanimCalendar($location, $getyear, $getmonth, $getday); $sunrise = $zmanim->getsunrise(); $twenty = $zmanim->getSunriseOffsetByDegrees(70); print("sunrise: $sunrise\n20 degrees: $twenty\n"); ?>
Enter fullscreen mode Exit fullscreen mode

When the Night Has Come, and the Land is Dark…

I’m sure there are useful reasons to know the time when the sun is at a certain point in the sky during the day, but from a religious perspective, there are far more reasons to want to know when the sun is below the horizon line. I say “religious” because I can think of at least two that care about the time of the sun’s position before sunrise: Judaism and Islam.

Both have a concept of dawn that indicates the very first visible lightening of the sky in the east. This time is known as fajr in Islam and alot hashachar in Judaism.

Because we’re talking about a matter of perception, it can be ferociously difficult to nail down, a matter not made any easier by the constant shifting of the sun over the year, and the differences due to latitude.

However – and bypassing a huge swath of religious debate – let’s accept the opinion that the first light is visible by perceptive humans on a clear day when the sun is 18

degrees below the horizon. How can we calculate that?

Honestly, it’s not hard now that you know the basic structure. In fact, we just have to change one thing:

$dawn = $zmanim->getSunriseOffsetByDegrees(90+18);

Yes, I could have just typed 108 but I wanted to make it explicit that we’re calculating 18 degrees before sunrise (90 degrees from the zenith).

Get Me to the Church Synagogue on Time…

To offer a more involved – not to mention specific – example of how this can be used, I’d like to explain one method of finding the time for “Tzeit haKochavim” (“nightfall”, which is more poetically described as the time when it’s dark enough to see 3 large stars in the sky). For this particular method, the following series of calculations are used:

  1. Select the date of the equinox (spring or fall)
  2. Get the time for sunset
  3. Get the time when the sun is 3.86 degrees below the horizon (after sunset)
  4. Get the difference in minutes between those 2 times
  5. Select the current date
  6. Calculate “seasonal minutes” – an even division of daylight 6.1) Subtract sunset from sunrise to get the total amount of daylight 6.2) Divide that time into 12 even “seasonal hours” 6.3) Divide 1 seasonal hour into 60 even “seasonal minutes”
  7. multiply the clock minutes you got from the equinox day calculations and multiply them by seasonal minutes.
  8. And finally, add THAT number of minutes to sunset, to get the time of “nightfall” / “Tzeit haKochavim”

Confused? Yep, me too. It took me a while to wrap my head around this. But here’s what it looks like in code:

First, let’s set our location and today’s date:

$locname = "Beit Knesset Chochmat Shlomo, Beachwood, OH"; $lat = 41.4939407; $long = -81.516709; $elev = 0; $tz = 'America/New_York'; $getdate = date('Y-m-d'); $getyear = date('Y', strtotime($getdate)); $getmonth = date('m', strtotime($getdate)); $getday = date('d', strtotime($getdate));
Enter fullscreen mode Exit fullscreen mode

Next, we’re going to create a location object, and use that location object to create a calendar object set to an equinox day (in this case March 20).

$location = new GeoLocation($locname, $lat, $long, $elev, $tz); $eqzmanim = new ComplexZmanimCalendar($location, $getyear, '3', '20');
Enter fullscreen mode Exit fullscreen mode

Get sunset for that day, along with the time the sun is 3.86 degrees below the horizon

$eqsunset = $eqzmanim->getsunset(); $eqtzeit = $eqzmanim->getSunsetOffsetByDegrees(90+3.86);
Enter fullscreen mode Exit fullscreen mode

Get the number of minutes between sunset and 3.86 degrees after sunset.

$tzeitmin = number_format((float)((strtotime($eqtzeit)-strtotime($eqsunset))), 2, '.', '')/60;
Enter fullscreen mode Exit fullscreen mode

OK, now it’s time to get some calculations for TODAY’S date. We’ll create a new calendar object and grab sunrise and sunset:

$todayzmanim = new ComplexZmanimCalendar($location, $getyear, $getmonth, $getday); $sunrise = $todayzmanim->getsunrise(); $sunset = $todayzmanim->getsunset();
Enter fullscreen mode Exit fullscreen mode

Now we’ll divide the time between sunrise and sunset into 12 equal parts (a “sha’ah” in Hebrew), and then divide one sha’ah into 60 even parts. That will effectively give us the ratio of seasonal minutes to clock minutes

$stdshaamin = number_format((float)((strtotime($sunset)-strtotime($sunrise))/12)/60, 2, '.', ''); $stdzmaniot = $stdshaamin/60;
Enter fullscreen mode Exit fullscreen mode

Now we multiply the number of minutes from our equinox day times the seasonal minute ratio.

$tzeitadjustment = $tzeitmin * $stdzmaniot;
Enter fullscreen mode Exit fullscreen mode

And finally, we add that adjustment to today’s sundown (also note we have to multiply the adjustment * 60 to make the clock math work out).

$todaytzeit = date('Y-m-d G:i:s', strtotime($sunset) + $tzeitadjustment*60);
Enter fullscreen mode Exit fullscreen mode

And let’s output it to see what we get:

print("sundown: $sunset\ntzeit: $todaytzeit\nadjustment: $tzeitadjustment\n");
Enter fullscreen mode Exit fullscreen mode

For June 10, 2025, the output would look like this:

sundown: 2025-06-10 20:59:34 tzeit: 2025-06-10 21:19:59 adjustment: 20.4228
Enter fullscreen mode Exit fullscreen mode

Good Night, My Someone

Believe it or not, we’re reached the end of my “Time Data Series”. I will, of course, keep adding things as I learn them myself. But – unless you have something specific you’d like to see (which, by all means, please tell me about in the comments), I’m going to turn out the lights, take a moment to admire the stars both for their beauty and the breathtaking wonder at the complexity of their movements, and head to bed.

Thank you for coming along on this ride with me.

Top comments (0)