Web Cash

dateRange is a fairly simple php class. It’s main function is to create a range of dates - allowing you to quickly check to see if a given date is within that range.

You can view the source code in text format. Or read on for a description of how this can be used.

Components of the dateRange Class

The dateRange class has four main properties:

• $start - the start date
• $end - the end date
• $name - a display name for your daterange
• $exceptions - a list of dates that are considered “out of the range”

Here’s an example of how to create an instance of the dateRange class…

$range = new dateRange("1 January 2008",
  "31 December 2008", "Year of 2008");

Formatting Dates for Use with dateRange

The class stores the start and end dates as Unix timestamps, but it is designed to take either a timestamp or a formatted date string as input. In this case, I passed a string to the constructor and it automatically converted it to a timestamp.

It uses the php strtotime() function to convert from a string to a timestamp, so you’re free to use any strings that you know that function can normally convert. The simplest format is the one I used - “Day Month Year”).

Optional Parameters for Constructor

If you don’t pass a name to the constructor, it will have a default name of “Random Date Range.”

You can pass either a single date or an array of dates (again, timestamps or strings) for the fourth parameter ($exclusions). If you pass no dates, then there are no exclusions - and every date from $start to $end is considered in the range.

Public Methods

The class is designed with its properties private. Therefore you need to use the methods to access their values.

• getName() - returns the name of the dateRange
• getStart() - returns the start date of the dateRange
• getEnd() - returns the end date of the dateRange
• addExclusion($exclusion) - adds the values in $exclusion to the dateRange’s own $exclusion array. This value can either be a single date or an array of dates. It can also be formatted as Unix timestamps or date strings.
• inRange($date) - this checks to see if a given date is in the range and not excluded. Returns true if it’s in the range, returns false if not.

Private Methods

The class includes one private method at the moment - isExcluded. This cycles through the $exclusions array and checks to see if a given date is excluded. It’s used in the public inRange($date) method.

Possible Uses

Well, heck, isn’t that your job?

Here are a few things you might use this for:

• Form validation. If your user is supposed to input a date, check to see if it’s in the range you want it to be.
• Convenience function for a calendar script. You could create a number of dateRanges in your calendar and use this to see if events fall within a certain range.
• Detect the current season. Create a dateRange for each season, and then compare the current time() to see what the current season is.

Sample Code Showing How to Use It

Here’s a little sample php to show you how to implement this…

$range = new dateRange("21 March 2008",
  "21 June 2008", "Spring 08");

//  This will be true
if ($range->inRange("15 April 2008"))
  echo "Tax day is in the range "
    . $range->getName();

//  This will be untrue
if (!($range->inRange("18 Feburary 2008")))
  echo "My b-day is not in the range "
    . $range->getName();

//  Tax day is evil, so we're going to take it out of Spring
$range->addExclusion("15 April 2008");
if (!($range->inRange("15 April 2008")))
  echo "Tax day is not in the range "
    . $range->getName();

If you’d like to see this script extended, let me know what you think would be useful. Also leave a comment if you run into any errors or problems. Can’t guarantee that I can help you… but if I have some free time I will.