pause-inc/when

When

, _(*1)

Date/Calendar recursion library for PHP, _(*2)

Author: Thomas Planer, _(*3)

About

After a comprehensive search I couldn't find a PHP library which could handle recursive dates. There is: [http://phpicalendar.org/][6] however it would have been extremely difficult to extract the recursion portion of the script from the application., _(*4)

Oddly, there are extremely good date recursion libraries for both Ruby and Python:, _(*5)

Ruby: http://github.com/seejohnrun/ice_cube, _(*6)

Python: http://labix.org/python-dateutil, _(*7)

Since I couldn't find an equivalent for PHP I created When., _(*8)

Unit Tests

Tests were written in PHPUnit (http://www.phpunit.de/), _(*9)

Initial set of tests were created from the examples found within RFC5545 (http://tools.ietf.org/html/rfc5545)., _(*10)

Documentation

Initializing the class, _(*11)

$when = new Recurrence();

Once you have initialized the class you can create a recurring event by calling on the recur method, _(*12)

$when->recur(<DateTime object|valid Date string>, <yearly|monthly|weekly|daily>);

You can limit the number of dates to find by specifying a limit():, _(*13)

$when->limit(<int>);

Alternatively you can specify an end date:, _(*14)

$when->until(<DateTime object|valid Date String>);

Note: the end date does not have to match the recurring pattern., _(*15)

Note: the script will stop returning results when either the limit or the end date is met., _(*16)

More documentation to come, please take a look at the unit tests for an understanding of what the class is capable of., _(*17)

Examples (take a look at the unit tests for more examples)

The next 5 occurrences of Friday the 13th:, _(*18)

$r = new Recurrence();
$r->recur(new DateTime(), 'monthly')
  ->count(5)
  ->byday(array('FR'))
  ->bymonthday(array(13));

while($result = $r->next())
{
    echo $result->format('c') . '<br />';
}

Every four years, the first Tuesday after a Monday in November, for the next 20 years (U.S. Presidential Election day):, _(*19)

// this is the next election date
$start = new DateTime('2012-09-06');

$r = new Recurrence();
$r->recur($start, 'yearly')
  ->until($start->modify('+20 years'))
  ->interval(4)
  ->bymonth(array(11))
  ->byday(array('TU'))
  ->bymonthday(array(2,3,4,5,6,7,8));

while($result = $r->next())
{
    echo $result->format('c') . '<br />';
}

You can now pass raw RRULE's to the class:, _(*20)

$r = new Recurrence();
$r->recur('19970922T090000')->rrule('FREQ=MONTHLY;COUNT=6;BYDAY=-2MO');

while($result = $r->next())
{
    echo $result->format('c') . '<br />';
}

Warnings:, _(*21)

• If you submit a pattern which has no results the script will loop infinitely.
• If you do not specify an end date (until) or a count for your pattern you must limit the number of results within your script to avoid an infinite loop.

Contributing

If you would like to contribute please create a fork and upon making changes submit a pull request., _(*22)

Please ensure 100% pass of unit tests before submitting a pull request., _(*23)

There are 78 tests, 1410 assertions currently., _(*24)

>>>phpunit --verbose tests
PHPUnit 3.4.15 by Sebastian Bergmann.

tests
 When_Core_Tests
 ..

 When_Daily_Rrule_Test
 .....

 When_Daily_Test
 .....

 When_Iterator_Tests
 ..

 When_Monthly_Rrule_Test
 ..............

 When_Monthly_Test
 ..............

 When_Weekly_Rrule_Test
 ........

 When_Weekly_Test
 ........

 When_Rrule_Test
 ..........

 When_Yearly_Test
 ..........

Time: 2 seconds, Memory: 6.00Mb

OK (78 tests, 1410 assertions)