MDL-64063 core_calendar: events by time considers enrolment status.
[moodle.git] / calendar / classes / local / event / data_access / event_vault_interface.php
CommitLineData
84d865d6
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 * Event vault interface
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
42e76c3f 25namespace core_calendar\local\event\data_access;
84d865d6 26
20592f5f
JP
27defined('MOODLE_INTERNAL') || die();
28
42e76c3f
CB
29use core_calendar\local\event\entities\event_interface;
30
84d865d6
RW
31/**
32 * Interface for an event vault class
33 *
34 * @copyright 2017 Ryan Wyllie <ryan@moodle.com>
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 */
37interface event_vault_interface {
38 /**
39 * Retrieve an event for the given id.
40 *
5e6e3bab 41 * @param int $id The event id
84d865d6
RW
42 * @return event_interface|false
43 */
5e6e3bab 44 public function get_event_by_id($id);
84d865d6 45
258a5705
CB
46 /**
47 * Get all events restricted by various parameters, taking in to account user and group overrides.
48 *
20592f5f
JP
49 * @param int|null $timestartfrom Events with timestart from this value (inclusive).
50 * @param int|null $timestartto Events with timestart until this value (inclusive).
51 * @param int|null $timesortfrom Events with timesort from this value (inclusive).
52 * @param int|null $timesortto Events with timesort until this value (inclusive).
53 * @param event_interface|null $timestartafterevent Restrict the events in the timestart range to ones after this one.
54 * @param event_interface|null $timesortafterevent Restrict the events in the timesort range to ones after this one.
55 * @param int $limitnum Return at most this number of events.
56 * @param int|null $type Return only events of this type.
57 * @param array|null $usersfilter Return only events for these users.
58 * @param array|null $groupsfilter Return only events for these groups.
59 * @param array|null $coursesfilter Return only events for these courses.
60 * @param bool $withduration If true return only events starting within specified
61 * timestart otherwise return in progress events as well.
62 * @param bool $ignorehidden If true don't return hidden events.
63 * @param callable|null $filter Additional logic to filter out unwanted events.
64 * Must return true to keep the event, false to discard it.
65 * @return event_interface[] Array of event_interfaces.
258a5705
CB
66 */
67 public function get_events(
68 $timestartfrom = null,
69 $timestartto = null,
70 $timesortfrom = null,
71 $timesortto = null,
72 event_interface $timestartafterevent = null,
73 event_interface $timesortafterevent = null,
74 $limitnum = 20,
75 $type = null,
76 array $usersfilter = null,
77 array $groupsfilter = null,
78 array $coursesfilter = null,
0085b0ea 79 array $categoriesfilter = null,
258a5705
CB
80 $withduration = true,
81 $ignorehidden = true,
82 callable $filter = null
83 );
84
84d865d6
RW
85 /**
86 * Retrieve an array of events for the given user and time constraints.
87 *
5a0974c7
RW
88 * If using this function for pagination then you can provide the last event that you've seen
89 * ($afterevent) and it will be used to appropriately offset the result set so that you don't
90 * receive the same events again.
84d865d6
RW
91 * @param \stdClass $user The user for whom the events belong
92 * @param int $timesortfrom Events with timesort from this value (inclusive)
93 * @param int $timesortto Events with timesort until this value (inclusive)
94 * @param event_interface $afterevent Only return events after this one
95 * @param int $limitnum Return at most this number of events
644ffbd3 96 * @param bool $lmittononsuspendedevents Limit course events to courses the user is active in (not suspended).
84d865d6
RW
97 * @return event_interface
98 */
99 public function get_action_events_by_timesort(
100 \stdClass $user,
5e6e3bab
MN
101 $timesortfrom,
102 $timesortto,
84d865d6 103 event_interface $afterevent,
644ffbd3
AG
104 $limitnum,
105 $limittononsuspendedevents
84d865d6 106 );
5a0974c7
RW
107
108 /**
109 * Retrieve an array of events for the given user filtered by the course and time constraints.
110 *
111 * If using this function for pagination then you can provide the last event that you've seen
112 * ($afterevent) and it will be used to appropriately offset the result set so that you don't
113 * receive the same events again.
114 *
20592f5f
JP
115 * @param \stdClass $user The user for whom the events belong
116 * @param \stdClass $course The course to filter by
117 * @param int $timesortfrom Events with timesort from this value (inclusive)
118 * @param int $timesortto Events with timesort until this value (inclusive)
119 * @param event_interface $afterevent Only return events after this one
120 * @param int $limitnum Return at most this number of events
5a0974c7
RW
121 * @return action_event_interface
122 */
123 public function get_action_events_by_course(
124 \stdClass $user,
125 \stdClass $course,
126 $timesortfrom,
127 $timesortto,
128 event_interface $afterevent,
129 $limitnum
130 );
84d865d6 131}