28b98152c65453b1ed43bef3866a8ae108313dd7
[moodle.git] / calendar / classes / local / event / data_access / event_vault_interface.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/>.
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  */
25 namespace core_calendar\local\event\data_access;
27 defined('MOODLE_INTERNAL') || die();
29 use core_calendar\local\event\entities\event_interface;
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  */
37 interface event_vault_interface {
38     /**
39      * Retrieve an event for the given id.
40      *
41      * @param int $id The event id
42      * @return event_interface|false
43      */
44     public function get_event_by_id($id);
46     /**
47      * Get all events restricted by various parameters, taking in to account user and group overrides.
48      *
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.
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,
79         array $categoriesfilter = null,
80         $withduration = true,
81         $ignorehidden = true,
82         callable $filter = null
83     );
85     /**
86      * Retrieve an array of events for the given user and time constraints.
87      *
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.
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
96      * @param bool            $lmittononsuspendedevents Limit course events to courses the user is active in (not suspended).
97      * @return event_interface
98      */
99     public function get_action_events_by_timesort(
100         \stdClass $user,
101         $timesortfrom,
102         $timesortto,
103         event_interface $afterevent,
104         $limitnum,
105         $limittononsuspendedevents
106     );
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      *
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
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     );