Parsing Google Calendar - Recurring Events

Dealing with normal events in a Google Calendar feed is not too tough. Looping through each event and pulling the basic chunks of information (title, description, times) is easy once you hook up the correct namespacing to the nodes. Once you get into recurring events, though, things get more difficult. Even Google seems to take the easy way out here and just throw all the repeating rules in iCal format, a solid blob of text in one of the XML elements. They leave it up to the developer to plod through the iCal, pull out the rules, and explode out each instance of the event.

So, first off, you need to pull out the data. Working off the groundwork in my earlier post, some modifications will need to be made to the loop through each entry. There is no start_time or end_time nodes for recurring events, so we should also account for that missing piece of data.

$events = array();
foreach($feed_xml->entry as $event)
{
	$gd_nodes = $event->children('http://schemas.google.com/g/2005'); // found in attribute of feed node
	$gcal_nodes = $event->children('http://schemas.google.com/gCal/2005'); // found in attribute of feed node
	
	$id = (string) $gcal_nodes->uid->attributes()->value;
	$title = (string) $event->title;
	$description = (string) $event->content;
	$location = (string) $gd_nodes->where->attributes()->valueString;
	
	/* modified code */
	if(isset($gd_nodes->recurrence))
	{
		$ical = (string) $gd_nodes->recurrence;
		$ical = explode("\n", $ical);
		$ical = array_slice($ical, 0, 3);
		
		$start_time = explode(':', $ical[0]);
		$start_time = array_pop($start_time);
		
		$end_time = explode(':', $ical[1]);
		$end_time = array_pop($end_time);
		
		$repeating_rule = $ical[2];
	}
	else
	{
		$start_time = (string) $gd_nodes->when->attributes()->startTime;
		$end_time = (string) $gd_nodes->when->attributes()->endTime;
	}
	/* end modified piece */
}

There are some annoying pieces here. iCal can be kind of messy, delimited with line breaks, colons, semicolons, and equal signs in different places, though every Google Calendar example has seemed fairly standard. You will need the first three rows: one for start_time, one for end_time, and one for the repeating rule. Also, since iCal defines timezones differently than the nodes in the feed, timezones will not match up. You may need to grab the timezone from the first two rows to make sure all your dates are lined up. Below is an example of what we're dealing with in the gd:recurrence node.

DTSTART;TZID=America/Chicago:20130610T080000
DTEND;TZID=America/Chicago:20130610T090000
RRULE:FREQ=DAILY;COUNT=5
BEGIN:VTIMEZONE
TZID:America/Chicago
X-LIC-LOCATION:America/Chicago
BEGIN:DAYLIGHT
TZOFFSETFROM:-0600
TZOFFSETTO:-0500
TZNAME:CDT
DTSTART:19700308T020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
END:DAYLIGHT
BEGIN:STANDARD
TZOFFSETFROM:-0500
TZOFFSETTO:-0600
TZNAME:CST
DTSTART:19701101T020000
RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
END:STANDARD
END:VTIMEZONE

Again, the only important lines are the first three - the rest are for timezones and daylight savings time and whatnot, which hopefully you won't need to worry about (hopefully).

So this is great, but what about getting a different instance for each part of a repeating event? All that the above script does is grab the start and end time of the root occasion. There are a lot of repeating options that Google Calendar has, each with their own special quirks, and we need to worry about each one.

Google Calendar Repeating Option

Daily
 - every n days
 - start date
 - ends never, after n occurrences, or on a certain date
 - example: RRULE:FREQ=DAILY;COUNT=5
Weekday
 - start date
 - ends never, after n occurrences, or on a certain date
 - example: RRULE:FREQ=WEEKLY;UNTIL=20130715T093000Z;BYDAY=MO,TU,WE,TH,FR
Monday, Wednesday, and Friday
 - start date
 - ends never, after n occurrences, or on a certain date
 - example: RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
Tuesday, Thursday
 - start date
 - ends never, after n occurrences, or on a certain date
 - example: RRULE:FREQ=WEEKLY;COUNT=25;BYDAY=TU,TH
Weekly
 - every n weeks
 - multiple days per week
 - start date
 - ends never, after n occurrences, or on a certain date
 - example: RRULE:FREQ=WEEKLY;UNTIL=20130716T093000Z;BYDAY=SU,MO,TU
Monthly
 - every n months
 - day of month v day of week
 - start date
 - ends never, after n occurrences, or on a certain date
 - example: RRULE:FREQ=MONTHLY;INTERVAL=3;BYMONTHDAY=11
Yearly
 - every n years
 - start date
 - ends never, after n occurrences, or on a certain date
 - example: RRULE:FREQ=YEARLY;UNTIL=20180611T093000Z
 

Even though the number of options available are a bit overwhelming you can start to see some patterns come out. The same key names are used for similar fields across the different options and some of the weekly repeating options use the same exact format.

So, to deal with these, we first need to parse out the fields. After the different variables are in a format that is easier to work with there are several ways to 'explode' each event, especially since the options are similar across them. Instead of being all tricksy and abstract we could just handle each option separately. Let's do that.

