on-demand release 4.0dev+
[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.
cf34245d 65 * @param string|null $searchvalue The value a user wishes to search against
20592f5f 66 * @return event_interface[] Array of event_interfaces.
258a5705
CB
67 */
68 public function get_events(
69 $timestartfrom = null,
70 $timestartto = null,
71 $timesortfrom = null,
72 $timesortto = null,
73 event_interface $timestartafterevent = null,
74 event_interface $timesortafterevent = null,
75 $limitnum = 20,
76 $type = null,
77 array $usersfilter = null,
78 array $groupsfilter = null,
79 array $coursesfilter = null,
0085b0ea 80 array $categoriesfilter = null,
258a5705
CB
81 $withduration = true,
82 $ignorehidden = true,
cf34245d
HN
83 callable $filter = null,
84 ?string $searchvalue = null
258a5705
CB
85 );
86
84d865d6
RW
87 /**
88 * Retrieve an array of events for the given user and time constraints.
89 *
5a0974c7
RW
90 * If using this function for pagination then you can provide the last event that you've seen
91 * ($afterevent) and it will be used to appropriately offset the result set so that you don't
92 * receive the same events again.
84d865d6
RW
93 * @param \stdClass $user The user for whom the events belong
94 * @param int $timesortfrom Events with timesort from this value (inclusive)
95 * @param int $timesortto Events with timesort until this value (inclusive)
96 * @param event_interface $afterevent Only return events after this one
97 * @param int $limitnum Return at most this number of events
644ffbd3 98 * @param bool $lmittononsuspendedevents Limit course events to courses the user is active in (not suspended).
cf34245d 99 * @param string|null $searchvalue The value a user wishes to search against
84d865d6
RW
100 * @return event_interface
101 */
102 public function get_action_events_by_timesort(
103 \stdClass $user,
5e6e3bab
MN
104 $timesortfrom,
105 $timesortto,
84d865d6 106 event_interface $afterevent,
644ffbd3 107 $limitnum,
cf34245d
HN
108 $limittononsuspendedevents,
109 ?string $searchvalue = null
84d865d6 110 );
5a0974c7
RW
111
112 /**
113 * Retrieve an array of events for the given user filtered by the course and time constraints.
114 *
115 * If using this function for pagination then you can provide the last event that you've seen
116 * ($afterevent) and it will be used to appropriately offset the result set so that you don't
117 * receive the same events again.
118 *
20592f5f
JP
119 * @param \stdClass $user The user for whom the events belong
120 * @param \stdClass $course The course to filter by
121 * @param int $timesortfrom Events with timesort from this value (inclusive)
122 * @param int $timesortto Events with timesort until this value (inclusive)
123 * @param event_interface $afterevent Only return events after this one
124 * @param int $limitnum Return at most this number of events
cf34245d 125 * @param string|null $searchvalue The value a user wishes to search against
5a0974c7
RW
126 * @return action_event_interface
127 */
128 public function get_action_events_by_course(
129 \stdClass $user,
130 \stdClass $course,
131 $timesortfrom,
132 $timesortto,
133 event_interface $afterevent,
cf34245d
HN
134 $limitnum,
135 ?string $searchvalue = null
5a0974c7 136 );
84d865d6 137}