Package Overview

Package Overview

When working with PEAR::Calendar, there are a total of 12 (public) classes available for you to use, depending on the particular problem you are trying to solve. They can be grouped in date classes, tabular date classes, validation classes and decorators.

Date Classes

Providing representations of all basic human date units. All are subclasses of Calendar so provide the methods defined there.

• Calendar_Year - represents a year and can build Calendar_Month, Calendar_Month_Weekdays and Calendar_Month_Weeks objects.

  Include with

  require_once 'Calendar/Year.php';

  .

• Calendar_Month - represents a month and can build Calendar_Day objects.

  Include with

  require_once 'Calendar/Month.php';

  .

• Calendar_Day - represents a day and can build Calendar_Hour objects.

  Include with

  require_once 'Calendar/Day.php';

  .

• Calendar_Hour - represents a hour and can build Calendar_Minute objects.

  Include with

  require_once 'Calendar/Hour.php';

  .

• Calendar_Minute - represents a minute and can build Calendar_Second objects.

  Include with

  require_once 'Calendar/Minute.php';

  .

• Calendar_Second - represents a second but cannot build anything.

  Include with

  require_once 'Calendar/Second.php';

  .

Tabular Date Classes

Designed for building calendars in tabular format. All are subclasses of Calendar so provide the methods defined there.

• Calendar_Month_Weekdays - builds Calendar_Day objects setting the isFirst(), isLast() and isEmpty() states, to display a month in tabular form.

  Include with

  require_once 'Calendar/Month/Weekdays.php';

  .

• Calendar_Month_Weeks - builds Calendar_Week objects, representing a month in terms of the tabular weeks it contains (see FAQ for what a week represents).

  Include with

  require_once 'Calendar/Month/Weeks.php';

  .

• Calendar_Week - builds a collection of seven Calendar_Day objects. If extended by a Calendar_Month_Weeks object, it represents a tabular week in a month and it sets the isEmpty() state for the appropriate days, if necessary.

  Include with

  require_once 'Calendar/Week.php';

  .

Validation Classes

Used to validate dates. Calendar provides the methods isValid() to perform a simple check on any date and getValidator() to return an instance of Calendar_Validator for fine grained validation.

• Calendar_Validator - is not instantiated by your code directly (you need need specifically include / create it) but instead returned from the Calendar::getValidator() method you can call on any subclass of Calendar. It is used to provide fine grained validation of a date to find out exactly what's wrong with it (for simple validation just call isValid() on any Date object or Tabular Date object, to know if it was created with valid values.

• Calendar_Validation_Error - represents a validation error, providing methods to determine what went wrong. Available methods are getUnit() (e.g. returns Year or Month), getValue() (the value it failed with), getMessage() (the validation error message) and toString() which returns a combination of all the three preceding methods. The default validation error messages are in English but stored in the constants CALENDAR_VALUE_TOOSMALL and CALENDAR_VALUE_TOOLARGE which you can redefine in your code.

Decorators

Provide a mechanism to add functionality to the main calendar objects (the subclasses of Calendar) without needing to directly extend them (and risk overwriting fields accidentally). When you create a decorator, you pass its constructor an instance of an existing calendar object. You can then make calls to the decorator in exactly the same way as you make calls to the original calendar object. This allows you to "overwrite" calendar methods, add new methods or even apply multiple decorators to the same calendar object. Decorators a typically either "injected" (via selection or the Calendar_Decorator_Wrapper decorator) into the loop where the calendar is rendered and / or to alter the output content (e.g. convert a numeric month into a textual month: 1 => January).

PEAR::Calendar provides some decorator implementations for you, to help with common tasks. These are not designed to suit everyone and hence are provided as optional code for you to use as needed (avoiding the performance cost associated with parsing code you're not using).

• Calendar_Decorator - this is the base decorator class which you should extend with your own. It provides the same API as the calendar object it is decorating, and simply routes calls through to it. Example;

  require_once 'Calendar/Decorator.php'; class ChristmasDecorator extends Calendar_Decorator { function ChristmasDecorator(&$Calendar) { parent::Calendar_Decorator($Calendar); } // Some method I've added function getDaysToChristmas() { $today = parent::thisDay(true); $Christmas = new Calendar_Day(date('Y'), 12, 25); $xmasday = $Christmas->thisDay(TRUE); $diff = $xmasday - $today; if ($diff < 0) { $NextChristmas = new Calendar_Day($Christmas->nextYear(), 12, 25); $nextxmasday = $NextChristmas->thisDay(true); $diff = $today - $nextxmasday; } return ($diff / 86400); } }

• Calendar_Decorator_Uri - provides a decorator to help with generating URLs (for example next / prev URLs).

  Include with

  require_once 'Calendar/Decorator/Uri.php';

  .

• Calendar_Decorator_Textual - helps with obtaining textual month names and weekday names from a calendar object.

  Include with

  require_once 'Calendar/Decorator/Textual.php';

  .

• Calendar_Decorator_Wrapper - is intended to help you add decorators to the children of the calendar object you are working with. It will wrap the children in the decorator you specify at the point fetch() or fetchAll() is called, after a build build() call.

  Include with

  require_once 'Calendar/Decorator/Wrapper.php';

  .