Merge branch 'MDL-60018-master' of git://github.com/jleyva/moodle
[moodle.git] / calendar / classes / local / api.php
CommitLineData
392d6a49
RW
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/**
18 * Contains class containing the internal calendar API.
19 *
20 * @package core_calendar
21 * @copyright 2017 Ryan Wyllie <ryan@moodle.com>
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25namespace core_calendar\local;
26
27defined('MOODLE_INTERNAL') || die();
28
55f5fcb9
RW
29use core_calendar\local\event\container;
30use core_calendar\local\event\entities\event_interface;
e62cd85f
RW
31use core_calendar\local\event\exceptions\limit_invalid_parameter_exception;
32
392d6a49
RW
33/**
34 * Class containing the local calendar API.
35 *
2229368a
MN
36 * This should not be used outside of core_calendar.
37 *
392d6a49
RW
38 * @package core_calendar
39 * @copyright 2017 Ryan Wyllie <ryan@moodle.com>
40 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41 */
42class api {
258a5705
CB
43 /**
44 * Get all events restricted by various parameters, taking in to account user and group overrides.
45 *
20592f5f
JP
46 * @param int|null $timestartfrom Events with timestart from this value (inclusive).
47 * @param int|null $timestartto Events with timestart until this value (inclusive).
48 * @param int|null $timesortfrom Events with timesort from this value (inclusive).
49 * @param int|null $timesortto Events with timesort until this value (inclusive).
50 * @param int|null $timestartaftereventid Restrict the events in the timestart range to ones after this ID.
51 * @param int|null $timesortaftereventid Restrict the events in the timesort range to ones after this ID.
52 * @param int $limitnum Return at most this number of events.
53 * @param int|null $type Return only events of this type.
54 * @param array|null $usersfilter Return only events for these users.
55 * @param array|null $groupsfilter Return only events for these groups.
56 * @param array|null $coursesfilter Return only events for these courses.
57 * @param bool $withduration If true return only events starting within specified
58 * timestart otherwise return in progress events as well.
59 * @param bool $ignorehidden If true don't return hidden events.
42e76c3f 60 * @return \core_calendar\local\event\entities\event_interface[] Array of event_interfaces.
258a5705
CB
61 */
62 public static function get_events(
63 $timestartfrom = null,
64 $timestartto = null,
65 $timesortfrom = null,
66 $timesortto = null,
67 $timestartaftereventid = null,
68 $timesortaftereventid = null,
69 $limitnum = 20,
70 $type = null,
71 array $usersfilter = null,
72 array $groupsfilter = null,
73 array $coursesfilter = null,
74 $withduration = true,
7fe41af5
AN
75 $ignorehidden = true,
76 callable $filter = null
258a5705
CB
77 ) {
78 global $USER;
79
d10693cb 80 $vault = \core_calendar\local\event\container::get_event_vault();
258a5705
CB
81
82 $timestartafterevent = null;
83 $timesortafterevent = null;
84
85 if ($timestartaftereventid && $event = $vault->get_event_by_id($timestartaftereventid)) {
86 $timestartafterevent = $event;
87 }
88
89 if ($timesortaftereventid && $event = $vault->get_event_by_id($timesortaftereventid)) {
90 $timesortafterevent = $event;
91 }
92
93 return $vault->get_events(
94 $timestartfrom,
95 $timestartto,
96 $timesortfrom,
97 $timesortto,
98 $timestartafterevent,
99 $timesortafterevent,
100 $limitnum,
101 $type,
102 $usersfilter,
103 $groupsfilter,
104 $coursesfilter,
105 $withduration,
7fe41af5
AN
106 $ignorehidden,
107 $filter
258a5705
CB
108 );
109 }
392d6a49
RW
110
111 /**
112 * Get a list of action events for the logged in user by the given
113 * timesort values.
114 *
115 * @param int|null $timesortfrom The start timesort value (inclusive)
116 * @param int|null $timesortto The end timesort value (inclusive)
117 * @param int|null $aftereventid Only return events after this one
118 * @param int $limitnum Limit results to this amount (between 1 and 50)
119 * @return array A list of action_event_interface objects
20592f5f 120 * @throws \moodle_exception
392d6a49
RW
121 */
122 public static function get_action_events_by_timesort(
123 $timesortfrom = null,
124 $timesortto = null,
125 $aftereventid = null,
126 $limitnum = 20
127 ) {
128 global $USER;
129
130 if (is_null($timesortfrom) && is_null($timesortto)) {
131 throw new \moodle_exception("Must provide a timesort to and/or from value");
132 }
133
134 if ($limitnum < 1 || $limitnum > 50) {
135 throw new \moodle_exception("Limit must be between 1 and 50 (inclusive)");
136 }
137
d10693cb 138 $vault = \core_calendar\local\event\container::get_event_vault();
392d6a49
RW
139
140 $afterevent = null;
141 if ($aftereventid && $event = $vault->get_event_by_id($aftereventid)) {
142 $afterevent = $event;
143 }
144
145 return $vault->get_action_events_by_timesort($USER, $timesortfrom, $timesortto, $afterevent, $limitnum);
146 }
e62cd85f
RW
147
148 /**
149 * Get a list of action events for the logged in user by the given
150 * course and timesort values.
151 *
152 * @param \stdClass $course The course the events must belong to
153 * @param int|null $timesortfrom The start timesort value (inclusive)
154 * @param int|null $timesortto The end timesort value (inclusive)
155 * @param int|null $aftereventid Only return events after this one
156 * @param int $limitnum Limit results to this amount (between 1 and 50)
157 * @return array A list of action_event_interface objects
20592f5f 158 * @throws limit_invalid_parameter_exception
e62cd85f
RW
159 */
160 public static function get_action_events_by_course(
161 $course,
162 $timesortfrom = null,
163 $timesortto = null,
164 $aftereventid = null,
165 $limitnum = 20
166 ) {
167 global $USER;
168
169 if ($limitnum < 1 || $limitnum > 50) {
170 throw new limit_invalid_parameter_exception(
171 "Limit must be between 1 and 50 (inclusive)");
172 }
173
d10693cb 174 $vault = \core_calendar\local\event\container::get_event_vault();
e62cd85f
RW
175
176 $afterevent = null;
177 if ($aftereventid && $event = $vault->get_event_by_id($aftereventid)) {
178 $afterevent = $event;
179 }
180
181 return $vault->get_action_events_by_course(
182 $USER, $course, $timesortfrom, $timesortto, $afterevent, $limitnum);
183 }
8a082024
RW
184
185 /**
186 * Get a list of action events for the logged in user by the given
187 * courses and timesort values.
188 *
189 * The limit number applies per course, not for the result set as a whole.
190 * E.g. Requesting 3 courses with a limit of 10 will result in up to 30
191 * events being returned (up to 10 per course).
192 *
193 * @param array $courses The courses the events must belong to
194 * @param int|null $timesortfrom The start timesort value (inclusive)
195 * @param int|null $timesortto The end timesort value (inclusive)
196 * @param int $limitnum Limit results per course to this amount (between 1 and 50)
197 * @return array A list of action_event_interface objects indexed by course id
198 */
199 public static function get_action_events_by_courses(
200 $courses = [],
201 $timesortfrom = null,
202 $timesortto = null,
203 $limitnum = 20
204 ) {
205 $return = [];
206
207 foreach ($courses as $course) {
208 $return[$course->id] = self::get_action_events_by_course(
209 $course,
210 $timesortfrom,
211 $timesortto,
212 null,
213 $limitnum
214 );
215 }
216
217 return $return;
218 }
55f5fcb9
RW
219
220 /**
221 * Change the start day for an event. Only the date will be
222 * modified, the time of day for the event will be left as is.
223 *
224 * @param event_interface $event The existing event to modify
96283892 225 * @param DateTimeInterface $startdate The new date to use for the start day
55f5fcb9
RW
226 * @return event_interface The new event with updated start date
227 */
228 public static function update_event_start_day(
229 event_interface $event,
96283892 230 \DateTimeInterface $startdate
55f5fcb9
RW
231 ) {
232 $mapper = container::get_event_mapper();
233 $legacyevent = $mapper->from_event_to_legacy_event($event);
234 $starttime = $event->get_times()->get_start_time()->setDate(
96283892
RW
235 $startdate->format('Y'),
236 $startdate->format('n'),
237 $startdate->format('j')
55f5fcb9
RW
238 );
239
240 // This function does our capability checks.
241 $legacyevent->update((object) ['timestart' => $starttime->getTimestamp()]);
242
243 return $mapper->from_legacy_event_to_event($legacyevent);
244 }
392d6a49 245}