on-demand release 4.0dev+
[moodle.git] / calendar / classes / type_base.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 namespace core_calendar;
19 /**
20  * Defines functions used by calendar type plugins.
21  *
22  * This library provides a unified interface for calendar types.
23  *
24  * @package core_calendar
25  * @copyright 2008 onwards Foodle Group {@link http://foodle.org}
26  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
28 abstract class type_base {
30     /**
31      * Returns the name of the calendar.
32      *
33      * This is the non-translated name, usually just
34      * the name of the calendar folder.
35      *
36      * @return string the calendar name
37      */
38     public abstract function get_name();
40     /**
41      * Returns a list of all the possible days for all months.
42      *
43      * This is used to generate the select box for the days
44      * in the date selector elements. Some months contain more days
45      * than others so this function should return all possible days as
46      * we can not predict what month will be chosen (the user
47      * may have JS turned off and we need to support this situation in
48      * Moodle).
49      *
50      * @return array the days
51      */
52     public abstract function get_days();
54     /**
55      * Returns a list of all the names of the months.
56      *
57      * @return array the month names
58      */
59     public abstract function get_months();
61     /**
62      * Returns the minimum year for the calendar.
63      *
64      * @return int The minimum year
65      */
66     public abstract function get_min_year();
68     /**
69      * Returns the maximum year for the calendar
70      *
71      * @return int The maximum year
72      */
73     public abstract function get_max_year();
75     /**
76      * Returns an array of years.
77      *
78      * @param int $minyear
79      * @param int $maxyear
80      * @return array the years
81      */
82     public abstract function get_years($minyear = null, $maxyear = null);
84     /**
85      * Returns a multidimensional array with information for day, month, year
86      * and the order they are displayed when selecting a date.
87      * The order in the array will be the order displayed when selecting a date.
88      * Override this function to change the date selector order.
89      *
90      * @param int $minyear The year to start with
91      * @param int $maxyear The year to finish with
92      * @return array Full date information
93      */
94     public abstract function get_date_order($minyear = null, $maxyear = null);
96     /**
97      * Returns the number of days in a week.
98      *
99      * @return int the number of days
100      */
101     public abstract function get_num_weekdays();
103     /**
104      * Returns an indexed list of all the names of the weekdays.
105      *
106      * The list starts with the index 0. Each index, representing a
107      * day, must be an array that contains the indexes 'shortname'
108      * and 'fullname'.
109      *
110      * @return array array of days
111      */
112     public abstract function get_weekdays();
114     /**
115      * Returns the index of the starting week day.
116      *
117      * This may vary, for example in the Gregorian calendar, some may consider Monday
118      * as the start of the week, where as others may consider Sunday the start.
119      *
120      * @return int
121      */
122     public abstract function get_starting_weekday();
124     /**
125      * Returns the index of the weekday for a specific calendar date.
126      *
127      * @param int $year
128      * @param int $month
129      * @param int $day
130      * @return int
131      */
132     public abstract function get_weekday($year, $month, $day);
134     /**
135      * Returns the number of days in a given month.
136      *
137      *
138      * @param int $year
139      * @param int $month
140      * @return int the number of days
141      */
142     public abstract function get_num_days_in_month($year, $month);
144     /**
145      * Get the previous month.
146      *
147      * @param int $year
148      * @param int $month
149      * @return array previous month and year
150      */
151     public abstract function get_prev_month($year, $month);
153     /**
154      * Get the next month.
155      *
156      * @param int $year
157      * @param int $month
158      * @return array the following month and year
159      */
160     public abstract function get_next_month($year, $month);
162     /**
163      * Returns a formatted string that represents a date in user time.
164      *
165      * @param int $time the timestamp in UTC, as obtained from the database
166      * @param string $format strftime format
167      * @param int|float|string $timezone the timezone to use
168      *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
169      * @param bool $fixday if true then the leading zero from %d is removed,
170      *        if false then the leading zero is maintained
171      * @param bool $fixhour if true then the leading zero from %I is removed,
172      *        if false then the leading zero is maintained
173      * @return string the formatted date/time
174      */
175     public abstract function timestamp_to_date_string($time, $format, $timezone, $fixday, $fixhour);
177     /**
178      * Given a $time timestamp in GMT (seconds since epoch), returns an array that represents
179      * the date in user time.
180      *
181      * @param int $time timestamp in GMT
182      * @param float|int|string $timezone the timezone to use to calculate the time
183      *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
184      * @return array an array that represents the date in user time
185      */
186     public abstract function timestamp_to_date_array($time, $timezone = 99);
188     /**
189      * Provided with a day, month, year, hour and minute in the specific
190      * calendar type convert it into the equivalent Gregorian date.
191      *
192      * @param int $year
193      * @param int $month
194      * @param int $day
195      * @param int $hour
196      * @param int $minute
197      * @return array the converted date
198      */
199     public abstract function convert_to_gregorian($year, $month, $day, $hour = 0, $minute = 0);
201     /**
202      * Provided with a day, month, year, hour and minute in a Gregorian date
203      * convert it into the specific calendar type date.
204      *
205      * @param int $year
206      * @param int $month
207      * @param int $day
208      * @param int $hour
209      * @param int $minute
210      * @return array the converted date
211      */
212     public abstract function convert_from_gregorian($year, $month, $day, $hour = 0, $minute = 0);
214     /**
215      * This return locale for windows os.
216      *
217      * @return string locale
218      */
219     public abstract function locale_win_charset();
221     /**
222      * Provided with a day, month, year, hour and minute in the specific
223      * calendar type convert it into the equivalent Unix Time Stamp.
224      *
225      * @param int $year
226      * @param int $month
227      * @param int $day
228      * @param int $hour
229      * @param int $minute
230      * @return int timestamp
231      */
232     public function convert_to_timestamp($year, $month, $day, $hour = 0, $minute = 0) {
233         $gregorianinfo = $this->convert_to_gregorian($year, $month, $day, $hour, $minute);
234         return make_timestamp(
235             $gregorianinfo['year'],
236             $gregorianinfo['month'],
237             $gregorianinfo['day'],
238             $gregorianinfo['hour'],
239             $gregorianinfo['minute'],
240             0);
241     }
243     /**
244      * Get the previous day.
245      *
246      * @param int $daytimestamp The day timestamp.
247      * @return int previous day timestamp
248      */
249     public function get_prev_day($daytimestamp) {
250         $date = new \DateTime();
251         $date->setTimestamp($daytimestamp);
252         $date->modify('-1 day');
254         return $date->getTimestamp();
255     }
257     /**
258      * Get the next day.
259      *
260      * @param int $daytimestamp The day timestamp.
261      * @return int the following day
262      */
263     public function get_next_day($daytimestamp) {
264         $date = new \DateTime();
265         $date->setTimestamp($daytimestamp);
266         $date->modify('+1 day');
268         return $date->getTimestamp();
269     }