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/>.
  16
  17 namespace core_calendar;
  18
  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 {
  29
  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();
  39
  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();
  53
  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();
  60
  61     /**
  62      * Returns the minimum year for the calendar.
  63      *
  64      * @return int The minimum year
  65      */
  66     public abstract function get_min_year();
  67
  68     /**
  69      * Returns the maximum year for the calendar
  70      *
  71      * @return int The maximum year
  72      */
  73     public abstract function get_max_year();
  74
  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);
  83
  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);
  95
  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();
 102
 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();
 113
 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();
 123
 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);
 133
 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);
 143
 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);
 152
 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);
 161
 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 https://moodledev.io/docs/apis/subsystems/time#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);
 176
 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 https://moodledev.io/docs/apis/subsystems/time#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);
 187
 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);
 200
 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);
 213
 214     /**
 215      * This return locale for windows os.
 216      *
 217      * @return string locale
 218      */
 219     public abstract function locale_win_charset();
 220
 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     }
 242
 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');
 253
 254         return $date->getTimestamp();
 255     }
 256
 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');
 267
 268         return $date->getTimestamp();
 269     }
 270 }