MDL-61307 core_privacy: Define and test providers

privacy/classes/local/metadata/collection.php

+<?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 defines the core_privacy\local\metadata\collection class object.
+ *
+ * The collection class is used to organize a collection of types
+ * objects, which contains the privacy field details of a component.
+ *
+ * @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\local\metadata;
+
+use core_privacy\local\metadata\types\type;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * A collection of metadata items.
+ *
+ * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class collection {
+
+    /**
+     * @var string The component that the items in the collection belong to.
+     */
+    protected $component;
+
+    /**
+     * @var array   The collection of metadata items.
+     */
+    protected $collection = [];
+
+    /**
+     * Constructor for a component's privacy collection class.
+     *
+     * @param string $component component name.
+     */
+    public function __construct($component) {
+        $this->component = $component;
+    }
+
+    /**
+     * Function to add an object that implements type interface to the current collection.
+     *
+     * @param   type    $type to add to collection.
+     * @return  $this
+     */
+    public function add_type(type $type) {
+        $this->collection[] = $type;
+
+        return $this;
+    }
+
+    /**
+     * Function to add a database table which contains user data to this collection.
+     *
+     * @param   string  $name the name of the database table.
+     * @param   array   $privacyfields An associative array of fieldname to description.
+     * @param   string  $summary A description of what the table is used for.
+     * @return  $this
+     */
+    public function add_database_table($name, array $privacyfields, $summary = '') {
+        $this->add_type(new types\database_table($name, $privacyfields, $summary));
+
+        return $this;
+    }
+
+    /**
+     * Function to link a subsystem to the component.
+     *
+     * @param   string  $name the name of the subsystem to link.
+     * @param   string  $summary A description of what is stored within this subsystem.
+     * @return  $this
+     */
+    public function link_subsystem($name, $summary = '') {
+        $this->add_type(new types\subsystem_link($name, $summary));
+
+        return $this;
+    }
+
+    /**
+     * Function to link a plugin to the component.
+     *
+     * @param   string  $name the name of the plugin to link.
+     * @param   string  $summary A description of what tis stored within this plugin.
+     * @return  $this
+     */
+    public function link_plugintype($name, $summary = '') {
+        $this->add_type(new types\plugintype_link($name, $summary));
+
+        return $this;
+    }
+
+    /**
+     * Function to indicate that data may be exported to an external location.
+     *
+     * @param   string  $name A name for the type of data exported.
+     * @param   array   $privacyfields A list of fields with their description.
+     * @param   string  $summary A description of what the table is used for. This is a language string identifier
+     *                           within the component.
+     * @return  $this
+     */
+    public function link_external_location($name, array $privacyfields, $summary = '') {
+        $this->add_type(new types\external_location($name, $privacyfields, $summary));
+
+        return $this;
+    }
+
+    /**
+     * Add a type of user preference to the collection.
+     *
+     * Typically this is a single user preference, but in some cases the
+     * name of a user preference fits a particular format.
+     *
+     * @param   string  $name The name of the user preference.
+     * @param   string  $summary A description of what the preference is used for.
+     * @return  $this
+     */
+    public function add_user_preference($name, $summary = '') {
+        $this->add_type(new types\user_preference($name, $summary));
+
+        return $this;
+    }
+
+    /**
+     * Function to return the current component name.
+     *
+     * @return string
+     */
+    public function get_component() {
+        return $this->component;
+    }
+
+    /**
+     * The content of this collection.
+     *
+     * @return  types\type[]
+     */
+    public function get_collection() {
+        return $this->collection;
+    }
+}

privacy/classes/local/metadata/null_provider.php

+<?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\nodata interface.
+ *
+ * Plugins implement this interface to declare that they don't store any personal information.
+ *
+ * @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\local\metadata;
+
+defined('MOODLE_INTERNAL') || die();
+
+interface null_provider {
+
+    /**
+     * Get the language string identifier with the component's language
+     * file to explain why this plugin stores no data.
+     *
+     * @return  string
+     */
+    public static function get_reason() : string ;
+}

privacy/classes/local/metadata/provider.php

