PEAR::Calendar - Getting Started

Version: $Id: gettingstarted.html,v 1.3 2003/10/29 00:05:22 harryf Exp $

API Docs : Examples : Tutorials : Download

Contents

- Installing
- In a Hurry
- Package Overview
- Method Overview

Installing

  1. Setup the PEAR package manager (if you haven't got it already) - see Getting the manager (command line version) or Getting Up and Running with the PEAR Web Installer (web package manager).
  2. Type pear install Calendar (using the command line manager)
  3. PEAR::Calendar is now installed

In a Hurry

<?php
require_once 'Calendar/Month/Weekdays.php';

$Month = new Calendar_Month_Weekdays(2003,10);

$Month->build();

echo ( "<table>\n");

while ( $Day = $Month->fetch() ) {
    if ( $Day->isFirst() ) {
        echo ( "<tr>\n");
    }

    if ( $Day->isEmpty() ) {
        echo ( "<td>&nbsp;</td>\n");
    } else {
        echo ( "<td>".$Day->thisDay()."</td>\n");
    }

    if ( $Day->isLast() ) {
        echo ( "</tr>\n");
    }
}

echo ( "</table>\n");
?>

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 break down like;

Date Classes

Tabular Date Classes

Utility Classes

Method Overview

Constructors

The constructors of the Date classes accept integer date values as their arguments, beginning with the year (on the left) across to the second (on the right), depending on what class you're using, for example;

$Year = new Calendar_Year(2003);                    // 2003

$Month = new Calendar_Month(2003,10);               // October 2003
$Month = new Calendar_Month_Weekdays(2003,10);      // October 2003
$Month = new Calendar_Month_Weeks(2003,10);         // October 2003

$Day = new Calendar_Day(2003,10,25);                // 25th October 2003
$Hour = new Calendar_Hour(2003,10,25,13);           // 25th October 2003 13:00:00
$Minute = new Calendar_Minute(2003,10,25,13,31);    // 25th October 2003 13:31:00
$Second = new Calendar_Second(2003,10,25,13,31,45); // 25th October 2003 13:31:45

The exception to that is a Calendar_Week which takes an integer week as it's third argument (where a day would normally be used).

Note that Calendar_Month_Weekdays and Calendar_Month_Weeks both take an optional third argument (integer) which specifies the first day of the week and adjust tabular display (normally it defaults to Monday (1) - pass the integer value 0 to switch to Sunday as the first day, for example). Calendar_Week accepts the first day argument as the fourth to it's constructor.

Location Methods

All date and tabular date classes share the methods defined in the abstract base class Calendar. Among these are methods for an object of any of these classes to identify itself (what's it's date is) and the previous and next dates. For example;

$Day = new Calendar_Day(2003,10,1); // 1st October 2003

echo ( $Day->thisMonth() ); // Displays 10
echo ( $Day->prevMonth() ); // Displays 9
echo ( $Day->nextMonth() ); // Displays 11

echo ( $Day->thisDay() ); // Displays 1
echo ( $Day->prevDay() ); // Displays 30 (the 30th of September)
echo ( $Day->nextDay() ); // Displays 2

There are this***(), prev***() and next***() methods for years, months, days, hours, minutes and seconds. Also there are the methods thisWeek(), prevWeek() and nextWeek() which only become available if you're using an instance of Calendar_Week and be careful - these will stop (return NULL) if they reach the beginning or end of a month.

Passing any of these methods the argument TRUE will result in them returning a timestamp (normally a Unix timestamp but varies depending on the Calendar Engine you are using), for example;

$Second = new Calendar_Second(2003,10,25,13,32,44);

echo ( $Second->thisYear(TRUE) );     // Displays 1041375600
echo ( $Second->thisMonth(TRUE) );    // Displays 1064959200
echo ( $Second->thisDay(TRUE) );      // Displays 1067032800
echo ( $Second->thisHour(TRUE) );     // Displays 1067079600
echo ( $Second->thisMinute(TRUE) );   // Displays 1067081520
echo ( $Second->thisSecond(TRUE) );   // Displays 1067081564

Notice how the timestamp return increases, depending on the method that was called to obtain it. The first, obtained from thisYear(TRUE) is a timestamp for the beginning of the year 2003 (1st January 2003 in fact) while the third from thisDay(TRUE) is a timestamp for 25th October 2003.

Building and Fetching

Every date and tabular date class has a build() method which is used to generate the children of that date object. For example Calendar_Month builds Calendar_Day objects, the days being "children" of the month.

Once build is called, the children can be fetched from the date object using the simple fetch() iterator, for example;

$Month = new Calendar_Month(2003,10);

$Month->build();

$i = 1;
while ( $Day = $Month->fetch() ) {
    echo ( $Day->thisDay()."<br />\n" );
    $i++;
}

echo ( $i ); // Displays 31 (31 days in October)

If you don't like the iterator, and wish to use your own, you can simply extract the children with the fetchAll() method (returns an indexed array of child date objects) and check the number you got back with size(). Be careful the index of the array you get back. For Calendar_Month, Calendar_Month_Weekdays, Calendar_Month_Weeks, Calendar_Week and Calendar_Day, the first index of the array is 1 while for Calendar_Hour, Calendar_Minute and Calendar_Second the index begins with 0. Why? Consider 2003-1-1 00:00:00 ...

Note: Calendar_Second::build() doesn't do anything - it has no children.

Selecting Children

To help with rendering the calendar, the build() methods accept an index array of date objects which is compares with the children it is building. If it finds that an object that was passed to it matches a child, it set's the childs state to selected, meaning the isSelected() method (available on any date or tabular date objects) returns true. For example;

$Month = new Calendar_Month(2003,10);

$DayX = new Calendar_Day(2003,10,15);
$DayY = new Calendar_Day(2003,10,23);
$selection = array($DayX,$DayY);

$Month->build($selection);

while ( $Day = $Month->fetch() ) {
    if ( $Day->isSelected() ) {
        echo ( $Day->thisDay()."<br />\n" ); // Displays 15 or 23
    }
}

In the above example, only 15th October 2003 and 23rd October 2003 are displayed.

The objects you pass to the build method which match children that are being built are used to replace the child (i.e. if there was a match, you get your object back). This allows you to "inject" your own classes into the loop, best accomplished by extending Calendar_Decorator.

Note: the Calendar_Year::build() method takes a second argument to specify the first day of the week (see above).

Validation

All date objects and tabular objects are capable of validating themselves. By default they accept whatever arguments they are given on construction but you can validate the date with the isValid() method, for example;

$Day = new Calendar_Day(2003,10,32);

if ( !$Day->isValid() ) {
    die ('Invalid date');
}

For more fine grained validation, you can first call the getValidator() method, to return an instance of Calendar_Validator then list the validation errors;

$Day = new Calendar_Day(2003,10,32);

if ( !$Day->isValid() ) {
    $Validator = & $Day->getValidator();
    while ( $Error = $Validator->fetch() ) {
        echo ( $Error->getUnit().' is invalid<br>' );
    }
}

or...

$Day = new Calendar_Day(2003,10,32);

$Validator = & $Day->getValidator();
if ( !$Validator->isValid() ) {
    while ( $Error = $Validator->fetch() ) {
        echo ( $Error->toString().'<br>' );
    }
}