New class: Hazaar\Cron

I'm happy to introduce a new class for your scheduling pleasure.  The Hazaar\Cron class!  This class can be used to parse cron strings and compute schedules.  It can parse a given string with a schedule specification in cron format.  The class can compute the last and the next schedule times relative to a given time.

Why?

Schedules are hard, and doing them right is even harder and it generally sucks trying to get them right. One system that seems to do them quite well is the Unix Cron program, so we have used that as our scheduling format of choice. 

What is Cron?

If you don't know cron, (achem, windows users) it is the name of program that enables Unix users to execute commands or scripts (groups of commands) automatically at a specified time/date. These dates and times are derived from a cron schedule which is just a string in a specific format. 
In a nut shell, the cron string is a series of 5 fields, each separated by a space. To blatantly rip off wikipedia, here is what a schedule string looks like:
* * * * *
│ │ │ │ │
│ │ │ │ │
│ │ │ │ └──── day of week (0 - 6) (0 to 6 are Sunday to Saturday, or use names; 7 is Sunday, the same as 0)
│ │ │ └────── month (1 - 12)
│ │ └──────── day of month (1 - 31)
│ └────────── hour (0 - 23)
└──────────── min (0 - 59)
So for example: 
0 10 * * *
would result in a date/time generated for 10am every day. 

Documentation

The API documentation is up to date so checkout the Hazaar\Cron class page for more info. 
There's an article called Newbie: Intro to cron you should read if you want to know more. There's also a good explanation on Wikipedia about cron, what it can do and it's schedule format. 
Another good website I use regularly when messing with cron is Cron Checker which will check your cron schedule strings by returning to you a human readable version. 
The Hazaar\Cron class does not actually execute any code or programs. It is simply a tool for working with a cron schedule string and generating datetime values. If you want to schedule a program to execute, look at Delayed Execution

How to use it?

It's quite simple. Just instantiate a new Hazaar\Cron object with the schedule string as it's only parameter. Then you just call call the _getNextOccurrence()_ method and it will return the next datetime in the schedule.
$cron = new \Hazaar\Cron('0,30 9-17 * * 1-5');
$next = $cron->getNextOccurrence();
echo date('Y-m-d H:i', $next);
This will echo the next occurrence from the schedule which should return dates and times for every 0th and 30th minute between 9am and 5pm, Monday to Friday. 
You can also specify the time after which you want to find the next occurrence. Calling getNextOccurrence($time) where $time is a datetime value, will use $time as the reference point and return the next datetime in the schedule after it.
$cron = new \Hazaar\Cron('0,30 9-17 * * 1-5');
$next = $cron->getNextOccurrence(mktime(17,30));
echo date('Y-m-d H:i', $next);
This will give the next date/time in the schedule that come after 5:30pm. In this case that would be 9am the next day.
You can also call getLastOccurrence() which is pretty much the same except it returns the last scheduled datetime before the current (or specified) datetime.
$cron = new \Hazaar\Cron('0,30 9-17 * * 1-5');
$next = $cron->getLastOccurrence(strtotime('2014-10-15 15,13'));
echo date('Y-m-d H:i', $next);
This will output the last scheduled time as exactly 2014-10-15 15:00.

Leave a reply

Fill in your details below or log in: