15c5a0cad1482853a951132efe109bac076ef18b
[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      * @return event_interface
97      */
98     public function get_action_events_by_timesort(
99         \stdClass $user,
100         $timesortfrom,
101         $timesortto,
102         event_interface $afterevent,
103         $limitnum
104     );
106     /**
107      * Retrieve an array of events for the given user filtered by the course and time constraints.
108      *
109      * If using this function for pagination then you can provide the last event that you've seen
110      * ($afterevent) and it will be used to appropriately offset the result set so that you don't
111      * receive the same events again.
112      *
113      * @param \stdClass       $user         The user for whom the events belong
114      * @param \stdClass       $course       The course to filter by
115      * @param int             $timesortfrom Events with timesort from this value (inclusive)
116      * @param int             $timesortto   Events with timesort until this value (inclusive)
117      * @param event_interface $afterevent   Only return events after this one
118      * @param int             $limitnum     Return at most this number of events
119      * @return action_event_interface
120      */
121     public function get_action_events_by_course(
122         \stdClass $user,
123         \stdClass $course,
124         $timesortfrom,
125         $timesortto,
126         event_interface $afterevent,
127         $limitnum
128     );