MDL-62371 core_privacy: Add support for progress trace
[moodle.git] / privacy / classes / manager.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  * This file contains the core_privacy\manager class.
19  *
20  * @package core_privacy
21  * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
22  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
24 namespace core_privacy;
25 use core_privacy\local\metadata\collection;
26 use core_privacy\local\request\contextlist_collection;
28 defined('MOODLE_INTERNAL') || die();
30 /**
31  * The core_privacy\manager class, providing a facade to describe, export and delete personal data across Moodle and its components.
32  *
33  * This class is responsible for communicating with and collating privacy data from all relevant components, where relevance is
34  * determined through implementations of specific marker interfaces. These marker interfaces describe the responsibilities (in terms
35  * of personal data storage) as well as the relationship between the component and the core_privacy subsystem.
36  *
37  * The interface hierarchy is as follows:
38  * ├── local\metadata\null_provider
39  * ├── local\metadata\provider
40  * ├── local\request\data_provider
41  *     └── local\request\core_data_provider
42  *         └── local\request\core_user_data_provider
43  *             └── local\request\plugin\provider
44  *             └── local\request\subsystem\provider
45  *         └── local\request\user_preference_provider
46  *     └── local\request\shared_data_provider
47  *         └── local\request\plugin\subsystem_provider
48  *         └── local\request\plugin\subplugin_provider
49  *         └── local\request\subsystem\plugin_provider
50  *
51  * Describing personal data:
52  * -------------------------
53  * All components must state whether they store personal data (and DESCRIBE it) by implementing one of the metadata providers:
54  * - local\metadata\null_provider (indicating they don't store personal data)
55  * - local\metadata\provider (indicating they do store personal data, and describing it)
56  *
57  * The manager requests metadata for all Moodle components implementing the local\metadata\provider interface.
58  *
59  * Export and deletion of personal data:
60  * -------------------------------------
61  * Those components storing personal data need to provide EXPORT and DELETION of this data by implementing a request provider.
62  * Which provider implementation depends on the nature of the component; whether it's a sub-component and which components it
63  * stores data for.
64  *
65  * Export and deletion for sub-components (or any component storing data on behalf of another component) is managed by the parent
66  * component. If a component contains sub-components, it must ask those sub-components to provide the relevant data. Only certain
67  * 'core provider' components are called directly from the manager and these must provide the personal data stored by both
68  * themselves, and by all sub-components. Because of this hierarchical structure, the core_privacy\manager needs to know which
69  * components are to be called directly by core: these are called core data providers. The providers implemented by sub-components
70  * are called shared data providers.
71  *
72  * The following are interfaces are not implemented directly, but are marker interfaces uses to classify components by nature:
73  * - local\request\data_provider:
74  *      Not implemented directly. Used to classify components storing personal data of some kind. Includes both components storing
75  *      personal data for themselves and on behalf of other components.
76  *      Include: local\request\core_data_provider and local\request\shared_data_provider.
77  * - local\request\core_data_provider:
78  *      Not implemented directly. Used to classify components storing personal data for themselves and which are to be called by the
79  *      core_privacy subsystem directly.
80  *      Includes: local\request\core_user_data_provider and local\request\user_preference_provider.
81  * - local\request\core_user_data_provider:
82  *      Not implemented directly. Used to classify components storing personal data for themselves, which are either a plugin or
83  *      subsystem and which are to be called by the core_privacy subsystem directly.
84  *      Includes: local\request\plugin\provider and local\request\subsystem\provider.
85  * - local\request\shared_data_provider:
86  *      Not implemented directly. Used to classify components storing personal data on behalf of other components and which are
87  *      called by the owning component directly.
88  *      Includes: local\request\plugin\subsystem_provider, local\request\plugin\subplugin_provider and local\request\subsystem\plugin_provider
89  *
90  * The manager only requests the export or deletion of personal data for components implementing the local\request\core_data_provider
91  * interface or one of its descendants; local\request\plugin\provider, local\request\subsystem\provider or local\request\user_preference_provider.
92  * Implementing one of these signals to the core_privacy subsystem that the component must be queried directly from the manager.
93  *
94  * Any component using another component to store personal data on its behalf, is responsible for making the relevant call to
95  * that component's relevant shared_data_provider class.
96  *
97  * For example:
98  * The manager calls a core_data_provider component (e.g. mod_assign) which, in turn, calls relevant subplugins or subsystems
99  * (which assign uses to store personal data) to get that data. All data for assign and its sub-components is aggregated by assign
100  * and returned to the core_privacy subsystem.
101  *
102  * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
103  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
104  */
105 class manager {
106     /**
107      * Checks whether the given component is compliant with the core_privacy API.
108      * To be considered compliant, a component must declare whether (and where) it stores personal data.
109      *
110      * Components which do store personal data must:
111      * - Have implemented the core_privacy\local\metadata\provider interface (to describe the data it stores) and;
112      * - Have implemented the core_privacy\local\request\data_provider interface (to facilitate export of personal data)
113      * - Have implemented the core_privacy\local\request\deleter interface
114      *
115      * Components which do not store personal data must:
116      * - Have implemented the core_privacy\local\metadata\null_provider interface to signal that they don't store personal data.
117      *
118      * @param string $component frankenstyle component name, e.g. 'mod_assign'
119      * @return bool true if the component is compliant, false otherwise.
120      */
121     public function component_is_compliant(string $component) : bool {
122         // Components which don't store user data need only implement the null_provider.
123         if ($this->component_implements($component, \core_privacy\local\metadata\null_provider::class)) {
124             return true;
125         }
126         // Components which store user data must implement the local\metadata\provider and the local\request\data_provider.
127         if ($this->component_implements($component, \core_privacy\local\metadata\provider::class) &&
128             $this->component_implements($component, \core_privacy\local\request\data_provider::class)) {
129             return true;
130         }
131         return false;
132     }
134     /**
135      * Retrieve the reason for implementing the null provider interface.
136      *
137      * @param  string $component Frankenstyle component name.
138      * @return string The key to retrieve the language string for the null provider reason.
139      */
140     public function get_null_provider_reason(string $component) : string {
141         if ($this->component_implements($component, \core_privacy\local\metadata\null_provider::class)) {
142             return $this->get_provider_classname($component)::get_reason();
143         } else {
144             throw new \coding_exception('Call to undefined method', 'Please only call this method on a null provider.');
145         }
146     }
148     /**
149      * Get the privacy metadata for all components.
150      *
151      * @return collection[] The array of collection objects, indexed by frankenstyle component name.
152      */
153     public function get_metadata_for_components() : array {
154         // Get the metadata, and put into an assoc array indexed by component name.
155         $metadata = [];
156         foreach ($this->get_component_list() as $component) {
157             if ($this->component_implements($component, \core_privacy\local\metadata\provider::class)) {
158                 $metadata[$component] = $this->get_provider_classname($component)::get_metadata(new collection($component));
159             }
160         }
161         return $metadata;
162     }
164     /**
165      * Gets a collection of resultset objects for all components.
166      *
167      * @param int $userid the id of the user we're fetching contexts for.
168      * @return contextlist_collection the collection of contextlist items for the respective components.
169      */
170     public function get_contexts_for_userid(int $userid) : contextlist_collection {
171         $progress = static::get_log_tracer();
173         $components = $this->get_component_list();
174         $a = (object) [
175             'total' => count($components),
176             'progress' => 0,
177             'component' => '',
178             'datetime' => userdate(time()),
179         ];
180         $clcollection = new contextlist_collection($userid);
182         $progress->output(get_string('trace:fetchcomponents', 'core_privacy', $a), 1);
183         foreach ($components as $component) {
184             $a->component = $component;
185             $a->progress++;
186             $a->datetime = userdate(time());
187             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
188             if ($this->component_implements($component, \core_privacy\local\request\core_user_data_provider::class)) {
189                 $contextlist = $this->get_provider_classname($component)::get_contexts_for_userid($userid);
190             } else {
191                 $contextlist = new local\request\contextlist();
192             }
194             // Each contextlist is tied to its respective component.
195             $contextlist->set_component($component);
197             // Add contexts that the component may not know about.
198             // Example of these include activity completion which modules do not know about themselves.
199             $contextlist = local\request\helper::add_shared_contexts_to_contextlist_for($userid, $contextlist);
201             if (count($contextlist)) {
202                 $clcollection->add_contextlist($contextlist);
203             }
204         }
205         $progress->output(get_string('trace:done', 'core_privacy'), 1);
207         return $clcollection;
208     }
210     /**
211      * Export all user data for the specified approved_contextlist items.
212      *
213      * Note: userid and component are stored in each respective approved_contextlist.
214      *
215      * @param contextlist_collection $contextlistcollection the collection of contextlists for all components.
216      * @return string the location of the exported data.
217      * @throws \moodle_exception if the contextlist_collection does not contain all approved_contextlist items or if one of the
218      * approved_contextlists' components is not a core_data_provider.
219      */
220     public function export_user_data(contextlist_collection $contextlistcollection) {
221         $progress = static::get_log_tracer();
223         $a = (object) [
224             'total' => count($contextlistcollection),
225             'progress' => 0,
226             'component' => '',
227             'datetime' => userdate(time()),
228         ];
230         // Export for the various components/contexts.
231         $progress->output(get_string('trace:exportingapproved', 'core_privacy', $a), 1);
232         foreach ($contextlistcollection as $approvedcontextlist) {
234             if (!$approvedcontextlist instanceof \core_privacy\local\request\approved_contextlist) {
235                 throw new \moodle_exception('Contextlist must be an approved_contextlist');
236             }
238             $component = $approvedcontextlist->get_component();
239             $a->component = $component;
240             $a->progress++;
241             $a->datetime = userdate(time());
242             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
244             // Core user data providers.
245             if ($this->component_implements($component, \core_privacy\local\request\core_user_data_provider::class)) {
246                 if (count($approvedcontextlist)) {
247                     // This plugin has data it knows about. It is responsible for storing basic data about anything it is
248                     // told to export.
249                     $this->get_provider_classname($component)::export_user_data($approvedcontextlist);
250                 }
251             } else if (!$this->component_implements($component, \core_privacy\local\request\context_aware_provider::class)) {
252                 // This plugin does not know that it has data - export the shared data it doesn't know about.
253                 local\request\helper::export_data_for_null_provider($approvedcontextlist);
254             }
255         }
256         $progress->output(get_string('trace:done', 'core_privacy'), 1);
258         // Check each component for non contextlist items too.
259         $components = $this->get_component_list();
260         $a->total = count($components);
261         $a->progress = 0;
262         $a->datetime = userdate(time());
263         $progress->output(get_string('trace:exportingrelated', 'core_privacy', $a), 1);
264         foreach ($components as $component) {
265             $a->component = $component;
266             $a->progress++;
267             $a->datetime = userdate(time());
268             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
269             // Core user preference providers.
270             if ($this->component_implements($component, \core_privacy\local\request\user_preference_provider::class)) {
271                 $this->get_provider_classname($component)::export_user_preferences($contextlistcollection->get_userid());
272             }
274             // Contextual information providers. Give each component a chance to include context information based on the
275             // existence of a child context in the contextlist_collection.
276             if ($this->component_implements($component, \core_privacy\local\request\context_aware_provider::class)) {
277                 $this->get_provider_classname($component)::export_context_data($contextlistcollection);
278             }
279         }
280         $progress->output(get_string('trace:done', 'core_privacy'), 1);
282         $progress->output(get_string('trace:finalisingexport', 'core_privacy'), 1);
283         $location = local\request\writer::with_context(\context_system::instance())->finalise_content();
285         $progress->output(get_string('trace:exportcomplete', 'core_privacy'), 1);
286         return $location;
287     }
289     /**
290      * Delete all user data for approved contexts lists provided in the collection.
291      *
292      * This call relates to the forgetting of an entire user.
293      *
294      * Note: userid and component are stored in each respective approved_contextlist.
295      *
296      * @param contextlist_collection $contextlistcollection the collections of approved_contextlist items on which to call deletion.
297      * @throws \moodle_exception if the contextlist_collection doesn't contain all approved_contextlist items, or if the component
298      * for an approved_contextlist isn't a core provider.
299      */
300     public function delete_data_for_user(contextlist_collection $contextlistcollection) {
301         $progress = static::get_log_tracer();
303         $a = (object) [
304             'total' => count($contextlistcollection),
305             'progress' => 0,
306             'component' => '',
307             'datetime' => userdate(time()),
308         ];
310         // Delete the data.
311         $progress->output(get_string('trace:deletingapproved', 'core_privacy', $a), 1);
312         foreach ($contextlistcollection as $approvedcontextlist) {
313             if (!$approvedcontextlist instanceof \core_privacy\local\request\approved_contextlist) {
314                 throw new \moodle_exception('Contextlist must be an approved_contextlist');
315             }
317             $component = $approvedcontextlist->get_component();
318             $a->component = $component;
319             $a->progress++;
320             $a->datetime = userdate(time());
321             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
323             if ($this->component_is_core_provider($component)) {
324                 if (count($approvedcontextlist)) {
325                     // The component knows about data that it has.
326                     // Have it delete its own data.
327                     $this->get_provider_classname($approvedcontextlist->get_component())::delete_data_for_user($approvedcontextlist);
328                 }
329             }
331             // Delete any shared user data it doesn't know about.
332             local\request\helper::delete_data_for_user($approvedcontextlist);
333         }
334         $progress->output(get_string('trace:done', 'core_privacy'), 1);
335     }
337     /**
338      * Delete all use data which matches the specified deletion criteria.
339      *
340      * @param   context         $context   The specific context to delete data for.
341      */
342     public function delete_data_for_all_users_in_context(\context $context) {
343         $progress = static::get_log_tracer();
345         $components = $this->get_component_list();
346         $a = (object) [
347             'total' => count($components),
348             'progress' => 0,
349             'component' => '',
350             'datetime' => userdate(time()),
351         ];
353         $progress->output(get_string('trace:deletingcontext', 'core_privacy', $a), 1);
354         foreach ($this->get_component_list() as $component) {
355             $a->component = $component;
356             $a->progress++;
357             $a->datetime = userdate(time());
358             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
360             if ($this->component_implements($component, \core_privacy\local\request\core_user_data_provider::class)) {
361                 // This component knows about specific data that it owns.
362                 // Have it delete all of that user data for the context.
363                 $this->get_provider_classname($component)::delete_data_for_all_users_in_context($context);
364             }
366             // Delete any shared user data it doesn't know about.
367             local\request\helper::delete_data_for_all_users_in_context($component, $context);
368         }
369         $progress->output(get_string('trace:done', 'core_privacy'), 1);
370     }
372     /**
373      * Check whether the specified component is a core provider.
374      *
375      * @param string $component the frankenstyle component name.
376      * @return bool true if the component is a core provider, false otherwise.
377      */
378     protected function component_is_core_provider($component) {
379         return $this->component_implements($component, \core_privacy\local\request\core_data_provider::class);
380     }
382     /**
383      * Returns a list of frankenstyle names of core components (plugins and subsystems).
384      *
385      * @return array the array of frankenstyle component names.
386      */
387     protected function get_component_list() {
388         return array_keys(array_reduce(\core_component::get_component_list(), function($carry, $item) {
389             return array_merge($carry, $item);
390         }, []));
391     }
393     /**
394      * Return the fully qualified provider classname for the component.
395      *
396      * @param string $component the frankenstyle component name.
397      * @return string the fully qualified provider classname.
398      */
399     protected function get_provider_classname($component) {
400         return static::get_provider_classname_for_component($component);
401     }
403     /**
404      * Return the fully qualified provider classname for the component.
405      *
406      * @param string $component the frankenstyle component name.
407      * @return string the fully qualified provider classname.
408      */
409     public static function get_provider_classname_for_component(string $component) {
410         return "$component\privacy\provider";
411     }
413     /**
414      * Checks whether the component's provider class implements the specified interface.
415      * This can either be implemented directly, or by implementing a descendant (extension) of the specified interface.
416      *
417      * @param string $component the frankenstyle component name.
418      * @param string $interface the name of the interface we want to check.
419      * @return bool True if an implementation was found, false otherwise.
420      */
421     protected function component_implements(string $component, string $interface) : bool {
422         $providerclass = $this->get_provider_classname($component);
423         if (class_exists($providerclass)) {
424             $rc = new \ReflectionClass($providerclass);
425             return $rc->implementsInterface($interface);
426         }
427         return false;
428     }
430     /**
431      * Call the named method with the specified params on any plugintype implementing the relevant interface.
432      *
433      * @param   string  $plugintype The plugingtype to check
434      * @param   string  $interface The interface to implement
435      * @param   string  $methodname The method to call
436      * @param   array   $params The params to call
437      */
438     public static function plugintype_class_callback(string $plugintype, string $interface, string $methodname, array $params) {
439         $components = \core_component::get_plugin_list($plugintype);
440         foreach (array_keys($components) as $component) {
441             static::component_class_callback("{$plugintype}_{$component}", $interface, $methodname, $params);
442         }
443     }
445     /**
446      * Call the named method with the specified params on the supplied component if it implements the relevant interface on its provider.
447      *
448      * @param   string  $component The component to call
449      * @param   string  $interface The interface to implement
450      * @param   string  $methodname The method to call
451      * @param   array   $params The params to call
452      * @return  mixed
453      */
454     public static function component_class_callback(string $component, string $interface, string $methodname, array $params) {
455         $classname = static::get_provider_classname_for_component($component);
456         if (class_exists($classname) && is_subclass_of($classname, $interface)) {
457             return component_class_callback($classname, $methodname, $params);
458         }
460         return null;
461     }
463     /**
464      * Get the tracer used for logging.
465      *
466      * The text tracer is used except for unit tests.
467      *
468      * @return  \progress_trace
469      */
470     protected static function get_log_tracer() {
471         if (PHPUNIT_TEST) {
472             return new \null_progress_trace();
473         }
475         return new \text_progress_trace();
476     }