Version: $Id: gettingstarted.html,v 1.3 2003/10/29 00:05:22 harryf Exp $
API Docs : Examples : Tutorials : Download
pear install Calendar
(using the command line manager)<?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> </td>\n"); } else { echo ( "<td>".$Day->thisDay()."</td>\n"); } if ( $Day->isLast() ) { echo ( "</tr>\n"); } } echo ( "</table>\n"); ?>
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;
Calendar_Year
- represents a year and can build Calendar_Month
, Calendar_Month_Weekdays
and Calendar_Month_Weeks
objects.require_once 'Calendar/Year.php';
.Calendar_Month
- represents a month and can build Calendar_Day
objects.require_once 'Calendar/Month.php';
.Calendar_Day
- represents a day and can build Calendar_Hour
objects.require_once 'Calendar/Day.php';
.Calendar_Hour
- represents an hour and can build Calendar_Minute
objects.require_once 'Calendar/Hour.php';
.Calendar_Minute
- represents a minute and can build Calendar_Second
objects.require_once 'Calendar/Minute.php';
.Calendar_Second
- represents a second (does not build other objects).require_once 'Calendar/Second.php';
.Calendar_Month_Weekdays
builds Calendar_Day
objects setting the isFirst()
, isLast()
and isEmpty()
states, to display a month in tabular form.require_once 'Calendar/Month/Weekdays.php';
.Calendar_Month_Weeks
builds Calendar_Week
objects, representing a month in terms of the tabular weeks in contains (see FAQ on what a week represents.require_once 'Calendar/Month/Weeks.php';
.Calendar_Week
builds Calendar_Day
objects, setting the isEmpty()
state if necessary and representing a tabular week in a month (i.e. you get 7 days from it).require_once 'Calendar/Week.php';
.Calendar_Validator
is not instantiated directly (not need to specifically include) but instead returned from the getValidator()
method you can call on any Date object or Tabular Date object. 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
which represents a validation error, providing methods to determine what went wrong.Calendar_Decorator
provides a decorator for any Date or Tabular date class, allowing you to extend the decorator and add functionality to a Date class without directly extending the Date class (and running the risk of conflicting variable names etc.)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.
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.
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.
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).
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>' ); } }