Method Overview
Method Overview
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.
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;
<?php
// 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
?>
Note that the tabular classes, 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 its 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 its date is) and the previous and next dates. For example;
<?php
// 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
?>
Notice that from the $Day I can find out not just about the day itself but also the month (or year/hour/minute/second). Notice also how prevDay() returned 30, taking care of working out that the previous day is in September for you. There are this***(), prev***() and next***() methods for years, months, days, hours, minutes and seconds.
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;
<?php
// 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
?>
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.
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.
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;
<?php
$Month = new Calendar_Month(2003, 10);
$Month->build();
while ($Day = $Month->fetch()) {
echo $Day->thisDay()."<br />\n";
}
?>
The fetch() method returns one child at a time, in ascending date order, and returns FALSE when there are no more children. It also automatically resets the internal collection of children, meaning you can loop over them as many times as you like.
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.
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;
<?php
$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 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).
Tabular Days
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.
Validation
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;
<?php
$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;
<?php
$Day = new Calendar_Day(2003, 10, 32);
if (!$Day->isValid()) {
$Validator = & $Day->getValidator();
while ($Error = $Validator->fetch()) {
echo $Error->getUnit().' is invalid<br>';
}
}
?>
or...
<?php
$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;
<?php
$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.