MDL-62134 privacy: consistantly call components methods
[moodle.git] / privacy / classes / manager.php
CommitLineData
0f59848d
JD
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 * 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 */
24namespace core_privacy;
25use core_privacy\local\metadata\collection;
65abf2a3
MG
26use core_privacy\local\metadata\null_provider;
27use core_privacy\local\request\context_aware_provider;
0f59848d 28use core_privacy\local\request\contextlist_collection;
65abf2a3
MG
29use core_privacy\local\request\core_data_provider;
30use core_privacy\local\request\core_user_data_provider;
31use core_privacy\local\request\data_provider;
32use core_privacy\local\request\user_preference_provider;
33use \core_privacy\local\metadata\provider as metadata_provider;
0f59848d
JD
34
35defined('MOODLE_INTERNAL') || die();
36
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 */
112class 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.
65abf2a3 130 if ($this->component_implements($component, null_provider::class)) {
0f59848d
JD
131 return true;
132 }
502344a9
AN
133
134 if (static::is_empty_subsystem($component)) {
135 return true;
136 }
137
0f59848d 138 // Components which store user data must implement the local\metadata\provider and the local\request\data_provider.
65abf2a3
MG
139 if ($this->component_implements($component, metadata_provider::class) &&
140 $this->component_implements($component, data_provider::class)) {
0f59848d
JD
141 return true;
142 }
502344a9 143
0f59848d
JD
144 return false;
145 }
146
0f6fb936
AG
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 {
65abf2a3
MG
154 if ($this->component_implements($component, null_provider::class)) {
155 return static::component_class_callback($component, null_provider::class, 'get_reason', []);
0f6fb936
AG
156 } else {
157 throw new \coding_exception('Call to undefined method', 'Please only call this method on a null provider.');
158 }
159 }
160
502344a9
AN
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 }
174
175 return false;
176 }
177
0f59848d
JD
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) {
65abf2a3
MG
187 $componentmetadata = static::component_class_callback($component, metadata_provider::class,
188 'get_metadata', [new collection($component)]);
189 if ($componentmetadata !== null) {
190 $metadata[$component] = $componentmetadata;
0f59848d
JD
191 }
192 }
193 return $metadata;
194 }
195
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 {
56385279
AN
203 $progress = static::get_log_tracer();
204
205 $components = $this->get_component_list();
206 $a = (object) [
207 'total' => count($components),
208 'progress' => 0,
209 'component' => '',
210 'datetime' => userdate(time()),
211 ];
0f59848d 212 $clcollection = new contextlist_collection($userid);
56385279
AN
213
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);
65abf2a3
MG
220 $contextlist = static::component_class_callback($component, core_user_data_provider::class,
221 'get_contexts_for_userid', [$userid]);
222 if ($contextlist === null) {
0f59848d
JD
223 $contextlist = new local\request\contextlist();
224 }
225
226 // Each contextlist is tied to its respective component.
227 $contextlist->set_component($component);
228
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);
232
233 if (count($contextlist)) {
234 $clcollection->add_contextlist($contextlist);
235 }
236 }
56385279 237 $progress->output(get_string('trace:done', 'core_privacy'), 1);
0f59848d
JD
238
239 return $clcollection;
240 }
241
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) {
56385279
AN
253 $progress = static::get_log_tracer();
254
255 $a = (object) [
256 'total' => count($contextlistcollection),
257 'progress' => 0,
258 'component' => '',
259 'datetime' => userdate(time()),
260 ];
261
0f59848d 262 // Export for the various components/contexts.
56385279 263 $progress->output(get_string('trace:exportingapproved', 'core_privacy', $a), 1);
0f59848d 264 foreach ($contextlistcollection as $approvedcontextlist) {
56385279 265
0f59848d
JD
266 if (!$approvedcontextlist instanceof \core_privacy\local\request\approved_contextlist) {
267 throw new \moodle_exception('Contextlist must be an approved_contextlist');
268 }
269
270 $component = $approvedcontextlist->get_component();
56385279
AN
271 $a->component = $component;
272 $a->progress++;
273 $a->datetime = userdate(time());
274 $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
275
0f59848d 276 // Core user data providers.
65abf2a3 277 if ($this->component_implements($component, core_user_data_provider::class)) {
0f59848d
JD
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.
65abf2a3
MG
281 static::component_class_callback($component, core_user_data_provider::class,
282 'export_user_data', [$approvedcontextlist]);
0f59848d 283 }
65abf2a3 284 } else if (!$this->component_implements($component, context_aware_provider::class)) {
0f59848d
JD
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 }
56385279 289 $progress->output(get_string('trace:done', 'core_privacy'), 1);
0f59848d
JD
290
291 // Check each component for non contextlist items too.
56385279
AN
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);
0f59848d 302 // Core user preference providers.
65abf2a3
MG
303 static::component_class_callback($component, user_preference_provider::class,
304 'export_user_preferences', [$contextlistcollection->get_userid()]);
0f59848d 305
e4a37fbe
JD
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.
65abf2a3
MG
308 static::component_class_callback($component, context_aware_provider::class,
309 'export_context_data', [$contextlistcollection]);
9faf51a7 310 }
56385279
AN
311 $progress->output(get_string('trace:done', 'core_privacy'), 1);
312
313 $progress->output(get_string('trace:finalisingexport', 'core_privacy'), 1);
314 $location = local\request\writer::with_context(\context_system::instance())->finalise_content();
9faf51a7 315
56385279
AN
316 $progress->output(get_string('trace:exportcomplete', 'core_privacy'), 1);
317 return $location;
0f59848d
JD
318 }
319
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 */
e98f0cf7 331 public function delete_data_for_user(contextlist_collection $contextlistcollection) {
56385279
AN
332 $progress = static::get_log_tracer();
333
334 $a = (object) [
335 'total' => count($contextlistcollection),
336 'progress' => 0,
337 'component' => '',
338 'datetime' => userdate(time()),
339 ];
340
0f59848d 341 // Delete the data.
56385279 342 $progress->output(get_string('trace:deletingapproved', 'core_privacy', $a), 1);
0f59848d
JD
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 }
347
56385279
AN
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);
353
65abf2a3
MG
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]);
0f59848d
JD
359 }
360
361 // Delete any shared user data it doesn't know about.
e98f0cf7 362 local\request\helper::delete_data_for_user($approvedcontextlist);
0f59848d 363 }
56385279 364 $progress->output(get_string('trace:done', 'core_privacy'), 1);
0f59848d
JD
365 }
366
367 /**
70f09234 368 * Delete all use data which matches the specified deletion criteria.
0f59848d 369 *
65abf2a3 370 * @param \context $context The specific context to delete data for.
0f59848d 371 */
e98f0cf7 372 public function delete_data_for_all_users_in_context(\context $context) {
56385279
AN
373 $progress = static::get_log_tracer();
374
375 $components = $this->get_component_list();
376 $a = (object) [
377 'total' => count($components),
378 'progress' => 0,
379 'component' => '',
380 'datetime' => userdate(time()),
381 ];
382
383 $progress->output(get_string('trace:deletingcontext', 'core_privacy', $a), 1);
0f59848d 384 foreach ($this->get_component_list() as $component) {
56385279
AN
385 $a->component = $component;
386 $a->progress++;
387 $a->datetime = userdate(time());
388 $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);
389
65abf2a3
MG
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]);
0f59848d
JD
394
395 // Delete any shared user data it doesn't know about.
e98f0cf7 396 local\request\helper::delete_data_for_all_users_in_context($component, $context);
0f59848d 397 }
56385279 398 $progress->output(get_string('trace:done', 'core_privacy'), 1);
0f59848d
JD
399 }
400
0f59848d
JD
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() {
66f2da2e 407 $components = array_keys(array_reduce(\core_component::get_component_list(), function($carry, $item) {
6e6ba823
JD
408 return array_merge($carry, $item);
409 }, []));
66f2da2e
AN
410 $components[] = 'core';
411
412 return $components;
0f59848d
JD
413 }
414
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 }
424
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) {
65abf2a3 432 return "$component\\privacy\\provider";
0f59848d
JD
433 }
434
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 }
4f9f035a
AN
451
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 }
466
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 }
481
482 return null;
483 }
56385279
AN
484
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 }
496
497 return new \text_progress_trace();
498 }
0f59848d 499}