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