MDL-63816 privacy: Corrected provider get_users_in_context descriptions
[moodle.git] / group / classes / privacy / provider.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  * Privacy Subsystem implementation for core_group.
19  *
20  * @package    core_group
21  * @category   privacy
22  * @copyright  2018 Shamim Rezaie <shamim@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 namespace core_group\privacy;
28 defined('MOODLE_INTERNAL') || die();
30 use core_privacy\local\metadata\collection;
31 use core_privacy\local\request\approved_contextlist;
32 use core_privacy\local\request\approved_userlist;
33 use core_privacy\local\request\contextlist;
34 use core_privacy\local\request\transform;
35 use core_privacy\local\request\userlist;
37 /**
38  * Privacy Subsystem implementation for core_group.
39  *
40  * @copyright  2018 Shamim Rezaie <shamim@moodle.com>
41  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
42  */
43 class provider implements
44         // Groups store user data.
45         \core_privacy\local\metadata\provider,
47         // The group subsystem contains user's group memberships.
48         \core_privacy\local\request\subsystem\provider,
50         // The group subsystem can provide information to other plugins.
51         \core_privacy\local\request\subsystem\plugin_provider,
53         // This plugin is capable of determining which users have data within it.
54         \core_privacy\local\request\core_userlist_provider {
56     /**
57      * Returns meta data about this system.
58      *
59      * @param   collection $collection The initialised collection to add items to.
60      * @return  collection A listing of user data stored through this system.
61      */
62     public static function get_metadata(collection $collection) : collection {
63         $collection->add_database_table('groups_members', [
64             'groupid' => 'privacy:metadata:groups:groupid',
65             'userid' => 'privacy:metadata:groups:userid',
66             'timeadded' => 'privacy:metadata:groups:timeadded',
67         ], 'privacy:metadata:groups');
69         return $collection;
70     }
72     /**
73      * Writes user data to the writer for the user to download.
74      *
75      * @param \context  $context    The context to export data for.
76      * @param string    $component  The component that is calling this function. Empty string means no component.
77      * @param array     $subcontext The sub-context in which to export this data.
78      * @param int       $itemid     Optional itemid associated with component.
79      */
80     public static function export_groups(\context $context, string $component, array $subcontext = [], int $itemid = 0) {
81         global $DB, $USER;
83         if (!$context instanceof \context_course) {
84             return;
85         }
87         $subcontext[] = get_string('groups', 'core_group');
89         $sql = "SELECT gm.id, gm.timeadded, gm.userid, g.name
90                   FROM {groups_members} gm
91                   JOIN {groups} g ON gm.groupid = g.id
92                  WHERE g.courseid = :courseid
93                        AND gm.component = :component
94                        AND gm.userid = :userid";
95         $params = [
96             'courseid'  => $context->instanceid,
97             'component' => $component,
98             'userid'    => $USER->id
99         ];
101         if ($itemid) {
102             $sql .= ' AND gm.itemid = :itemid';
103             $params['itemid'] = $itemid;
104         }
106         $groups = $DB->get_records_sql($sql, $params);
108         $groups = array_map(function($group) {
109             return (object) [
110                 'name' => format_string($group->name),
111                 'timeadded' => transform::datetime($group->timeadded),
112             ];
113         }, $groups);
115         if (!empty($groups)) {
116             \core_privacy\local\request\writer::with_context($context)
117                     ->export_data($subcontext, (object) [
118                         'groups' => $groups,
119                     ]);
120         }
121     }
123     /**
124      * Deletes all group memberships for a specified context and component.
125      *
126      * @param \context  $context    Details about which context to delete group memberships for.
127      * @param string    $component  Component to delete. Empty string means no component (manual group memberships).
128      * @param int       $itemid     Optional itemid associated with component.
129      */
130     public static function delete_groups_for_all_users(\context $context, string $component, int $itemid = 0) {
131         global $DB;
133         if (!$context instanceof \context_course) {
134             return;
135         }
137         if (!$DB->record_exists('groups', ['courseid' => $context->instanceid])) {
138             return;
139         }
141         $select = "component = :component AND groupid IN (SELECT g.id FROM {groups} g WHERE courseid = :courseid)";
142         $params = ['component' => $component, 'courseid' => $context->instanceid];
144         if ($itemid) {
145             $select .= ' AND itemid = :itemid';
146             $params['itemid'] = $itemid;
147         }
149         $DB->delete_records_select('groups_members', $select, $params);
151         // Purge the group and grouping cache for users.
152         \cache_helper::purge_by_definition('core', 'user_group_groupings');
153     }
155     /**
156      * Deletes all records for a user from a list of approved contexts.
157      *
158      * @param approved_contextlist  $contextlist    Contains the user ID and a list of contexts to be deleted from.
159      * @param string                $component      Component to delete from. Empty string means no component (manual memberships).
160      * @param int                   $itemid         Optional itemid associated with component.
161      */
162     public static function delete_groups_for_user(approved_contextlist $contextlist, string $component, int $itemid = 0) {
163         global $DB;
165         $userid = $contextlist->get_user()->id;
167         $contextids = $contextlist->get_contextids();
169         if (!$contextids) {
170             return;
171         }
173         list($contextsql, $contextparams) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED);
174         $contextparams += ['contextcourse' => CONTEXT_COURSE];
175         $groupselect = "SELECT g.id
176                           FROM {groups} g
177                           JOIN {context} ctx ON g.courseid = ctx.instanceid AND ctx.contextlevel = :contextcourse
178                          WHERE ctx.id $contextsql";
180         if (!$DB->record_exists_sql($groupselect, $contextparams)) {
181             return;
182         }
184         $select = "userid = :userid AND component = :component AND groupid IN ({$groupselect})";
185         $params = ['userid' => $userid, 'component' => $component] + $contextparams;
187         if ($itemid) {
188             $select .= ' AND itemid = :itemid';
189             $params['itemid'] = $itemid;
190         }
192         $DB->delete_records_select('groups_members', $select, $params);
194         // Invalidate the group and grouping cache for the user.
195         \cache_helper::invalidate_by_definition('core', 'user_group_groupings', array(), array($userid));
196     }
198     /**
199      * Add the list of users who are members of some groups in the specified constraints.
200      *
201      * @param   userlist    $userlist   The userlist to add the users to.
202      * @param   string      $component  The component to check.
203      * @param   int         $itemid     Optional itemid associated with component.
204      */
205     public static function get_group_members_in_context(userlist $userlist, string $component, int $itemid = 0) {
206         $context = $userlist->get_context();
208         if (!$context instanceof \context_course) {
209             return;
210         }
212         // Group members in the given context.
213         $sql = "SELECT gm.userid
214                   FROM {groups_members} gm
215                   JOIN {groups} g ON gm.groupid = g.id
216                  WHERE g.courseid = :courseid AND gm.component = :component";
217         $params = [
218             'courseid'      => $context->instanceid,
219             'component'     => $component
220         ];
222         if ($itemid) {
223             $sql .= ' AND gm.itemid = :itemid';
224             $params['itemid'] = $itemid;
225         }
227         $userlist->add_from_sql('userid', $sql, $params);
228     }
230     /**
231      * Deletes all records for multiple users within a single context.
232      *
233      * @param approved_userlist $userlist   The approved context and user information to delete information for.
234      * @param string            $component  Component to delete from. Empty string means no component (manual memberships).
235      * @param int               $itemid     Optional itemid associated with component.
236      */
237     public static function delete_groups_for_users(approved_userlist $userlist, string $component, int $itemid = 0) {
238         global $DB;
240         $context = $userlist->get_context();
241         $userids = $userlist->get_userids();
243         list($usersql, $userparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED);
245         $groupselect = "SELECT g.id
246                           FROM {groups} g
247                           JOIN {context} ctx ON g.courseid = ctx.instanceid AND ctx.contextlevel = :contextcourse
248                          WHERE ctx.id = :contextid";
249         $groupparams = ['contextid' => $context->id, 'contextcourse' => CONTEXT_COURSE];
251         $select = "component = :component AND userid {$usersql} AND groupid IN ({$groupselect})";
252         $params = ['component' => $component] + $groupparams + $userparams;
254         if ($itemid) {
255             $select .= ' AND itemid = :itemid';
256             $params['itemid'] = $itemid;
257         }
259         $DB->delete_records_select('groups_members', $select, $params);
261         // Invalidate the group and grouping cache for the user.
262         \cache_helper::invalidate_by_definition('core', 'user_group_groupings', array(), $userids);
263     }
265     /**
266      * Get the list of contexts that contain group membership for the specified user.
267      *
268      * @param   int     $userid     The user to search.
269      * @param   string  $component  The component to check.
270      * @param   int     $itemid     Optional itemid associated with component.
271      * @return  contextlist         The contextlist containing the list of contexts.
272      */
273     public static function get_contexts_for_group_member(int $userid, string $component, int $itemid = 0) {
274         $contextlist = new contextlist();
276         $sql = "SELECT ctx.id
277                   FROM {groups_members} gm
278                   JOIN {groups} g ON gm.groupid = g.id
279                   JOIN {context} ctx ON g.courseid = ctx.instanceid AND ctx.contextlevel = :contextcourse
280                  WHERE gm.userid = :userid AND gm.component = :component";
282         $params = [
283             'contextcourse' => CONTEXT_COURSE,
284             'userid'        => $userid,
285             'component'     => $component
286         ];
288         if ($itemid) {
289             $sql .= ' AND gm.itemid = :itemid';
290             $params['itemid'] = $itemid;
291         }
293         $contextlist->add_from_sql($sql, $params);
295         return $contextlist;
296     }
298     /**
299      * Get the list of users who have data within a context.
300      *
301      * @param   int $userid The user to search.
302      * @return  contextlist The contextlist containing the list of contexts used in this plugin.
303      */
304     public static function get_contexts_for_userid(int $userid) : contextlist {
305         return static::get_contexts_for_group_member($userid, '');
306     }
308     /**
309      * Get the list of users who have data within a context.
310      *
311      * @param   userlist    $userlist   The userlist containing the list of users who have data in this context/plugin combination.
312      */
313     public static function get_users_in_context(userlist $userlist) {
314         $context = $userlist->get_context();
316         if (!$context instanceof \context_course) {
317             return;
318         }
320         static::get_group_members_in_context($userlist, '');
321     }
323     /**
324      * Export all user data for the specified user, in the specified contexts.
325      *
326      * @param approved_contextlist $contextlist The approved contexts to export information for.
327      */
328     public static function export_user_data(approved_contextlist $contextlist) {
329         $contexts = $contextlist->get_contexts();
331         foreach ($contexts as $context) {
332             static::export_groups($context, '');
333         }
334     }
336     /**
337      * Delete all data for all users in the specified context.
338      *
339      * @param context $context The specific context to delete data for.
340      */
341     public static function delete_data_for_all_users_in_context(\context $context) {
342         static::delete_groups_for_all_users($context, '');
343     }
345     /**
346      * Delete all user data for the specified user, in the specified contexts.
347      *
348      * @param approved_contextlist $contextlist The approved contexts and user information to delete information for.
349      */
350     public static function delete_data_for_user(approved_contextlist $contextlist) {
351         static::delete_groups_for_user($contextlist, '');
352     }
354     /**
355      * Delete multiple users within a single context.
356      *
357      * @param   approved_userlist   $userlist   The approved context and user information to delete information for.
358      */
359     public static function delete_data_for_users(approved_userlist $userlist) {
360         static::delete_groups_for_users($userlist, '');
361     }