Merge branch 'MDL-41792_master' of https://github.com/markn86/moodle
[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 of the calendar.
63      *
64      * @return int the minumum year
65      */
66     public abstract function get_min_year();
68     /**
69      * Returns the maximum year of the calendar.
70      *
71      * @return int the max year
72      */
73     public abstract function get_max_year();
75     /**
76      * Returns the number of days in a week.
77      *
78      * @return int the number of days
79      */
80     public abstract function get_num_weekdays();
82     /**
83      * Returns an indexed list of all the names of the weekdays.
84      *
85      * The list starts with the index 0. Each index, representing a
86      * day, must be an array that contains the indexes 'shortname'
87      * and 'fullname'.
88      *
89      * @return array array of days
90      */
91     public abstract function get_weekdays();
93     /**
94      * Returns the index of the starting week day.
95      *
96      * This may vary, for example in the Gregorian calendar, some may consider Monday
97      * as the start of the week, where as others may consider Sunday the start.
98      *
99      * @return int
100      */
101     public abstract function get_starting_weekday();
103     /**
104      * Returns the index of the weekday for a specific calendar date.
105      *
106      * @param int $year
107      * @param int $month
108      * @param int $day
109      * @return int
110      */
111     public abstract function get_weekday($year, $month, $day);
113     /**
114      * Returns the number of days in a given month.
115      *
116      *
117      * @param int $year
118      * @param int $month
119      * @return int the number of days
120      */
121     public abstract function get_num_days_in_month($year, $month);
123     /**
124      * Get the previous month.
125      *
126      * @param int $year
127      * @param int $month
128      * @return array previous month and year
129      */
130     public abstract function get_prev_month($year, $month);
132     /**
133      * Get the next month.
134      *
135      * @param int $year
136      * @param int $month
137      * @return array the following month and year
138      */
139     public abstract function get_next_month($year, $month);
141     /**
142      * Returns a formatted string that represents a date in user time.
143      *
144      * @param int $time the timestamp in UTC, as obtained from the database
145      * @param string $format strftime format
146      * @param int|float|string $timezone the timezone to use
147      *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
148      * @param bool $fixday if true then the leading zero from %d is removed,
149      *        if false then the leading zero is maintained
150      * @param bool $fixhour if true then the leading zero from %I is removed,
151      *        if false then the leading zero is maintained
152      * @return string the formatted date/time
153      */
154     public abstract function timestamp_to_date_string($time, $format, $timezone, $fixday, $fixhour);
156     /**
157      * Given a $time timestamp in GMT (seconds since epoch), returns an array that represents
158      * the date in user time.
159      *
160      * @param int $time timestamp in GMT
161      * @param float|int|string $timezone the timezone to use to calculate the time
162      *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
163      * @return array an array that represents the date in user time
164      */
165     public abstract function timestamp_to_date_array($time, $timezone = 99);
167     /**
168      * Provided with a day, month, year, hour and minute in the specific
169      * calendar type convert it into the equivalent Gregorian date.
170      *
171      * @param int $year
172      * @param int $month
173      * @param int $day
174      * @param int $hour
175      * @param int $minute
176      * @return array the converted date
177      */
178     public abstract function convert_to_gregorian($year, $month, $day, $hour = 0, $minute = 0);
180     /**
181      * Provided with a day, month, year, hour and minute in a Gregorian date
182      * convert it into the specific calendar type date.
183      *
184      * @param int $year
185      * @param int $month
186      * @param int $day
187      * @param int $hour
188      * @param int $minute
189      * @return array the converted date
190      */
191     public abstract function convert_from_gregorian($year, $month, $day, $hour = 0, $minute = 0);