+<?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/>.
+
+/**
+ * INterface for main metadata provider interface.
+ *
+ * @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\local\metadata;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * INterface for main metadata provider interface.
+ *
+ * @copyright 2018 Jake Dallimore <jrhdallimore@gmail.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+interface provider {
+
+    /**
+     * Returns meta data about this system.
+     *
+     * @param   collection     $collection The initialised collection to add items to.
+     * @return  collection     A listing of user data stored through this system.
+     */
+    public static function get_metadata(collection $collection) : collection ;
+}

privacy/classes/local/metadata/types/database_table.php

+<?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 defines an item of metadata which encapsulates a database table.
+ *
+ * @package core_privacy
+ * @copyright 2018 Zig Tan <zig@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+namespace core_privacy\local\metadata\types;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * The database_table type.
+ *
+ * @copyright 2018 Zig Tan <zig@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class database_table implements type {
+
+    /**
+     * @var string  Database table name.
+     */
+    protected $name;
+
+    /**
+     * @var array Fields which contain user information within the table.
+     */
+    protected $privacyfields;
+
+    /**
+     * @var string  A description of what this table is used for.
+     */
+    protected $summary;
+
+    /**
+     * Constructor to create a new database_table type.
+     *
+     * @param   string  $name The name of the database table being described.
+     * @param   array   $privacyfields A list of fields with their description.
+     * @param   string  $summary A description of what the table is used for.
+     */
+    public function __construct($name, array $privacyfields = [], $summary = '') {
+        if (debugging('', DEBUG_DEVELOPER)) {
+            if (empty($privacyfields)) {
+                debugging("Table '{$name}' was supplied without any fields.", DEBUG_DEVELOPER);
+            }
+
+            foreach ($privacyfields as $key => $field) {
+                $teststring = clean_param($field, PARAM_STRINGID);
+                if ($teststring !== $field) {
+                    debugging("Field '{$key}' passed for table '{$name}' has an invalid langstring identifier: '{$field}'",
+                        DEBUG_DEVELOPER);
+                }
+            }
+
+            $teststring = clean_param($summary, PARAM_STRINGID);
+            if ($teststring !== $summary) {
+                debugging("Summary information for the '{$name}' table has an invalid langstring identifier: '{$summary}'",
+                    DEBUG_DEVELOPER);
+            }
+        }
+
+        $this->name = $name;
+        $this->privacyfields = $privacyfields;
+        $this->summary = $summary;
+    }
+
+    /**
+     * The name of the database table.
+     *
+     * @return  string
+     */
+    public function get_name() {
+        return $this->name;
+    }
+
+    /**
+     * The list of fields within the table which contain user data, with a description of each field.
+     *
+     * @return  array
+     */
+    public function get_privacy_fields() {
+        return $this->privacyfields;
+    }
+
+    /**
+     * A summary of what this table is used for.
+     *
+     * @return  string
+     */
+    public function get_summary() {
+        return $this->summary;
+    }
+}

privacy/classes/local/metadata/types/external_location.php

