65300686b84fc423a7e505dd5850581c4fbc113d
[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         }
127         if (static::is_empty_subsystem($component)) {
128             return true;
129         }
131         // Components which store user data must implement the local\metadata\provider and the local\request\data_provider.
132         if ($this->component_implements($component, \core_privacy\local\metadata\provider::class) &&
133             $this->component_implements($component, \core_privacy\local\request\data_provider::class)) {
134             return true;
135         }
137         return false;
138     }
140     /**
141      * Retrieve the reason for implementing the null provider interface.
142      *
143      * @param  string $component Frankenstyle component name.
144      * @return string The key to retrieve the language string for the null provider reason.
145      */
146     public function get_null_provider_reason(string $component) : string {
147         if ($this->component_implements($component, \core_privacy\local\metadata\null_provider::class)) {
148             return $this->get_provider_classname($component)::get_reason();
149         } else {
150             throw new \coding_exception('Call to undefined method', 'Please only call this method on a null provider.');
151         }
152     }
154     /**
155      * Return whether this is an 'empty' subsystem - that is, a subsystem without a directory.
156      *
157      * @param  string $component Frankenstyle component name.
158      * @return string The key to retrieve the language string for the null provider reason.
159      */
160     public static function is_empty_subsystem($component) {
161         if (strpos($component, 'core_') === 0) {
162             if (null === \core_component::get_subsystem_directory(substr($component, 5))) {
163                 // This is a subsystem without a directory.
164                 return true;
165             }
166         }
168         return false;
169     }
171     /**
172      * Get the privacy metadata for all components.
173      *
174      * @return collection[] The array of collection objects, indexed by frankenstyle component name.
175      */
176     public function get_metadata_for_components() : array {
177         // Get the metadata, and put into an assoc array indexed by component name.
178         $metadata = [];
179         foreach ($this->get_component_list() as $component) {
180             if ($this->component_implements($component, \core_privacy\local\metadata\provider::class)) {
181                 $metadata[$component] = $this->get_provider_classname($component)::get_metadata(new collection($component));
182             }
183         }
184         return $metadata;
185     }
187     /**
188      * Gets a collection of resultset objects for all components.
189      *
190      * @param int $userid the id of the user we're fetching contexts for.
191      * @return contextlist_collection the collection of contextlist items for the respective components.
192      */
193     public function get_contexts_for_userid(int $userid) : contextlist_collection {
194         $progress = static::get_log_tracer();
196         $components = $this->get_component_list();
197         $a = (object) [
198             'total' => count($components),
199             'progress' => 0,
200             'component' => '',
201             'datetime' => userdate(time()),
202         ];
203         $clcollection = new contextlist_collection($userid);
205         $progress->output(get_string('trace:fetchcomponents', 'core_privacy', $a), 1);
206         foreach ($components as $component) {
207             $a->component = $component;
208             $a->progress++;
209             $a->datetime = userdate(time());
210             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
211             if ($this->component_implements($component, \core_privacy\local\request\core_user_data_provider::class)) {
212                 $contextlist = $this->get_provider_classname($component)::get_contexts_for_userid($userid);
213             } else {
214                 $contextlist = new local\request\contextlist();
215             }
217             // Each contextlist is tied to its respective component.
218             $contextlist->set_component($component);
220             // Add contexts that the component may not know about.
221             // Example of these include activity completion which modules do not know about themselves.
222             $contextlist = local\request\helper::add_shared_contexts_to_contextlist_for($userid, $contextlist);
224             if (count($contextlist)) {
225                 $clcollection->add_contextlist($contextlist);
226             }
227         }
228         $progress->output(get_string('trace:done', 'core_privacy'), 1);
230         return $clcollection;
231     }
233     /**
234      * Export all user data for the specified approved_contextlist items.
235      *
236      * Note: userid and component are stored in each respective approved_contextlist.
237      *
238      * @param contextlist_collection $contextlistcollection the collection of contextlists for all components.
239      * @return string the location of the exported data.
240      * @throws \moodle_exception if the contextlist_collection does not contain all approved_contextlist items or if one of the
241      * approved_contextlists' components is not a core_data_provider.
242      */
243     public function export_user_data(contextlist_collection $contextlistcollection) {
244         $progress = static::get_log_tracer();
246         $a = (object) [
247             'total' => count($contextlistcollection),
248             'progress' => 0,
249             'component' => '',
250             'datetime' => userdate(time()),
251         ];
253         // Export for the various components/contexts.
254         $progress->output(get_string('trace:exportingapproved', 'core_privacy', $a), 1);
255         foreach ($contextlistcollection as $approvedcontextlist) {
257             if (!$approvedcontextlist instanceof \core_privacy\local\request\approved_contextlist) {
258                 throw new \moodle_exception('Contextlist must be an approved_contextlist');
259             }
261             $component = $approvedcontextlist->get_component();
262             $a->component = $component;
263             $a->progress++;
264             $a->datetime = userdate(time());
265             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
267             // Core user data providers.
268             if ($this->component_implements($component, \core_privacy\local\request\core_user_data_provider::class)) {
269                 if (count($approvedcontextlist)) {
270                     // This plugin has data it knows about. It is responsible for storing basic data about anything it is
271                     // told to export.
272                     $this->get_provider_classname($component)::export_user_data($approvedcontextlist);
273                 }
274             } else if (!$this->component_implements($component, \core_privacy\local\request\context_aware_provider::class)) {
275                 // This plugin does not know that it has data - export the shared data it doesn't know about.
276                 local\request\helper::export_data_for_null_provider($approvedcontextlist);
277             }
278         }
279         $progress->output(get_string('trace:done', 'core_privacy'), 1);
281         // Check each component for non contextlist items too.
282         $components = $this->get_component_list();
283         $a->total = count($components);
284         $a->progress = 0;
285         $a->datetime = userdate(time());
286         $progress->output(get_string('trace:exportingrelated', 'core_privacy', $a), 1);
287         foreach ($components as $component) {
288             $a->component = $component;
289             $a->progress++;
290             $a->datetime = userdate(time());
291             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
292             // Core user preference providers.
293             if ($this->component_implements($component, \core_privacy\local\request\user_preference_provider::class)) {
294                 $this->get_provider_classname($component)::export_user_preferences($contextlistcollection->get_userid());
295             }
297             // Contextual information providers. Give each component a chance to include context information based on the
298             // existence of a child context in the contextlist_collection.
299             if ($this->component_implements($component, \core_privacy\local\request\context_aware_provider::class)) {
300                 $this->get_provider_classname($component)::export_context_data($contextlistcollection);
301             }
302         }
303         $progress->output(get_string('trace:done', 'core_privacy'), 1);
305         $progress->output(get_string('trace:finalisingexport', 'core_privacy'), 1);
306         $location = local\request\writer::with_context(\context_system::instance())->finalise_content();
308         $progress->output(get_string('trace:exportcomplete', 'core_privacy'), 1);
309         return $location;
310     }
312     /**
313      * Delete all user data for approved contexts lists provided in the collection.
314      *
315      * This call relates to the forgetting of an entire user.
316      *
317      * Note: userid and component are stored in each respective approved_contextlist.
318      *
319      * @param contextlist_collection $contextlistcollection the collections of approved_contextlist items on which to call deletion.
320      * @throws \moodle_exception if the contextlist_collection doesn't contain all approved_contextlist items, or if the component
321      * for an approved_contextlist isn't a core provider.
322      */
323     public function delete_data_for_user(contextlist_collection $contextlistcollection) {
324         $progress = static::get_log_tracer();
326         $a = (object) [
327             'total' => count($contextlistcollection),
328             'progress' => 0,
329             'component' => '',
330             'datetime' => userdate(time()),
331         ];
333         // Delete the data.
334         $progress->output(get_string('trace:deletingapproved', 'core_privacy', $a), 1);
335         foreach ($contextlistcollection as $approvedcontextlist) {
336             if (!$approvedcontextlist instanceof \core_privacy\local\request\approved_contextlist) {
337                 throw new \moodle_exception('Contextlist must be an approved_contextlist');
338             }
340             $component = $approvedcontextlist->get_component();
341             $a->component = $component;
342             $a->progress++;
343             $a->datetime = userdate(time());
344             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
346             if ($this->component_is_core_provider($component)) {
347                 if (count($approvedcontextlist)) {
348                     // The component knows about data that it has.
349                     // Have it delete its own data.
350                     $this->get_provider_classname($approvedcontextlist->get_component())::delete_data_for_user($approvedcontextlist);
351                 }
352             }
354             // Delete any shared user data it doesn't know about.
355             local\request\helper::delete_data_for_user($approvedcontextlist);
356         }
357         $progress->output(get_string('trace:done', 'core_privacy'), 1);
358     }
360     /**
361      * Delete all use data which matches the specified deletion criteria.
362      *
363      * @param   context         $context   The specific context to delete data for.
364      */
365     public function delete_data_for_all_users_in_context(\context $context) {
366         $progress = static::get_log_tracer();
368         $components = $this->get_component_list();
369         $a = (object) [
370             'total' => count($components),
371             'progress' => 0,
372             'component' => '',
373             'datetime' => userdate(time()),
374         ];
376         $progress->output(get_string('trace:deletingcontext', 'core_privacy', $a), 1);
377         foreach ($this->get_component_list() as $component) {
378             $a->component = $component;
379             $a->progress++;
380             $a->datetime = userdate(time());
381             $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
383             if ($this->component_implements($component, \core_privacy\local\request\core_user_data_provider::class)) {
384                 // This component knows about specific data that it owns.
385                 // Have it delete all of that user data for the context.
386                 $this->get_provider_classname($component)::delete_data_for_all_users_in_context($context);
387             }
389             // Delete any shared user data it doesn't know about.
390             local\request\helper::delete_data_for_all_users_in_context($component, $context);
391         }
392         $progress->output(get_string('trace:done', 'core_privacy'), 1);
393     }
395     /**
396      * Check whether the specified component is a core provider.
397      *
398      * @param string $component the frankenstyle component name.
399      * @return bool true if the component is a core provider, false otherwise.
400      */
401     protected function component_is_core_provider($component) {
402         return $this->component_implements($component, \core_privacy\local\request\core_data_provider::class);
403     }
405     /**
406      * Returns a list of frankenstyle names of core components (plugins and subsystems).
407      *
408      * @return array the array of frankenstyle component names.
409      */
410     protected function get_component_list() {
411         $components = array_keys(array_reduce(\core_component::get_component_list(), function($carry, $item) {
412             return array_merge($carry, $item);
413         }, []));
414         $components[] = 'core';
416         return $components;
417     }
419     /**
420      * Return the fully qualified provider classname for the component.
421      *
422      * @param string $component the frankenstyle component name.
423      * @return string the fully qualified provider classname.
424      */
425     protected function get_provider_classname($component) {
426         return static::get_provider_classname_for_component($component);
427     }
429     /**
430      * Return the fully qualified provider classname for the component.
431      *
432      * @param string $component the frankenstyle component name.
433      * @return string the fully qualified provider classname.
434      */
435     public static function get_provider_classname_for_component(string $component) {
436         return "$component\privacy\provider";
437     }
439     /**
440      * Checks whether the component's provider class implements the specified interface.
441      * This can either be implemented directly, or by implementing a descendant (extension) of the specified interface.
442      *
443      * @param string $component the frankenstyle component name.
444      * @param string $interface the name of the interface we want to check.
445      * @return bool True if an implementation was found, false otherwise.
446      */
447     protected function component_implements(string $component, string $interface) : bool {
448         $providerclass = $this->get_provider_classname($component);
449         if (class_exists($providerclass)) {
450             $rc = new \ReflectionClass($providerclass);
451             return $rc->implementsInterface($interface);
452         }
453         return false;
454     }
456     /**
457      * Call the named method with the specified params on any plugintype implementing the relevant interface.
458      *
459      * @param   string  $plugintype The plugingtype to check
460      * @param   string  $interface The interface to implement
461      * @param   string  $methodname The method to call
462      * @param   array   $params The params to call
463      */
464     public static function plugintype_class_callback(string $plugintype, string $interface, string $methodname, array $params) {
465         $components = \core_component::get_plugin_list($plugintype);
466         foreach (array_keys($components) as $component) {
467             static::component_class_callback("{$plugintype}_{$component}", $interface, $methodname, $params);
468         }
469     }
471     /**
472      * Call the named method with the specified params on the supplied component if it implements the relevant interface on its provider.
473      *
474      * @param   string  $component The component to call
475      * @param   string  $interface The interface to implement
476      * @param   string  $methodname The method to call
477      * @param   array   $params The params to call
478      * @return  mixed
479      */
480     public static function component_class_callback(string $component, string $interface, string $methodname, array $params) {
481         $classname = static::get_provider_classname_for_component($component);
482         if (class_exists($classname) && is_subclass_of($classname, $interface)) {
483             return component_class_callback($classname, $methodname, $params);
484         }
486         return null;
487     }
489     /**
490      * Get the tracer used for logging.
491      *
492      * The text tracer is used except for unit tests.
493      *
494      * @return  \progress_trace
495      */
496     protected static function get_log_tracer() {
497         if (PHPUNIT_TEST) {
498             return new \null_progress_trace();
499         }
501         return new \text_progress_trace();
502     }