Time Data Series: The Rest of the Story

Time Data Series: The Rest of the Story - AdatoSystems

It’s been a while since I wrote about PHP Zmanim – the work I’ve done with it and the things I’ve learned while implementing it. But despite the delay, I always intended to continue the conversation. That’s what we’re doing today 

In my first post I explained how to install and get started with the PHP Zmanim library. Then in the next post I dug into calculating more complex times, and the real power of the tool – applying the most common Rabbinic opinions for various zmanim. I’m picking up where I left off with minimal overlap, so if you need to take a minute to get back up to speed,  I’ve linked to those previous posts.

The goal today is to explore uses of PHP Zmanim that move beyond the relatively straightforward use of the library. That includes:

• Taking a standard time and adjusting it for synagogue specific use cases (“Mincha starts 25 minutes before Shkia each day”).
• Using PHP Zmanim library functions and methods that provide non-time calculations – such as the weekly Torah Portion, the Hebrew date, and whether a specified date is a holiday (like Rosh Chodesh or Sukkot).

Acknowledgements

Once again need to begin by stating my gratitude to the folks who made all of this possible. Foremost among a long list of names is Zachary Weixelbaum, the maintainer of the PHP Zmanim library itself; and Eliyahu Hershfeld: creator of the Kosher Java library upon which PHP Zmanim is based.

A quick refresher

When we left off, we had a solid basic php script that:

• sets variables for the location (in latitude/longitude), along with the time zone and elevation.
• Sets the date
• creates a php zmanim object from those variables
• uses the built-in methods to calculate the time for anything from sunrise to mincha to tzeit hakochavim

It looked like this:

<?php
require 'vendor/autoload.php';
use PhpZmanim\Zmanim;
use PhpZmanim\Calendar\ComplexZmanimCalendar;
use PhpZmanim\Geo\GeoLocation;
# Set variables:
$locname = "Beit Knesset Chochmat Shlomo, Beachwood, OH";
$lat = 41.4939407;
$long = -81.516709;
$elev = 0;
$tz = 'America/New_York';
$getyear = 2024;
$getday = 20;
$getmonth = 12;
$testzmanim = Zmanim::create($getyear, $getmonth, $getday, $locname, $lat, $long, $elev, $tz);
$sunrise = $testzmanim->sunrise;
echo "$sunrise\n";
?>

But sunrise is just the beginning. Using any of the built-in calculations (which are described on the github readme page), you can pull a wide variety of times. For example, to get Mincha Gedola using a specific Rabbinic opinion, I could include:

$gedolah = $zmanim->minchaGedola16Point1Degrees

In the last blog I also covered ways to use PHP Zmanim’s format method to make the output more readable:

$gedolah = $gedolah->format('g:i a');

“Salt to taste” – adjusting times

For those who don’t spend a lot of time in synagogue (no blame, no shame, you’re still welcome here) it may not be obvious, but – despite the name of the zman – very few organizations pray Mincha (afternoon prayers) at Mincha Ketana, Mincha Gedola, or Plag haMincha.

In fact, a lot of the work with regard to calculating times has less to do with the straight “what time is Mincha Gedola?” and more with “how late in the day can we reasonably schedule Mincha so that everyone has time to get here after work; but not SO late that nobody comes because they’ll miss dinner?”

If that’s too theoretical, allow me to share the logical jenga puzzle my synagogue considers when setting up the weekly schedule:

• Friday night candle lighting: Shkia (sunset) minus 18 minutes
• Summer Friday Mincha: Plag haMincha (using “plagHaminchaAteretTorah”) minus 20 minutes
• Winter Friday Mincha: Shkia (sunset) minus 22 minutes
• Saturday Mincha: Shkia minus 40 minutes
• Saturday Ma’ariv: Shkia plus 50 minutes
• Saturday end of Shabbat: Shkia plus 45 minutes
• Weekday Mincha: find the earliest shkia for the week, then subtract 17 minutes

While all the other times I covered in earlier blogs still matter, hopefully you are starting to realize that they matter less often than one might expect.

So how DO you take a time (like shkia/sunset) and then add or subtract minutes? We’ll start off with the same script we had before:

<?php
require 'vendor/autoload.php';
use PhpZmanim\Zmanim;
use PhpZmanim\Calendar\ComplexZmanimCalendar;
use PhpZmanim\Geo\GeoLocation;
# Set variables:
$locname = "Beit Knesset Chochmat Shlomo, Beachwood, OH";
$lat = 41.4939407;
$long = -81.516709;
$elev = 0;
$tz = 'America/New_York';
$getyear = 2024;
$getday = 20;
$getmonth = 12;
$testzmanim = Zmanim::create($getyear, $getmonth, $getday, $locname, $lat, $long, $elev, $tz);

To that we’ll add the code to get sunset:

$sunset = $zmanim->sunset;

and then we’ll subtract 18 minutes to get candle lighting time:

$candles = date('g:i a', strtotime($sunset . " -18 minutes"));

