Merge branch 'MDL-63333_master' of git://github.com/markn86/moodle
[moodle.git] / admin / tool / dataprivacy / classes / data_registry.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  * Data registry business logic methods. Mostly internal stuff.
19  *
20  * All methods should be considered part of the internal tool_dataprivacy API
21  * unless something different is specified.
22  *
23  * @package    tool_dataprivacy
24  * @copyright  2018 David Monllao
25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
28 namespace tool_dataprivacy;
30 use coding_exception;
31 use core\persistent;
33 defined('MOODLE_INTERNAL') || die();
35 /**
36  * Data registry business logic methods. Mostly internal stuff.
37  *
38  * @copyright  2018 David Monllao
39  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40  */
41 class data_registry {
43     /**
44      * @var array Inheritance between context levels.
45      */
46     private static $contextlevelinheritance = [
47         CONTEXT_USER => [CONTEXT_SYSTEM],
48         CONTEXT_COURSECAT => [CONTEXT_SYSTEM],
49         CONTEXT_COURSE => [CONTEXT_COURSECAT, CONTEXT_SYSTEM],
50         CONTEXT_MODULE => [CONTEXT_COURSE, CONTEXT_COURSECAT, CONTEXT_SYSTEM],
51         CONTEXT_BLOCK => [CONTEXT_COURSE, CONTEXT_COURSECAT, CONTEXT_SYSTEM],
52     ];
54     /**
55      * Returns purpose and category var names from a context class name
56      *
57      * @param string $classname The context level's class.
58      * @param string $pluginname The name of the plugin associated with the context level.
59      * @return string[]
60      */
61     public static function var_names_from_context($classname, $pluginname = '') {
62         $pluginname = trim($pluginname);
63         if (!empty($pluginname)) {
64             $categoryvar = $classname . '_' . $pluginname . '_category';
65             $purposevar = $classname . '_' . $pluginname . '_purpose';
66         } else {
67             $categoryvar = $classname . '_category';
68             $purposevar = $classname . '_purpose';
69         }
70         return [
71             $purposevar,
72             $categoryvar
73         ];
74     }
76     /**
77      * Returns the default purpose id and category id for the provided context level.
78      *
79      * The caller code is responsible of checking that $contextlevel is an integer.
80      *
81      * @param int $contextlevel The context level.
82      * @param string $pluginname The name of the plugin associated with the context level.
83      * @return int[]|false[]
84      */
85     public static function get_defaults($contextlevel, $pluginname = '') {
87         $classname = \context_helper::get_class_for_level($contextlevel);
88         list($purposevar, $categoryvar) = self::var_names_from_context($classname, $pluginname);
90         $purposeid = get_config('tool_dataprivacy', $purposevar);
91         $categoryid = get_config('tool_dataprivacy', $categoryvar);
93         if (!empty($pluginname)) {
94             list($purposevar, $categoryvar) = self::var_names_from_context($classname);
95             // If the plugin-level doesn't have a default purpose set, try the context level.
96             if ($purposeid === false) {
97                 $purposeid = get_config('tool_dataprivacy', $purposevar);
98             }
100             // If the plugin-level doesn't have a default category set, try the context level.
101             if ($categoryid === false) {
102                 $categoryid = get_config('tool_dataprivacy', $categoryvar);
103             }
104         }
106         if (empty($purposeid)) {
107             $purposeid = false;
108         }
109         if (empty($categoryid)) {
110             $categoryid = false;
111         }
113         return [$purposeid, $categoryid];
114     }
116     /**
117      * Are data registry defaults set?
118      *
119      * At least the system defaults need to be set.
120      *
121      * @return bool
122      */
123     public static function defaults_set() {
124         list($purposeid, $categoryid) = self::get_defaults(CONTEXT_SYSTEM);
125         if (empty($purposeid) || empty($categoryid)) {
126             return false;
127         }
128         return true;
129     }
131     /**
132      * Returns all site categories that are visible to the current user.
133      *
134      * @return \core_course_category[]
135      */
136     public static function get_site_categories() {
137         global $DB;
139         if (method_exists('\core_course_category', 'get_all')) {
140             $categories = \core_course_category::get_all(['returnhidden' => true]);
141         } else {
142             // Fallback (to be removed once this gets integrated into master).
143             $ids = $DB->get_fieldset_select('course_categories', 'id', '');
144             $categories = \core_course_category::get_many($ids);
145         }
147         foreach ($categories as $key => $category) {
148             if (!$category->is_uservisible()) {
149                 unset($categories[$key]);
150             }
151         }
152         return $categories;
153     }
155     /**
156      * Returns the roles assigned to the provided level.
157      *
158      * Important to note that it returns course-level assigned roles
159      * if the provided context level is below course.
160      *
161      * @param \context $context
162      * @return array
163      */
164     public static function get_subject_scope(\context $context) {
166         if ($contextcourse = $context->get_course_context(false)) {
167             // Below course level we look at module or block level roles + course-assigned roles.
168             $courseroles = get_roles_used_in_context($contextcourse, false);
169             $roles = $courseroles + get_roles_used_in_context($context, false);
170         } else {
171             // We list category + system for others (we don't work with user instances so no need to work about them).
172             $roles = get_roles_used_in_context($context);
173         }
175         return array_map(function($role) {
176             if ($role->name) {
177                 return $role->name;
178             } else {
179                 return $role->shortname;
180             }
181         }, $roles);
182     }
184     /**
185      * Returns the effective value given a context instance
186      *
187      * @param \context $context
188      * @param string $element 'category' or 'purpose'
189      * @param int|false $forcedvalue Use this value as if this was this context instance value.
190      * @return persistent|false It return a 'purpose' instance or a 'category' instance, depending on $element
191      */
192     public static function get_effective_context_value(\context $context, $element, $forcedvalue=false) {
194         if ($element !== 'purpose' && $element !== 'category') {
195             throw new coding_exception('Only \'purpose\' and \'category\' are supported.');
196         }
197         $fieldname = $element . 'id';
199         if ($forcedvalue === false) {
200             $instance = context_instance::get_record_by_contextid($context->id, false);
202             if (!$instance) {
203                 // If the instance does not have a value defaults to not set, so we grab the context level default as its value.
204                 $instancevalue = context_instance::NOTSET;
205             } else {
206                 $instancevalue = $instance->get($fieldname);
207             }
208         } else {
209             $instancevalue = $forcedvalue;
210         }
212         // Not set.
213         if ($instancevalue == context_instance::NOTSET) {
215             // The effective value varies depending on the context level.
216             if ($context->contextlevel == CONTEXT_USER) {
217                 // Use the context level value as we don't allow people to set specific instances values.
218                 return self::get_effective_contextlevel_value($context->contextlevel, $element);
219             } else {
220                 // Check if we need to pass the plugin name of an activity.
221                 $forplugin = '';
222                 if ($context->contextlevel == CONTEXT_MODULE) {
223                     list($course, $cm) = get_course_and_cm_from_cmid($context->instanceid);
224                     $forplugin = $cm->modname;
225                 }
226                 // Use the default context level value.
227                 list($purposeid, $categoryid) = self::get_effective_default_contextlevel_purpose_and_category(
228                     $context->contextlevel, false, false, $forplugin
229                 );
230                 return self::get_element_instance($element, $$fieldname);
231             }
232         }
234         // Specific value for this context instance.
235         if ($instancevalue != context_instance::INHERIT) {
236             return self::get_element_instance($element, $instancevalue);
237         }
239         // This context is using inherited so let's return the parent effective value.
240         $parentcontext = $context->get_parent_context();
241         if (!$parentcontext) {
242             return false;
243         }
245         // The forced value should not be transmitted to parent contexts.
246         return self::get_effective_context_value($parentcontext, $element);
247     }
249     /**
250      * Returns the effective value for a context level.
251      *
252      * Note that this is different from the effective default context level
253      * (see get_effective_default_contextlevel_purpose_and_category) as this is returning
254      * the value set in the data registry, not in the defaults page.
255      *
256      * @param int $contextlevel
257      * @param string $element 'category' or 'purpose'
258      * @param int $forcedvalue Use this value as if this was this context level purpose.
259      * @return \tool_dataprivacy\purpose|false
260      */
261     public static function get_effective_contextlevel_value($contextlevel, $element, $forcedvalue = false) {
263         if ($element !== 'purpose' && $element !== 'category') {
264             throw new coding_exception('Only \'purpose\' and \'category\' are supported.');
265         }
266         $fieldname = $element . 'id';
268         if ($contextlevel != CONTEXT_SYSTEM && $contextlevel != CONTEXT_USER) {
269             throw new \coding_exception('Only context_system and context_user values can be retrieved, no other context levels ' .
270                 'have a purpose or a category.');
271         }
273         if ($forcedvalue === false) {
274             $instance = contextlevel::get_record_by_contextlevel($contextlevel, false);
275             if (!$instance) {
276                 // If the context level does not have a value defaults to not set, so we grab the context level default as
277                 // its value.
278                 $instancevalue = context_instance::NOTSET;
279             } else {
280                 $instancevalue = $instance->get($fieldname);
281             }
282         } else {
283             $instancevalue = $forcedvalue;
284         }
286         // Not set -> Use the default context level value.
287         if ($instancevalue == context_instance::NOTSET) {
288             list($purposeid, $categoryid) = self::get_effective_default_contextlevel_purpose_and_category($contextlevel);
289             return self::get_element_instance($element, $$fieldname);
290         }
292         // Specific value for this context instance.
293         if ($instancevalue != context_instance::INHERIT) {
294             return self::get_element_instance($element, $instancevalue);
295         }
297         if ($contextlevel == CONTEXT_SYSTEM) {
298             throw new coding_exception('Something went wrong, system defaults should be set and we should already have a value.');
299         }
301         // If we reach this point is that we are inheriting so get the parent context level and repeat.
302         $parentcontextlevel = reset(self::$contextlevelinheritance[$contextlevel]);
304         // Forced value are intentionally not passed as the force value should only affect the immediate context level.
305         return self::get_effective_contextlevel_value($parentcontextlevel, $element);
306     }
308     /**
309      * Returns the effective default purpose and category for a context level.
310      *
311      * @param int $contextlevel
312      * @param int|bool $forcedpurposevalue Use this value as if this was this context level purpose.
313      * @param int|bool $forcedcategoryvalue Use this value as if this was this context level category.
314      * @param string $activity The plugin name of the activity.
315      * @return int[]
316      */
317     public static function get_effective_default_contextlevel_purpose_and_category($contextlevel, $forcedpurposevalue = false,
318                                                                                    $forcedcategoryvalue = false, $activity = '') {
320         list($purposeid, $categoryid) = self::get_defaults($contextlevel, $activity);
322         // Honour forced values.
323         if ($forcedpurposevalue) {
324             $purposeid = $forcedpurposevalue;
325         }
326         if ($forcedcategoryvalue) {
327             $categoryid = $forcedcategoryvalue;
328         }
330         // Not set == INHERIT for defaults.
331         if ($purposeid == context_instance::INHERIT || $purposeid == context_instance::NOTSET) {
332             $purposeid = false;
333         }
334         if ($categoryid == context_instance::INHERIT || $categoryid == context_instance::NOTSET) {
335             $categoryid = false;
336         }
338         if ($contextlevel != CONTEXT_SYSTEM && ($purposeid === false || $categoryid === false)) {
339             foreach (self::$contextlevelinheritance[$contextlevel] as $parent) {
341                 list($parentpurposeid, $parentcategoryid) = self::get_defaults($parent);
342                 // Not set == INHERIT for defaults.
343                 if ($parentpurposeid == context_instance::INHERIT || $parentpurposeid == context_instance::NOTSET) {
344                     $parentpurposeid = false;
345                 }
346                 if ($parentcategoryid == context_instance::INHERIT || $parentcategoryid == context_instance::NOTSET) {
347                     $parentcategoryid = false;
348                 }
350                 if ($purposeid === false && $parentpurposeid) {
351                     $purposeid = $parentpurposeid;
352                 }
354                 if ($categoryid === false && $parentcategoryid) {
355                     $categoryid = $parentcategoryid;
356                 }
357             }
358         }
360         // They may still be false, but we return anyway.
361         return [$purposeid, $categoryid];
362     }
364     /**
365      * Returns an instance of the provided element.
366      *
367      * @throws \coding_exception
368      * @param string $element The element name 'purpose' or 'category'
369      * @param int $id The element id
370      * @return \core\persistent
371      */
372     private static function get_element_instance($element, $id) {
374         if ($element !== 'purpose' && $element !== 'category') {
375             throw new coding_exception('No other elements than purpose and category are allowed');
376         }
378         $classname = '\tool_dataprivacy\\' . $element;
379         return new $classname($id);
380     }