$events = array();
foreach($feed_xml->entry as $event)
{
	$gd_nodes = $event->children('http://schemas.google.com/g/2005'); // found in attribute of feed node
	$gcal_nodes = $event->children('http://schemas.google.com/gCal/2005'); // found in attribute of feed node
	
	$id = (string) $gcal_nodes->uid->attributes()->value;
	$title = (string) $event->title;
	$description = (string) $event->content;
	$location = (string) $gd_nodes->where->attributes()->valueString;
	
	$repeat_array = array();
	if(isset($gd_nodes->recurrence))
	{
		$ical = (string) $gd_nodes->recurrence;
		$ical = explode("\n", $ical);
		$ical = array_slice($ical, 0, 3);
		
		$start_time = explode(':', $ical[0]);
		$start_time = array_pop($start_time);
		
		$end_time = explode(':', $ical[1]);
		$end_time = array_pop($end_time);
		
		$repeating_rule = explode(':', $ical[2]);
		$repeating_rule = array_pop($repeating_rule);
		$repeating_rule = explode(';', $repeating_rule);
		
		$repeat_array = array();
		foreach($repeating_rule as $row)
		{
			list($key, $value) = explode('=', $row);
			
			if($key == 'BYDAY')
				$value = explode(',', $value);
			
			$repeat_array[$key] = $value;
		}
	}
	else
	{
		$start_time = (string) $gd_nodes->when->attributes()->startTime;
		$end_time = (string) $gd_nodes->when->attributes()->endTime;
	}
	
	/* start modified code */
	$events[] = array(
		'id' => $id,
		'title' => $title,
		'description' => $description,
		'location' => $location,
		'start_time' => strtotime($start_time),
		'end_time' => strtotime($end_time));
	
	if(!empty($repeat_array))
	{
		if(isset($repeat_array['UNTIL']))
			$limit = array('UNTIL' => $repeat_array['UNTIL']);
		else if(isset($repeat_array['COUNT']))
			$limit = array('COUNT' => $repeat_array['COUNT']);
		else
			$limit = array('COUNT' => $repeating_event_limit); // too avoid infinite arrays
		
		$timestamp = strtotime($start_time);
		$elapsed_time = strtotime($end_time) - $timestamp;
		$count = 1;
		
		while(TRUE) // with multiple ending conditions I found this the best way to loop
		{
			switch($repeat_array['FREQ'])
			{
				case 'DAILY' :
					$interval = isset($repeat_array['INTERVAL']) ? $repeat_array['INTERVAL'] : 1;
					$timestamp += 24 * 60 * 60 * $interval;
					break;
				case 'WEEKLY' :
					unset($next_day);
					$day = date('w', $timestamp);
					
					foreach($repeat_array['BYDAY'] as $repeat_day)
					{
						$repeat_day_index = array_search($repeat_day, $weekday_short_array);
						if($repeat_day_index > $day)
						{
							$next_day = $repeat_day_index;
							break;
						}
					}
					
					if(isset($next_day))
						$timestamp += 24 * 60 * 60 * ($next_day - $day);
					else
					{
						$next_day = array_search($repeat_array['BYDAY'][0], $weekday_short_array);
						$timestamp += 24 * 60 * 60 * ($next_day + 7 - $day);
					}
					break;
				case 'MONTHLY' :
					$interval = isset($repeat_array['INTERVAL']) ? $repeat_array['INTERVAL'] : 1;
					if(isset($repeat_array['BYMONTHDAY']))
						$timestamp = strtotime(date('c', $timestamp) . " +{$interval} month");
					else
					{
						$by_day = $repeat_array['BYDAY'][0];
						
						$by_day_week_number = substr($by_day, 0, 1);
						$ordinal = $ordinal_array[$by_day_week_number];
						
						$by_day_weekday = substr($by_day, 1);
						$day_index = array_search($by_day_weekday, $weekday_short_array);
						$dayname = $weekday_medium_array[$day_index];
						
						$timestamp = strtotime(date('c', $timestamp) . " +{$interval} month");
						$month = date('F', $timestamp);
						$year = date('Y', $timestamp);
						
						$relative_timestamp = "{$ordinal} {$dayname} of {$month} {$year}";
						$timestamp = strtotime($relative_timestamp);
					}
					break;
				case 'YEARLY' :
					$interval = isset($repeat_array['INTERVAL']) ? $repeat_array['INTERVAL'] : 1;
					$timestamp = strtotime(date('c', $timestamp) . " +{$interval} year");
					break;
			}
			$count++;
			
			if(
				(isset($limit['UNTIL']) && $timestamp > strtotime($limit['UNTIL'])) ||
				(isset($limit['COUNT']) && $count > $limit['COUNT']))
			{
				break;
			}
			
			$events[] = array(
				'id' => $id,
				'title' => $title,
				'description' => $description,
				'location' => $location,
				'start_time' => date('c', $timestamp),
				'end_time' => $timestamp + $elapsed_time);
		}
	}
	/* end modified code */
}

While it isn't too tricky there is a lot of date manipulation that could go wrong during certain cases, like leap years and such. One thing that I had to remind myself several times is that this code is not calculating the 'correct' recurring dates but is trying to replicate Google Calendar processing as close as possible. After all, if you make a change to the source you expect it to flow exactly to any dependant sites, regardless of how either one is reading the data.

I did have to add some configuration information for some of the logic near the top of my script…

$repeating_event_limit = 300;
$weekday_short_array = array('SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA');
$weekday_medium_array = array('Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat');
$ordinal_array = array('zero', 'first', 'second', 'third', 'fourth', 'fifth');

And that pretty much does it! Again, it is important to test different cases - this script worked just fine for the scope of my project and the different tests we threw at it and may need some tweaks to work for yours. Also, it does not look at modified or deleted events from a repeating series. This is a nasty side effect to the way Google passes on the information, actually creating new events with status 'deleted' to mark holes in a recurring series. Just take a look at the eventstatus node if this is a concern.