MDL-41664 - Calendar: Add method for formating years in the new calendar plugin.
[moodle.git] / calendar / classes / type_base.php
CommitLineData
2f00e1b2 1<?php
2f00e1b2
MN
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/>.
16
022745ac
MN
17namespace core_calendar;
18
2f00e1b2
MN
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
2f00e1b2
MN
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 */
022745ac 28abstract class type_base {
2f00e1b2 29
73412d96
AG
30 /** string $minyear Minimum year we are using. */
31 protected $minyear = 1900;
32
33 /** string $maxyear Maximum year we are using. */
34 protected $maxyear = 2050;
35
da304137
MN
36 /**
37 * Returns the name of the calendar.
38 *
39 * This is the non-translated name, usually just
40 * the name of the calendar folder.
41 *
42 * @return string the calendar name
43 */
44 public abstract function get_name();
45
2f00e1b2
MN
46 /**
47 * Returns a list of all the possible days for all months.
48 *
49 * This is used to generate the select box for the days
50 * in the date selector elements. Some months contain more days
51 * than others so this function should return all possible days as
52 * we can not predict what month will be chosen (the user
53 * may have JS turned off and we need to support this situation in
54 * Moodle).
55 *
56 * @return array the days
57 */
58 public abstract function get_days();
59
60 /**
61 * Returns a list of all the names of the months.
62 *
63 * @return array the month names
64 */
65 public abstract function get_months();
66
67 /**
73412d96 68 * Returns a list of all of the years being used.
2f00e1b2 69 *
73412d96 70 * @return array the years.
2f00e1b2 71 */
73412d96 72 public abstract function get_years();
2f00e1b2
MN
73
74 /**
73412d96
AG
75 * Returns a multidimensional array with information for day, month, year
76 * and the order they are displayed when selecting a date.
77 * The order in the array will be the order displayed when selecting a date.
78 * Override this function to change the date selector order.
2f00e1b2 79 *
73412d96
AG
80 * @param int $minyear The year to start with.
81 * @param int $maxyear The year to finish with.
82 * @return array Full date information.
2f00e1b2 83 */
73412d96 84 public abstract function date_order($minyear = null, $maxyear = null);
2f00e1b2 85
da304137
MN
86 /**
87 * Returns the number of days in a week.
88 *
89 * @return int the number of days
90 */
91 public abstract function get_num_weekdays();
92
93 /**
94 * Returns an indexed list of all the names of the weekdays.
95 *
96 * The list starts with the index 0. Each index, representing a
97 * day, must be an array that contains the indexes 'shortname'
98 * and 'fullname'.
99 *
100 * @return array array of days
101 */
102 public abstract function get_weekdays();
103
104 /**
105 * Returns the index of the starting week day.
106 *
107 * This may vary, for example in the Gregorian calendar, some may consider Monday
108 * as the start of the week, where as others may consider Sunday the start.
109 *
110 * @return int
111 */
112 public abstract function get_starting_weekday();
113
114 /**
115 * Returns the index of the weekday for a specific calendar date.
116 *
117 * @param int $year
118 * @param int $month
119 * @param int $day
120 * @return int
121 */
122 public abstract function get_weekday($year, $month, $day);
123
124 /**
125 * Returns the number of days in a given month.
126 *
127 *
128 * @param int $year
129 * @param int $month
130 * @return int the number of days
131 */
132 public abstract function get_num_days_in_month($year, $month);
133
134 /**
135 * Get the previous month.
136 *
137 * @param int $year
138 * @param int $month
139 * @return array previous month and year
140 */
141 public abstract function get_prev_month($year, $month);
142
143 /**
144 * Get the next month.
145 *
146 * @param int $year
147 * @param int $month
148 * @return array the following month and year
149 */
150 public abstract function get_next_month($year, $month);
151
f59ab4ad
MN
152 /**
153 * Returns a formatted string that represents a date in user time.
154 *
da304137 155 * @param int $time the timestamp in UTC, as obtained from the database
f59ab4ad
MN
156 * @param string $format strftime format
157 * @param int|float|string $timezone the timezone to use
158 * {@link http://docs.moodle.org/dev/Time_API#Timezone}
159 * @param bool $fixday if true then the leading zero from %d is removed,
160 * if false then the leading zero is maintained
161 * @param bool $fixhour if true then the leading zero from %I is removed,
162 * if false then the leading zero is maintained
163 * @return string the formatted date/time
164 */
da304137 165 public abstract function timestamp_to_date_string($time, $format, $timezone, $fixday, $fixhour);
f59ab4ad
MN
166
167 /**
168 * Given a $time timestamp in GMT (seconds since epoch), returns an array that represents
169 * the date in user time.
170 *
171 * @param int $time timestamp in GMT
172 * @param float|int|string $timezone the timezone to use to calculate the time
173 * {@link http://docs.moodle.org/dev/Time_API#Timezone}
174 * @return array an array that represents the date in user time
175 */
da304137 176 public abstract function timestamp_to_date_array($time, $timezone = 99);
f59ab4ad 177
2f00e1b2
MN
178 /**
179 * Provided with a day, month, year, hour and minute in the specific
180 * calendar type convert it into the equivalent Gregorian date.
181 *
182 * @param int $year
183 * @param int $month
184 * @param int $day
185 * @param int $hour
186 * @param int $minute
da304137 187 * @return array the converted date
2f00e1b2
MN
188 */
189 public abstract function convert_to_gregorian($year, $month, $day, $hour = 0, $minute = 0);
190
191 /**
192 * Provided with a day, month, year, hour and minute in a Gregorian date
193 * convert it into the specific calendar type date.
194 *
195 * @param int $year
196 * @param int $month
197 * @param int $day
198 * @param int $hour
199 * @param int $minute
da304137 200 * @return array the converted date
2f00e1b2
MN
201 */
202 public abstract function convert_from_gregorian($year, $month, $day, $hour = 0, $minute = 0);
2f00e1b2 203}