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