Time Data Series: Written In Our Stars

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;

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);

Finally, the code that calculates and displays the results:

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

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");
?>

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));

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');

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);

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

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

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();

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;

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

$tzeitadjustment = $tzeitmin * $stdzmaniot;

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);

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

print("sundown: $sunset\ntzeit: $todaytzeit\nadjustment: $tzeitadjustment\n");

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

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.