Introduction

Introduction

PEAR::Calendar is an package for generating Calendars as data structures. It does not render content or rely on any underlying data store, allowing it to be applied to many problem domains. At the same time it provides an easy to use API that makes rendering, for example, an HTML calendar very easy, while making it possible to "connect" the calendar with your data store.

PEAR::Calendar was developed as a result of finding no alternatives out there in PHP. There are numerous public domain calendar utilities / classes out there but all are tied to a specific output format (typically HTML with limited ability to customize without re-writing code) and often dependent on pre-built data structures stored in a database (read MySQL). This poses significant restrictions on the problem domains they can be applied to. By contrast PEAR::Calendar focuses on eliminating the math from the task of generating a calendar, allowing the end user to simply iterate over a prepared data structure.

Some of the benefits / features of PEAR::Calendar include;

• You can render whatever output you like (e.g. (X)HTML, WML, SOAP, XML-RPC, command line ASCII or whatever).

• Generating a calendar is much like looping through the results of a database query.

• Representations of all "date objects" from a Year down to a Second (e.g. you can equally render a complete yearly calendar with months and days or a "Weekly / Daily Diary")

• Allows "tabular" calendars to be generated easily.

• Any date can be easily validated (is 29th Feb 2003 valid?).

• Performs well despite number crunching and object oriented API.

• Calendars can be easily navigated (e.g. providing a link from 1st Jan 2004 to 31st Dec 2003 is no problem).

• It returns numeric values for all operations, meaning you are not tied to using, say, English names for months. Typically you would generate these yourself with PHP functions like strftime() and setlocale().

• Representations of a date can be obtained as a human readable number or in the form of a timestamp (e.g. Unix Timestamp), depending on the calendar engine you are using.

• You can attach your own functionality to the calendar by creating Decorators.

• Allows you to write layered, N-Tier applications.

• The calendar "calculation engine" is abstracted meaning you are not tied to a Gregorian calendar - you could write a Tolkien calendar should you wish. Currently "engines" based on Unixtimestamps (the default) and PEAR::Date have been implemented.

Example 34-1. A Simple Example require_once 'Calendar/Month.php'; $Month = new Calendar_Month(2003, 10); // October 2003 $Month->build(); // Build the days in the month // Loop through the days... while ($Day = $Month->fetch()) { echo $Day->thisDay().'<br />'; }

Note: there are numerous and extensive examples provided with the PEAR::Calendar package file.