+<?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 defines an item of metadata which encapsulates data which is exported to an external location.
+ *
+ * @package core_privacy
+ * @copyright 2018 Andrew Nicols <andrew@nicols.co.uk>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+namespace core_privacy\local\metadata\types;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * The external_location type.
+ *
+ * @copyright 2018 Andrew Nicols <andrew@nicols.co.uk>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class external_location implements type {
+
+    /**
+     * @var string The name to describe the type of information exported.
+     */
+    protected $name;
+
+    /**
+     * @var array The list of data names and descriptions exported.
+     */
+    protected $privacyfields;
+
+    /**
+     * @var string A description of what this table is used for.
+     * This is a language string identifier.
+     */
+    protected $summary;
+
+    /**
+     * Constructor to create a new external_location type.
+     *
+     * @param   string  $name A name for the type of data exported.
+     * @param   array   $privacyfields A list of fields with their description.
+     * @param   string  $summary A description of what the table is used for. This is a language string identifier
+     *                  within the component.
+     */
+    public function __construct($name, array $privacyfields = [], $summary = '') {
+        if (debugging('', DEBUG_DEVELOPER)) {
+            if (empty($privacyfields)) {
+                debugging("Location '{$name}' was supplied without any fields.", DEBUG_DEVELOPER);
+            }
+
+            foreach ($privacyfields as $key => $field) {
+                $teststring = clean_param($field, PARAM_STRINGID);
+                if ($teststring !== $field) {
+                    debugging("Field '{$key}' passed for location '{$name}' has an invalid langstring identifier: '{$field}'",
+                        DEBUG_DEVELOPER);
+                }
+            }
+
+            $teststring = clean_param($summary, PARAM_STRINGID);
+            if ($teststring !== $summary) {
+                debugging("Summary information for the '{$name}' location has an invalid langstring identifier: '{$summary}'",
+                    DEBUG_DEVELOPER);
+            }
+        }
+
+        $this->name = $name;
+        $this->privacyfields = $privacyfields;
+        $this->summary = $summary;
+    }
+
+    /**
+     * The name to describe the type of information exported.
+     *
+     * @return  string
+     */
+    public function get_name() {
+        return $this->name;
+    }
+
+    /**
+     * Get the list of fields which contain user data, with a description of each field.
+     *
+     * @return  array
+     */
+    public function get_privacy_fields() {
+        return $this->privacyfields;
+    }
+
+    /**
+     * A summary of what this type of exported data is used for.
+     *
+     * @return  string
+     */
+    public function get_summary() {
+        return $this->summary;
+    }
+}

privacy/classes/local/metadata/types/plugintype_link.php

+<?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 defines a link to another Moodle plugin.
+ *
+ * @package core_privacy
+ * @copyright 2018 Zig Tan <zig@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+namespace core_privacy\local\metadata\types;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * The plugintype link.
+ *
+ * @copyright 2018 Zig Tan <zig@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class plugintype_link implements type {
+
+    /**
+     * @var The name of the core plugintype to link.
+     */
+    protected $name;
+
+    /**
+     * @var string A description of what this plugintype is used to store.
+     */
+    protected $summary;
+
+    /**
+     * Constructor for the plugintype_link.
+     *
+     * @param   string  $name The name of the plugintype to link.
+     * @param   string  $summary A description of what is stored within this plugintype.
+     */
+    public function __construct($name, $summary = '') {
+        if (debugging('', DEBUG_DEVELOPER)) {
+            $teststring = clean_param($summary, PARAM_STRINGID);
+            if ($teststring !== $summary) {
+                debugging("Summary information for use of the '{$name}' plugintype " .
+                    "has an invalid langstring identifier: '{$summary}'",
+                    DEBUG_DEVELOPER);
+            }
+        }
+
+        $this->name = $name;
+        $this->summary = $summary;
+    }
+
+    /**
+     * Function to return the name of this plugintype_link type.
+     *
+     * @return string $name
+     */
+    public function get_name() {
+        return $this->name;
+    }
+
+    /**
+     * A plugintype link does not define any fields itself.
+     *
+     * @return  array
+     */
+    public function get_privacy_fields() : array {
+        return null;
+    }
+
+    /**
+     * A summary of what this plugintype is used for.
+     *
+     * @return string $summary
+     */
+    public function get_summary() {
+        return $this->summary;
+    }
+}

privacy/classes/local/metadata/types/subsystem_link.php

+<?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 defines a link to another Moodle subsystem.
+ *
+ * @package core_privacy
+ * @copyright 2018 Zig Tan <zig@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+namespace core_privacy\local\metadata\types;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * The subsystem link type.
+ *
+ * @copyright 2018 Zig Tan <zig@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class subsystem_link implements type {
+
+    /**
+     * @var The name of the core subsystem to link.
+     */
+    protected $name;
+
+    /**
+     * @var string A description of what this subsystem is used to store.
+     */
+    protected $summary;
+
+    /**
+     * Constructor for the subsystem_link.
+     *
+     * @param   string  $name The name of the subsystem to link.
+     * @param   string  $summary A description of what is stored within this subsystem.
+     */