As part of our recent Balboa Park Online Collaborative (BPOC) project, we needed to push Drupal's date and time handling further than we'd ever seen it pushed. For those who haven't had to deal with it before, date handling is a nightmare. That's not a Drupal problem, but a calendaring problem. Date and time logic is incredibly complex once timezones, date-without-time events, and repeating events are added to the mix. What's more, there is always the ever-present feature request for "this event happens every Tuesday and Thursday this year at both 3 and 6 p.m., except for Thanksgiving and the 4th of July and this one other day where there's another event going on instead". Having implemented a number of calendaring systems of varying complexity, I've usually commented in the past, "Date handling sucks. It just sucks less in Drupal."

For BPOC, however, we had the opportunity to really do it right. BPOC really does have events like that, and we needed a clean, portable way to support them. Fortunately, there is an existing standard for such date logic that we were able to bring into Drupal: iCal.

iCal itself is a beast of a format. Not to be confused with the Apple application of the same name, it is a text-based format that was a compromise between a handful of existing, competing formats for defining complex event rules. As such, it offers just a bit too much flexibility to be called "easy to use", despite being the industry standard. We needed a good way to round-trip data from iCal strings to data structures in Drupal to all of the different instances an iCal recurrence rule would generate. No such code existed in one place, but we were able to assemble a solution.

There appears to be a severe shortage of good, complete, maintained iCal solutions for PHP. We found several partial attempts at libraries that stopped development when they got to the hard parts and a few Web calendar programs that used iCal internally, but didn't offer a separable library or API for our usage. Eventually we settled on iCalCreator, a partially-abandoned PHP 4-era library that handled more of the iCal specification than anything else we could find, but didn't hide iCal's warts very well. It actually did almost all of what we needed with one exception: It cannot process RRULEs, the iCal way of defining when and how an event will repeat, to generate each date instance we need. In fact, we found exactly one implementation of that logic anywhere: In Drupal's very own date_repeat module, part of the Date suite. How about that?

Enter the iCal module, which leverages the Libraries API and Autoload modules to stitch together iCalCreator and date_repeat and provide more solid Drupal integration. It also makes use of PHP 5's powerful iterators and DateTime object handling (which is, actually, really good) to provide a good, clean, predictable API, at least for the parts of the iCal spec that we needed.

Now that we could process iCal, what do we do with it? While the date_repeat module already exists, it was insufficient for our needs. It didn't allow each instance to have custom data and we expected that CCK wouldn't scale well in practice to having 500+ instances of a single field. In order to support both of those requirements we had only one viable alternative: Every instance of a repeating event is its own node, and refers back to an Event node that ties them all together and holds the original iCal information. That would mean thousands of nodes, but that's OK. Drupal can handle thousands of nodes.

That required creating three more modules: icalfield, icalreferencefield, and inheritedformatter.

• icalfield is a field that holds an iCal fragment, specifically a "VEVENT", or event record.
• icalreferencefield is, as the name implies, a nodereference-like field module that refers not to a node, but to a specific value within an iCal field on another node. That is, it refers to the recurrence rule that spawned it.
• inheritedformatter is an odd little formatter that lets an empty field pull in the value from the same field on a different node, "inheriting" its value, essentially. It works with both nodereference and icalreference fields and has hooks to add more.

Now, when an Event node, containing an icalfield, is saved, we use the iCal module to generate the appropriate Instance nodes along with it, each with a single-value date field representing that specific instance, all of them referring back to the Event node. Those we can then show in calendar views, edit individually, rate, sign up for, comment on, or anything else that you can do with nodes.

There's only one problem: Do we really want to generate the next 3 years worth of daily events all at once? Probably not, especially when iCal lets you specify events that repeat forever. Drupal can't handle Aleph-Omega nodes. Instead, we only generate out up to X instance nodes at a time, up to Y time in the future. (Both X and Y are configurable.) Then we keep a list of all "active" Event nodes and periodically toss them into a queue. That's right, the Drupal Queue module, which is a backport of Drupal 7's new queuing system. We then process each event again, generating any new instances. Over time, we will always have up to X instances Y time in the future generated. Because we're using the queuing system it should scale almost indefinitely for calendar-heavy sites.

And there you have it: a single place to edit arbitrarily complex repeating event rules, but a separate node for each instance with all the power that it brings, and it scales.

The next step, of course, is to clean up that iCal part. PHP needs a really solid, modern PHP 5-based iCal library, and we'd love to be able to move over to that rather than stitching together various different bits and pieces. If you're interested in working on or funding general PHP date handling work, let us know. We've been inside iCal and lived to tell about it.