That’s right. You just use php’s own string to time function. I’m sorry if I kept you in suspense. But it’s really just that easy.

What’s the Torah portion? What’s the Hebrew date? When is Rosh Chodesh?

(…and other essential but vexing questions often asked in and around your synagogue.)

Along with date calculations, the KosherJava library (and therefore the PHP Zmanim library) have methods and functions to quickly provide information like the ones asked above.

The first thing to understand is that the PHP Zmanim object we’ve been working with so far has been a Zmanim object – an object that has a set of specific times for a particular date. For things involving the dates themselves, we instantiate a  jewishCalendar object. The good news is that it’s MUCH easier to create. All you need is the year, month, and day.

<?php
require 'vendor/autoload.php';
use PhpZmanim\Zmanim;
use PhpZmanim\Calendar\ComplexZmanimCalendar;
use PhpZmanim\Geo\GeoLocation;
# Set variables:
$getyear = 2024;
$getday = 21;
$getmonth = 09;
$jewishCalendar = Zmanim::jewishCalendar(Carbon::createFromDate($getyear, $getmonth, $getday));

We now have a jewishCalendar object to work with and can use methods similar to the ones we found for times. For example: Presuming the date we selected was a Saturday, we can get the Torah portion:

$format = Zmanim::format();
$parshaeng = json_decode('"' . $format->formatParsha($jewishCalendar) . '"');

(ignore the $format setting for now. We’ll dig into it in just a bit).

If you ran that code, $parshaeng would give you:

Parshas Ki Savo

You’ll notice we didn’t need to provide latitude, longitude, time zone, etc. I cannot stress enough that this capability alone – the ability to get dates, Torah portions, and more – makes the PHP Zmanim library useful all on its own, even without the time calculations. 

Can I get that in Hebrew?

The Torah Portion? Of course! This is where the $format line comes in. 

First, an explanation of what it is: It’s a method that modifies objects like Zmanim and jewishCalendar, setting the display and output options.  Setting Zmanim::format() without any other information defaults to English. But then you can tell the system you want Hebrew with this additional line:

$format->setHebrewFormat(true)

Now if you run the same json_decode(‘”‘ . $format->formatParsha($jewishCalendar) . ‘”‘) line, you’d get:

כי תבוא

Putting it all together:

<?php
require 'vendor/autoload.php';
use PhpZmanim\Zmanim;
use PhpZmanim\Calendar\ComplexZmanimCalendar;
use PhpZmanim\Geo\GeoLocation;
# Set variables:
$getyear = 2024;
$getday = 21;
$getmonth = 09;
$jewishCalendar = Zmanim::jewishCalendar(Carbon::createFromDate($getyear, $getmonth, $getday));
$format = Zmanim::format();
$parshaeng = json_decode('"' . $format->formatParsha($jewishCalendar) . '"');
$format->setHebrewFormat(true);
$parshaheb = json_decode('"' . $format->formatParsha($jewishCalendar) . '"');
echo "$parshaheb - $parshaeng\n";

This would display: כי תבוא – Ki Savo

What day is it?

More specifically, what HEBREW day is it?

Like the previous example, we start out with a jewishCalendar and a format object

$jewishCalendar = Zmanim::jewishCalendar(Carbon::createFromDate($theyear, $themonth, $theday));
$format = Zmanim::format();

Then we add the same line to set the format to Hebrew.

$format->setHebrewFormat(true);

And finally (and fairly simply) we ask for a straight calendar object output:

$zmandate = json_decode('"' . $format->format($jewishCalendar) . '"');

That’s literally all you need. The result is something like this:

17 Elul, 5784

Yes, even though we specified setHebrewFormat it came out in English.

Can I get that in ACTUAL Hebrew?

In order to get the Hebrew date to show up fully in Hebrew – both words and letters – we invoke a slightly different method called, appropriately enough, HebrewDateFormatter. Presuming (once again) you set up your initial variables and created a jewishCalendar object, the code to output a Hebrew language date would be:

$hebformat = HebrewDateFormatter::create();
$hebformat->setHebrewFormat(true);
$hebdate = json_decode('"' . $hebformat->format($jewishCalendar) . '"');
print("Hebrew date: $hebdate\n");

which would give you:

Hebrew date: י״ח אלול תשפ״ד

Is today the day?

Sometimes you need to check if a specific date is… well, a specific day. Like Rosh Chodesh (the new month) or part of a multi-day holiday (like Sukkot).

It turns out that PHP Zmanim method makes this very simple. Presuming you’ve started off in the same way as the other examples,

Once you’ve set up the jewishCalendar object it’s as simple as

$jewishCalendar->isRoshHashana();
$jewishCalendar->isSuccos(); 

If the date matches the holiday, it will return “true” and you can proceed with whatever logic or process you want, such as displaying the date (or not).

So what’s next?

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.

In the meanwhile, if there’s something else you’d like to see me cover; or if you have questions, corrections, or kudos, feel free to leave them in the comments below.