README

A simple PHP library for generating Crontab schedules with expressive PHP code.

Install

Install with Composer:

$ composer require garethellis/crontab-schedule-generator

Usage

I wrote this library for use with Jobby, but it could be used in any situation where you need to output a Crontab schedule with PHP.

I recommend using the included functions for expressive code.

Hourly

The Hourly class can be used to output crontab schedules to be run on an hourly basis. The hourly() function can be used to create a new instance of Hourly.

If you call hourly() by itself, you'll get a crontab schedule of "run hourly on the hour". You can specify the minutes past the hour to run at by using the at() method. This method takes either a numeric string (0-59) or one of the following text strings: on the hour, quarter past, half past or quarter to.

You can use the repeatingAt method to run a task multiple times in an hour. This method takes the same argument as at(), i.e. a numeric string (0-59) or a text string from the above list.

use function Garethellis\CrontabScheduleGenerator\hourly;

echo hourly();
//outputs "0 * * * *" (i.e. run hourly on the hour)   
   
echo hourly()->at("20");
//outputs "20 * * * *" (i.e. run hourly at twenty past the hour)   
   
echo hourly()->at("half past");
//outputs "30 * * * *" (i.e. run hourly at half past the hour)

echo hourly()->at("on the hour")->repeatingAt("quarter past")->repeatingAt("half past")->repeatingAt("quarter to");
//outputs "0,15,30,45 * * * *" (i.e. run every 15 minutes)

Daily

The Daily class can be used to output crontab schedules to be run on a daily basis. The daily() function returns a new instance of Daily.

If you call daily() by itself, you will get a crontab schedule of "run daily at midnight". You can specify a time to run using the at() method. This method takes a (string) time in 24 hour format as its only argument (e.g. "16:00").

There is also the repeatingAt() method if you would like to schedule a task to run multiple times in a day. This method takes a whole number (numeric string) as its only argument; this number represents the hour to repeat the job at. Note, this will create a schedule which repeats at the same number of minutes past the hour as whatever you specify using the at() method. It's not possible (currently) to do something like "run at 9:30, then repeat at 11:15, then repeat at "13:40".

use function Garethellis\CrontabScheduleGenerator\daily;

echo daily();
//outputs "0 0 * * *" (i.e. run daily at midnight)   
   
echo daily()->at("4");
//outputs "0 4 * * *" (i.e. run daily at 4am)   
   
echo daily()->at("15:25");
//outputs "25 15 * * *" (i.e. run daily at 3:25pm / 15:25)

echo daily()->at("9:30")->repeatingAt("10")->repeatingAt("11");
//outputs "30 9,10,11 * * *" (i.e. run daily at 9:30, 10:30 and 11:30)

Weekly

The Weekly class can be used to output crontab schedules to be run on a daily basis. The weekly() function returns a new instance of Weekly.

If you call weekly() by itself, you will get a crontab schedule for midnight Sunday. You can specify a day to run on using the on() method. This method takes a day name in English (e.g. 'Sunday') as its only argument. If you call it like this, you will get a crontab schedule set to run on that given day at midnight. You can specify a time to run in the same way as the Daily class - see above.

You can also set weekly schedules to repeat on given days using the repeatingOn() method, passing in a day name.

use function Garethellis\CrontabScheduleGenerator\weekly;

echo weekly();
//outputs "0 0 * * 0"   
   
echo weekly()->on("Friday");
//outputs "0 0 * * 4" (i.e. run every Friday at midnight)   
   
echo weekly()->on("Saturday")->at("12:10");
//outputs "10 12 * * 6" (i.e. run every Saturday at 12:10pm

echo weekly()->on("Saturday")->repeatingOn("Sunday");
//outputs "0 0 * * 0,6" (i.e. run every Saturday & Sunday at midnight)

Monthly

The Monthly class allows you to output crontab schedules to be run on a monthly basis. The monthly() function returns a new instance of Monthly.

Calling monthly() by itself will give you a crontab schedule for midnight on the first of the month. To specify a day to run on, you can use an ordinal or whole number (as a numeric string) with the on() method. You can also use the at() method in the same way as with weekly & daily.

use function Garethellis\CrontabScheduleGenerator\monthly;

echo monthly();
//outputs "0 0 1 * *"   
   
echo monthly()->on("4th");
//outputs "0 0 4 * *" (i.e. run every month on the 4th at midnight)   
   
echo monthly()->on("12th")->at("10:15");
//outputs "15 10 12 * *" (i.e. run every month on the 12th at 10:15am)

Every X minutes/Every X hours

The Interval class allows you to output crontab schedules to be run every X minutes or every X hours. This class can be instantiated using the factory function every(). Unlike the other classes in this library, this class is no good on its own, i.e. every("5") will not output anything. Instead, you have to use the minutes() and hours() methods to create instances of MinutesInterval and HoursInterval respectively. From here, usage of these classes is very similar to the above. With HoursInterval you can specify a start and stop time using the from() and until() methods.

For MinutesInterval, the interval value must be a divisor of 60 as a numeric string (i.e. 1,2,3,4,5,6,10,12,15,20,30,60).

use function Garethellis\CrontabScheduleGenerator\every`

echo every("5")->minutes();
//outputs "*/5 * * * *" (i.e. run every 5 minutes)

echo every("2")->hours();
//outputs "0 */2 * * *" (i.e. run every 2 hours on the hour)

echo every("3")->hours()->at("half past");
//outputs "30 */3 * * *" (i.e. run every 3 hours at half past the hour)

echo every("2")->hours()->from("8")->until("14");
//outputs "0 8,10,12,14 * * *" (i.e. run on the hour at 8am, 10am, 12pm and 2pm)

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ vendor/bin/phpunit

Code Style

Easily check the code style against PSR-12 Coding Standard by running:

$ vendor/bin/phpcs src/ --standard=PSR12 --report=summary

And automatically fix them with this:

$ vendor/bin/phpcbf src/ --standard=PSR12

garethellis / crontab-schedule-generator

Maintainers

Details