Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**

 * This file contains the core_privacy\manager class.

 *

 * @package core_privacy

 * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>

 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

namespace core_privacy;

use core_privacy\local\metadata\collection;

use core_privacy\local\metadata\null_provider;

use core_privacy\local\request\context_aware_provider;

use core_privacy\local\request\contextlist_collection;

use core_privacy\local\request\core_user_data_provider;

use core_privacy\local\request\core_userlist_provider;

use core_privacy\local\request\data_provider;

use core_privacy\local\request\user_preference_provider;

use \core_privacy\local\metadata\provider as metadata_provider;

defined('MOODLE_INTERNAL') || die();

/**

 * The core_privacy\manager class, providing a facade to describe, export and delete personal data across Moodle and its components.

 *

 * This class is responsible for communicating with and collating privacy data from all relevant components, where relevance is

 * determined through implementations of specific marker interfaces. These marker interfaces describe the responsibilities (in terms

 * of personal data storage) as well as the relationship between the component and the core_privacy subsystem.

 *

 * The interface hierarchy is as follows:

 * ├── local\metadata\null_provider

 * ├── local\metadata\provider

 * ├── local\request\data_provider

 *     └── local\request\core_data_provider

 *         └── local\request\core_user_data_provider

 *             └── local\request\plugin\provider

 *             └── local\request\subsystem\provider

 *         └── local\request\user_preference_provider

 *     └── local\request\shared_data_provider

 *         └── local\request\plugin\subsystem_provider

 *         └── local\request\plugin\subplugin_provider

 *         └── local\request\subsystem\plugin_provider

 *

 * Describing personal data:

 * -------------------------

 * All components must state whether they store personal data (and DESCRIBE it) by implementing one of the metadata providers:

 * - local\metadata\null_provider (indicating they don't store personal data)

 * - local\metadata\provider (indicating they do store personal data, and describing it)

 *

 * The manager requests metadata for all Moodle components implementing the local\metadata\provider interface.

 *

 * Export and deletion of personal data:

 * -------------------------------------

 * Those components storing personal data need to provide EXPORT and DELETION of this data by implementing a request provider.

 * Which provider implementation depends on the nature of the component; whether it's a sub-component and which components it

 * stores data for.

 *

 * Export and deletion for sub-components (or any component storing data on behalf of another component) is managed by the parent

 * component. If a component contains sub-components, it must ask those sub-components to provide the relevant data. Only certain

 * 'core provider' components are called directly from the manager and these must provide the personal data stored by both

 * themselves, and by all sub-components. Because of this hierarchical structure, the core_privacy\manager needs to know which

 * components are to be called directly by core: these are called core data providers. The providers implemented by sub-components

 * are called shared data providers.

 *

 * The following are interfaces are not implemented directly, but are marker interfaces uses to classify components by nature:

 * - local\request\data_provider:

 *      Not implemented directly. Used to classify components storing personal data of some kind. Includes both components storing

 *      personal data for themselves and on behalf of other components.

 *      Include: local\request\core_data_provider and local\request\shared_data_provider.

 * - local\request\core_data_provider:

 *      Not implemented directly. Used to classify components storing personal data for themselves and which are to be called by the

 *      core_privacy subsystem directly.

 *      Includes: local\request\core_user_data_provider and local\request\user_preference_provider.

 * - local\request\core_user_data_provider:

 *      Not implemented directly. Used to classify components storing personal data for themselves, which are either a plugin or

 *      subsystem and which are to be called by the core_privacy subsystem directly.

 *      Includes: local\request\plugin\provider and local\request\subsystem\provider.

 * - local\request\shared_data_provider:

 *      Not implemented directly. Used to classify components storing personal data on behalf of other components and which are

 *      called by the owning component directly.

 *      Includes: local\request\plugin\subsystem_provider, local\request\plugin\subplugin_provider and local\request\subsystem\plugin_provider

 *

 * The manager only requests the export or deletion of personal data for components implementing the local\request\core_data_provider

 * interface or one of its descendants; local\request\plugin\provider, local\request\subsystem\provider or local\request\user_preference_provider.

 * Implementing one of these signals to the core_privacy subsystem that the component must be queried directly from the manager.

 *

 * Any component using another component to store personal data on its behalf, is responsible for making the relevant call to

 * that component's relevant shared_data_provider class.

 *

 * For example:

 * The manager calls a core_data_provider component (e.g. mod_assign) which, in turn, calls relevant subplugins or subsystems

 * (which assign uses to store personal data) to get that data. All data for assign and its sub-components is aggregated by assign

 * and returned to the core_privacy subsystem.

 *

 * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>

 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class manager {

    /**

     * @var manager_observer Observer.

     */

    protected $observer;

    /**

     * Set the failure handler.

     *

     * @param   manager_observer $observer

     */

    public function set_observer(manager_observer $observer) {

        $this->observer = $observer;

    }

    /**

     * Checks whether the given component is compliant with the core_privacy API.

     * To be considered compliant, a component must declare whether (and where) it stores personal data.

     *

     * Components which do store personal data must:

     * - Have implemented the core_privacy\local\metadata\provider interface (to describe the data it stores) and;

     * - Have implemented the core_privacy\local\request\data_provider interface (to facilitate export of personal data)

     * - Have implemented the core_privacy\local\request\deleter interface

     *

     * Components which do not store personal data must:

     * - Have implemented the core_privacy\local\metadata\null_provider interface to signal that they don't store personal data.

     *

     * @param string $component frankenstyle component name, e.g. 'mod_assign'

     * @return bool true if the component is compliant, false otherwise.

     */

    public function component_is_compliant(string $component): bool {

        // Components which don't store user data need only implement the null_provider.

        if ($this->component_implements($component, null_provider::class)) {

            return true;

        }

        if (static::is_empty_subsystem($component)) {

            return true;

        }

        // Components which store user data must implement the local\metadata\provider and the local\request\data_provider.

        if ($this->component_implements($component, metadata_provider::class) &&

            $this->component_implements($component, data_provider::class)) {

            return true;

        }

        return false;

    }

    /**

     * Retrieve the reason for implementing the null provider interface.

     *

     * @param  string $component Frankenstyle component name.

     * @return string The key to retrieve the language string for the null provider reason.

     */

    public function get_null_provider_reason(string $component): string {

        if ($this->component_implements($component, null_provider::class)) {

            $reason = $this->handled_component_class_callback($component, null_provider::class, 'get_reason', []);

            return empty($reason) ? 'privacy:reason' : $reason;

        } else {

            throw new \coding_exception('Call to undefined method', 'Please only call this method on a null provider.');

        }

    }

    /**

     * Return whether this is an 'empty' subsystem - that is, a subsystem without a directory.

     *

     * @param  string $component Frankenstyle component name.

     * @return string The key to retrieve the language string for the null provider reason.

     */

    public static function is_empty_subsystem($component) {

        if (strpos($component, 'core_') === 0) {

            if (null === \core_component::get_subsystem_directory(substr($component, 5))) {

                // This is a subsystem without a directory.

                return true;

            }

        }

        return false;

    }

    /**

     * Get the privacy metadata for all components.

     *

     * @return collection[] The array of collection objects, indexed by frankenstyle component name.

     */

    public function get_metadata_for_components(): array {

        // Get the metadata, and put into an assoc array indexed by component name.

        $metadata = [];

        foreach ($this->get_component_list() as $component) {

            $componentmetadata = $this->handled_component_class_callback($component, metadata_provider::class,

                'get_metadata', [new collection($component)]);

            if ($componentmetadata !== null) {

                $metadata[$component] = $componentmetadata;

            }

        }

        return $metadata;

    }

    /**

     * Gets a collection of resultset objects for all components.

     *

     *

     * @param int $userid the id of the user we're fetching contexts for.

     * @return contextlist_collection the collection of contextlist items for the respective components.

     */

    public function get_contexts_for_userid(int $userid): contextlist_collection {

        $progress = static::get_log_tracer();

        $components = $this->get_component_list();

        $a = (object) [

            'total' => count($components),

            'progress' => 0,

            'component' => '',

            'datetime' => userdate(time()),

        ];

        $clcollection = new contextlist_collection($userid);

        $progress->output(get_string('trace:fetchcomponents', 'core_privacy', $a), 1);

        foreach ($components as $component) {

            $a->component = $component;

            $a->progress++;

            $a->datetime = userdate(time());

            $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);

            $contextlist = $this->handled_component_class_callback($component, core_user_data_provider::class,

                'get_contexts_for_userid', [$userid]);

            if ($contextlist === null) {

                $contextlist = new local\request\contextlist();

            }

            // Each contextlist is tied to its respective component.

            $contextlist->set_component($component);

            // Add contexts that the component may not know about.

            // Example of these include activity completion which modules do not know about themselves.

            $contextlist = local\request\helper::add_shared_contexts_to_contextlist_for($userid, $contextlist);

            if (count($contextlist)) {

                $clcollection->add_contextlist($contextlist);

            }

        }

        $progress->output(get_string('trace:done', 'core_privacy'), 1);

        return $clcollection;

    }

    /**

     * Gets a collection of users for all components in the specified context.

     *

     * @param   \context    $context The context to search

     * @return  userlist_collection the collection of userlist items for the respective components.

     */

    public function get_users_in_context(\context $context): \core_privacy\local\request\userlist_collection {

        $progress = static::get_log_tracer();

        $components = $this->get_component_list();

        $a = (object) [

            'total' => count($components),

            'progress' => 0,

            'component' => '',

            'datetime' => userdate(time()),

        ];

        $collection = new \core_privacy\local\request\userlist_collection($context);

        $progress->output(get_string('trace:fetchcomponents', 'core_privacy', $a), 1);

        foreach ($components as $component) {

            $a->component = $component;

            $a->progress++;

            $a->datetime = userdate(time());

            $progress->output(get_string('trace:preprocessingcomponent', 'core_privacy', $a), 2);

            $userlist = new local\request\userlist($context, $component);

            $this->handled_component_class_callback($component, core_userlist_provider::class, 'get_users_in_context', [$userlist]);

            // Add contexts that the component may not know about.

            \core_privacy\local\request\helper::add_shared_users_to_userlist($userlist);

            if (count($userlist)) {

                $collection->add_userlist($userlist);

            }

        }

        $progress->output(get_string('trace:done', 'core_privacy'), 1);

        return $collection;

    }

    /**

     * Export all user data for the specified approved_contextlist items.

     *

     * Note: userid and component are stored in each respective approved_contextlist.

     *

     * @param contextlist_collection $contextlistcollection the collection of contextlists for all components.

     * @return string the location of the exported data.

     * @throws \moodle_exception if the contextlist_collection does not contain all approved_contextlist items or if one of the

     * approved_contextlists' components is not a core_data_provider.

     */

    public function export_user_data(contextlist_collection $contextlistcollection) {

        $progress = static::get_log_tracer();

        $a = (object) [

            'total' => count($contextlistcollection),

            'progress' => 0,

            'component' => '',

            'datetime' => userdate(time()),

        ];

        // Export for the various components/contexts.

        $progress->output(get_string('trace:exportingapproved', 'core_privacy', $a), 1);

        foreach ($contextlistcollection as $approvedcontextlist) {

            if (!$approvedcontextlist instanceof \core_privacy\local\request\approved_contextlist) {

                throw new \moodle_exception('Contextlist must be an approved_contextlist');

            }

            $component = $approvedcontextlist->get_component();

            $a->component = $component;

            $a->progress++;

            $a->datetime = userdate(time());

            $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);

            // Core user data providers.

            if ($this->component_implements($component, core_user_data_provider::class)) {

                if (count($approvedcontextlist)) {

                    // This plugin has data it knows about. It is responsible for storing basic data about anything it is

                    // told to export.

                    $this->handled_component_class_callback($component, core_user_data_provider::class,

                        'export_user_data', [$approvedcontextlist]);

                }

            } else if (!$this->component_implements($component, context_aware_provider::class)) {

                // This plugin does not know that it has data - export the shared data it doesn't know about.

                local\request\helper::export_data_for_null_provider($approvedcontextlist);

            }

        }

        $progress->output(get_string('trace:done', 'core_privacy'), 1);

        // Check each component for non contextlist items too.

        $components = $this->get_component_list();

        $a->total = count($components);

        $a->progress = 0;

        $a->datetime = userdate(time());

        $progress->output(get_string('trace:exportingrelated', 'core_privacy', $a), 1);

        foreach ($components as $component) {

            $a->component = $component;

            $a->progress++;

            $a->datetime = userdate(time());

            $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);

            // Core user preference providers.

            $this->handled_component_class_callback($component, user_preference_provider::class,

                'export_user_preferences', [$contextlistcollection->get_userid()]);

            // Contextual information providers. Give each component a chance to include context information based on the

            // existence of a child context in the contextlist_collection.

            $this->handled_component_class_callback($component, context_aware_provider::class,

                'export_context_data', [$contextlistcollection]);

        }

        $progress->output(get_string('trace:done', 'core_privacy'), 1);

        $progress->output(get_string('trace:finalisingexport', 'core_privacy'), 1);

        $location = local\request\writer::with_context(\context_system::instance())->finalise_content();

        $progress->output(get_string('trace:exportcomplete', 'core_privacy'), 1);

        return $location;

    }

    /**

     * Delete all user data for approved contexts lists provided in the collection.

     *

     * This call relates to the forgetting of an entire user.

     *

     * Note: userid and component are stored in each respective approved_contextlist.

     *

     * @param contextlist_collection $contextlistcollection the collections of approved_contextlist items on which to call deletion.

     * @throws \moodle_exception if the contextlist_collection doesn't contain all approved_contextlist items, or if the component

     * for an approved_contextlist isn't a core provider.

     */

    public function delete_data_for_user(contextlist_collection $contextlistcollection) {

        $progress = static::get_log_tracer();

        $a = (object) [

            'total' => count($contextlistcollection),

            'progress' => 0,

            'component' => '',

            'datetime' => userdate(time()),

        ];

        // Delete the data.

        $progress->output(get_string('trace:deletingapproved', 'core_privacy', $a), 1);

        foreach ($contextlistcollection as $approvedcontextlist) {

            if (!$approvedcontextlist instanceof \core_privacy\local\request\approved_contextlist) {

                throw new \moodle_exception('Contextlist must be an approved_contextlist');

            }

            $component = $approvedcontextlist->get_component();

            $a->component = $component;

            $a->progress++;

            $a->datetime = userdate(time());

            $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);

            if (count($approvedcontextlist)) {

                // The component knows about data that it has.

                // Have it delete its own data.

                $this->handled_component_class_callback($approvedcontextlist->get_component(), core_user_data_provider::class,

                    'delete_data_for_user', [$approvedcontextlist]);

            }

            // Delete any shared user data it doesn't know about.

            local\request\helper::delete_data_for_user($approvedcontextlist);

        }

        $progress->output(get_string('trace:done', 'core_privacy'), 1);

    }

    /**

     * Delete all user data for all specified users in a context.

     *

     * @param   \core_privacy\local\request\userlist_collection $collection

     */

    public function delete_data_for_users_in_context(\core_privacy\local\request\userlist_collection $collection) {

        $progress = static::get_log_tracer();

        $a = (object) [

            'contextid' => $collection->get_context()->id,

            'total' => count($collection),

            'progress' => 0,

            'component' => '',

            'datetime' => userdate(time()),

        ];

        // Delete the data.

        $progress->output(get_string('trace:deletingapprovedusers', 'core_privacy', $a), 1);

        foreach ($collection as $userlist) {

            if (!$userlist instanceof \core_privacy\local\request\approved_userlist) {

                throw new \moodle_exception('The supplied userlist must be an approved_userlist');

            }

            $component = $userlist->get_component();

            $a->component = $component;

            $a->progress++;

            $a->datetime = userdate(time());

            if (empty($userlist)) {

                // This really shouldn't happen!

                continue;

            }

            $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);

            $this->handled_component_class_callback($component, core_userlist_provider::class,

                    'delete_data_for_users', [$userlist]);

        }

        $progress->output(get_string('trace:done', 'core_privacy'), 1);

    }

    /**

     * Delete all use data which matches the specified deletion criteria.

     *

     * @param \context $context The specific context to delete data for.

     */

    public function delete_data_for_all_users_in_context(\context $context) {

        $progress = static::get_log_tracer();

        $components = $this->get_component_list();

        $a = (object) [

            'total' => count($components),

            'progress' => 0,

            'component' => '',

            'datetime' => userdate(time()),

        ];

        $progress->output(get_string('trace:deletingcontext', 'core_privacy', $a), 1);

        foreach ($this->get_component_list() as $component) {

            $a->component = $component;

            $a->progress++;

            $a->datetime = userdate(time());

            $progress->output(get_string('trace:processingcomponent', 'core_privacy', $a), 2);

            // If this component knows about specific data that it owns,

            // have it delete all of that user data for the context.

            $this->handled_component_class_callback($component, core_user_data_provider::class,

                'delete_data_for_all_users_in_context', [$context]);

            // Delete any shared user data it doesn't know about.

            local\request\helper::delete_data_for_all_users_in_context($component, $context);

        }

        $progress->output(get_string('trace:done', 'core_privacy'), 1);

    }

    /**

     * Returns a list of frankenstyle names of core components (plugins and subsystems).

     *

     * @return array the array of frankenstyle component names.

     */

    protected function get_component_list() {

        $components = array_keys(array_reduce(\core_component::get_component_list(), function($carry, $item) {

            return array_merge($carry, $item);

        }, []));

        $components[] = 'core';

        return $components;

    }

    /**

     * Return the fully qualified provider classname for the component.

     *

     * @param string $component the frankenstyle component name.

     * @return string the fully qualified provider classname.

     */

    protected function get_provider_classname($component) {

        return static::get_provider_classname_for_component($component);

    }

    /**

     * Return the fully qualified provider classname for the component.

     *

     * @param string $component the frankenstyle component name.

     * @return string the fully qualified provider classname.

     */

    public static function get_provider_classname_for_component(string $component) {

        return "$component\\privacy\\provider";

    }

    /**

     * Checks whether the component's provider class implements the specified interface.

     * This can either be implemented directly, or by implementing a descendant (extension) of the specified interface.

     *

     * @param string $component the frankenstyle component name.

     * @param string $interface the name of the interface we want to check.

     * @return bool True if an implementation was found, false otherwise.

     */

    protected function component_implements(string $component, string $interface): bool {

        $providerclass = $this->get_provider_classname($component);

        if (class_exists($providerclass)) {

            $rc = new \ReflectionClass($providerclass);

            return $rc->implementsInterface($interface);

        }

        return false;

    }

    /**

     * Call the named method with the specified params on any plugintype implementing the relevant interface.

     *

     * @param   string  $plugintype The plugingtype to check

     * @param   string  $interface The interface to implement

     * @param   string  $methodname The method to call

     * @param   array   $params The params to call

     */

    public static function plugintype_class_callback(string $plugintype, string $interface, string $methodname, array $params) {

        $components = \core_component::get_plugin_list($plugintype);

        foreach (array_keys($components) as $component) {

            static::component_class_callback("{$plugintype}_{$component}", $interface, $methodname, $params);

        }

    }

    /**

     * Call the named method with the specified params on the supplied component if it implements the relevant interface on its provider.

     *

     * @param   string  $component The component to call

     * @param   string  $interface The interface to implement

     * @param   string  $methodname The method to call

     * @param   array   $params The params to call

     * @return  mixed

     */

    public static function component_class_callback(string $component, string $interface, string $methodname, array $params) {

        $classname = static::get_provider_classname_for_component($component);

        if (class_exists($classname) && is_subclass_of($classname, $interface)) {

            return component_class_callback($classname, $methodname, $params);

        }

        return null;

    }

    /**

     * Get the tracer used for logging.

     *

     * The text tracer is used except for unit tests.

     *

     * @return  \progress_trace

     */

    protected static function get_log_tracer() {

        if (PHPUNIT_TEST) {

            return new \null_progress_trace();

        }

        return new \text_progress_trace();

    }

    /**

     * Call the named method with the specified params on the supplied component if it implements the relevant interface

     * on its provider.

     *

     * @param   string  $component The component to call

     * @param   string  $interface The interface to implement

     * @param   string  $methodname The method to call

     * @param   array   $params The params to call

     * @return  mixed

     */

    protected function handled_component_class_callback(string $component, string $interface, string $methodname, array $params) {

        try {

            return static::component_class_callback($component, $interface, $methodname, $params);

        } catch (\Throwable $e) {

            debugging($e->getMessage(), DEBUG_DEVELOPER, $e->getTrace());

            $this->component_class_callback_failed($e, $component, $interface, $methodname, $params);

            return null;

        }

    }

    /**

     * Notifies the observer of any failure.

     *

     * @param \Throwable $e

     * @param string $component

     * @param string $interface

     * @param string $methodname

     * @param array $params

     */

    protected function component_class_callback_failed(\Throwable $e, string $component, string $interface,

            string $methodname, array $params) {

        if ($this->observer) {

            call_user_func_array([$this->observer, 'handle_component_failure'], func_get_args());

        }

    }

}