#TitusCrow - A Recurring Event Library
##Introduction A common problem in both business and personal lives is recurring events. Things like birthdays, bills due, compliance tasks, homework, meetings and a whole swag of things have recurring patterns.
This library has been stewing in my brain for quite some time and I decided it was time to bring this from abstract thought to concrete code.
Date calculations are painful at the best of times, and the language of recurring events can be quite complicated. There are a range of special conditions with dates that are not logical but are simply cultural or political. Things like day light savings, public holidays (federal, state, occupational, religious), seasons that are different depending on the hemisphere you live in etc all add to the complexity.
##Requirements PHP 5.3.0 or greater.
##Background This library does not attempt to solve every possible combination of recurrence, however it provides the base tools to build schedules of events that have a recurrence description. In the context of this library, this description is referenced as a 'Temporal Expression'. These temporal expressions can be combined, extended or be created from scratch to resolve the particular requirement of you recurring events.
##Terminology and Usage The following is a very quick attempt to describe the terminology used in this library with some hint at how to use the various classes. I hope to have better documentation with examples and tutorials at a later date. Also be sure to read the API documentation.
###What Makes a Schedule
A schedule is simply a collection of events that occur at various points in
time. We represent schedules with the TCSchedule class.
###What Makes an Event
An event is something of interest that happens at various points in time. We
represent events by implementing the ITCEvent interface. A simple concrete
class is provided with the TCSimpleEvent class.
###How To Represent Dates
Dates are represented with the TCDate class. Time is not stored in these
objects, just the date.
###How To Specify Recurring Dates
We use Temporal Expressions to describe what dates a particular event occurs
on. The language of date recurrence is quite complex, so we use the Expression
pattern that is defined by the ITCTemporalExpression interface. Temporal
expressions can be easily extended to handle new types of recurrence as the
need arrises.
There are 3 powerful set temporal expressions that allow complex combinations of other temporal expressions. These set expressions provide:
- Union
TCUnionTemporalExpression - Intersection
TCIntersectionTemporalExpression - Differences
TCDifferenceTemporalExpression
##Interface and Classes
###Schedule This is the main class used to manage a schedule.
Create a schedule object for the subject which can say which days an event occurs
###Schedule Element Schedule Element is a map between an event and a temporal expression. Temporal expression has an individual instance method to determine if dates match.
###Temporal Expressions You need a way to express how when an event occurs.
###Set Expressions You need to represent combinations of temporal expressions.
Set combinations exist for union, intersection and difference.