For the main Calendar classes (the subclasses of Calendar) all share a common API (a common set of class methods). Although there are some minor variations in specific cases, you should find it intuitive and easy to remember, once you are familiar with what's available. This section summarizes the common methods and highlights the variations. For further information, consult the API documentation.
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;
// Natural Calendar Classes $Year = new Calendar_Year(2003); // 2003 $Month = new Calendar_Month(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 // Tabular Calendar Classes $Month = new Calendar_Month_Weekdays(2003, 10); // October 2003 $Month = new Calendar_Month_Weeks(2003, 10); // October 2003 $Week = new Calendar_Week(2003, 10, 25); // week containing 25th October 2003 |
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 its date is) and the previous and next dates. For example;
// Create a day $Day = new Calendar_Day(2003, 10, 1); // 1st October 2003 echo $Day->thisDay(); // Displays 1 echo $Day->prevDay(); // Displays 30 (the 30th of September) echo $Day->nextDay(); // Displays 2 echo $Day->thisMonth(); // Displays 10 echo $Day->prevMonth(); // Displays 9 echo $Day->nextMonth(); // Displays 11 |
Calling any of these methods and passing the value TRUE will result in a timestamp being returned (the type of timestamp depends on the Calendar Engine you are using - see the FAQ), for example;
// Create a second $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 |
| Warning |
The prev***() and next***() methods return values calculated relative to the current Calendar object you are working with. In the above example, if you wanted the day and month of the next day (which should be 2nd October 2003), calling nextDay() then nextMonth() would give you the 2nd of November not October. Instead you should call nextDay() passing it the argument TRUE, to get back a timestamp from which the next day can be obtained. Be aware of the Calendar_Decorator_Uri which is designed to help build URLs for next / prev links. |
There are also the methods thisWeek(), prevWeek() and nextWeek() which only become available if you're using an instance of Calendar_Week. The returned value format can be chosen among 'timestamp', 'n_in_month', 'n_in_year' or 'array'. Be careful - if you select 'n_in_month', it will return NULL if it reaches the beginning or end of a month.
Finally all Calendar objects provide the methods getTimeStamp() and setTimeStamp(). The former returns a timestamp in the format used by the calendar engine you are working with (i.e. Unix Timestamp if it's the default UnixTs engine or of format YYYY-MM-DD HH:MM:SS). The later excepts a timestamp which is used to replace the values the Calendar object was constructed with.
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();
while ($Day = $Month->fetch()) {
echo $Day->thisDay()."<br />\n";
} |
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 from fetchAll(). For Calendar_Year, Calendar_Month, Calendar_Month_Weekdays, Calendar_Month_Weeks and Calendar_Week, the first index of the array is 1 while for Calendar_Day, 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
}
} |
The objects you pass to build() which match children that are being built replace the child (i.e. if there was a match, you get your object back). This allows you to "inject" your own objects 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 discussion on Constructors).
The Calendar_Day class has three unique methods, which don't appear elsewhere, and are used purely for building tabular calendars. The isEmpty() is used to determine whether the day is an empty day or not (see FAQ for explaination of empty days). The methods isFirst() and isLast() are used to mark the beginning and and of a week.
Whether you need to use these methods depends on which class was used to build the day objects. If the day was built with Calendar_Month_Weekdays, all three of these methods are applicable (you may have empty days and Calendar_Month_Weekdays builts a complete month but delimits the beginning and end of each week so you can find it with isFirst() and isLast()). If the day was built with Calendar_Week, only the isEmpty() method is applicable (the first or last week in a month may contain empty days). For day objects built in any other manner, isEmpty(), isFirst() and isLast() are meaningless.
All date objects and tabular objects (except weeks) 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');
} |
$Day = new Calendar_Day(2003, 10, 32);
if (!$Day->isValid()) {
$Validator = & $Day->getValidator();
while ($Error = $Validator->fetch()) {
echo $Error->getUnit().' is invalid<br>';
}
} |
$Day = new Calendar_Day(2003, 10, 32);
$Validator = & $Day->getValidator();
if (!$Validator->isValid()) {
while ($Error = $Validator->fetch()) {
echo $Error->toString().'<br>';
}
} |
Note that rather than validating dates, you may prefer to automatically adjust them with the adjust() method, for example;
$Day = new Calendar_Day(2003, 10, 32); $Day->adjust(); echo $Day->thisYear(); // 2003 echo $Day->thisMonth(); // 11 (moved forward a month) echo $Day->thisDay(); // 1 (the first of the month) |
That summarizes all the methods available within PEAR::Calendar, apart from the those provided in the Decorator classes.