MDL-71174 core: Improve phpdoc for plagiarism_update_status
[moodle.git] / lib / plagiarismlib.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  * plagiarismlib.php - Contains core Plagiarism related functions.
19  *
20  * @since Moodle 2.0
21  * @package    core
22  * @subpackage plagiarism
23  * @copyright  2010 Dan Marsden http://danmarsden.com
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 if (!defined('MOODLE_INTERNAL')) {
28     die('Direct access to this script is forbidden.');
29 }
31 /**
32  * displays the similarity score and provides a link to the full report if allowed.
33  *
34  * @param object  $linkarray contains all relevant information for the plugin to generate a link
35  * @return string - url to allow login/viewing of a similarity report
36  */
37 function plagiarism_get_links($linkarray) {
38     global $CFG;
39     if (empty($CFG->enableplagiarism)) {
40         return '';
41     }
42     $plagiarismplugins = plagiarism_load_available_plugins();
43     $output = '';
44     foreach ($plagiarismplugins as $plugin => $dir) {
45         require_once($dir.'/lib.php');
46         $plagiarismclass = "plagiarism_plugin_$plugin";
47         $plagiarismplugin = new $plagiarismclass;
48         $output .= $plagiarismplugin->get_links($linkarray);
49     }
50     return $output;
51 }
53 /**
54  * returns array of plagiarism details about specified file
55  *
56  * @param int $cmid
57  * @param int $userid
58  * @param object $file moodle file object
59  * @return array - sets of details about specified file, one array of details per plagiarism plugin
60  *  - each set contains at least 'analyzed', 'score', 'reporturl'
61  */
62 function plagiarism_get_file_results($cmid, $userid, $file) {
63     global $CFG;
64     $allresults = array();
65     if (empty($CFG->enableplagiarism)) {
66         return $allresults;
67     }
68     $plagiarismplugins = plagiarism_load_available_plugins();
69     foreach ($plagiarismplugins as $plugin => $dir) {
70         require_once($dir.'/lib.php');
71         $plagiarismclass = "plagiarism_plugin_$plugin";
72         $plagiarismplugin = new $plagiarismclass;
73         $allresults[] = $plagiarismplugin->get_file_results($cmid, $userid, $file);
74     }
75     return $allresults;
76 }
78 /**
79  * saves/updates plagiarism settings from a modules config page - called by course/modedit.php
80  *
81  * @deprecated Since Moodle 3.9. MDL-65835 Please use {plugin name}_coursemodule_edit_post_actions() instead.
82  * @todo MDL-67526 This is to be moved from here to deprecatedlib.php in Moodle 4.1
83  * @param object $data - form data
84  */
85 function plagiarism_save_form_elements($data) {
86     global $CFG;
87     if (empty($CFG->enableplagiarism)) {
88         return '';
89     }
90     $plagiarismplugins = plagiarism_load_available_plugins();
91     foreach ($plagiarismplugins as $plugin => $dir) {
92         require_once($dir.'/lib.php');
93         $plagiarismclass = "plagiarism_plugin_$plugin";
94         $plagiarismplugin = new $plagiarismclass;
96         $reflectionmethod = new ReflectionMethod($plagiarismplugin, 'save_form_elements');
97         if ($reflectionmethod->getDeclaringClass()->getName() == get_class($plagiarismplugin)) {
98             $text = 'plagiarism_plugin::save_form_elements() is deprecated.';
99             $text .= ' Use plagiarism_' . $plugin . '_coursemodule_edit_post_actions() instead';
100             debugging($text, DEBUG_DEVELOPER);
101         }
103         $plagiarismplugin->save_form_elements($data);
104     }
107 /**
108  * adds the list of plagiarism settings to a form - called inside modules that have enabled plagiarism
109  *
110  * @deprecated Since Moodle 3.9. MDL-65835 Please use {plugin name}_coursemodule_standard_elements() instead.
111  * @todo MDL-67526 This is to be moved from here to deprecatedlib.php in Moodle 4.1
112  * @param object $mform - Moodle form object
113  * @param object $context - context object
114  * @param string $modulename - Name of the module
115  */
116 function plagiarism_get_form_elements_module($mform, $context, $modulename = "") {
117     global $CFG;
118     if (empty($CFG->enableplagiarism)) {
119         return '';
120     }
121     $plagiarismplugins = plagiarism_load_available_plugins();
122     foreach ($plagiarismplugins as $plugin => $dir) {
123         require_once($dir.'/lib.php');
124         $plagiarismclass = "plagiarism_plugin_$plugin";
125         $plagiarismplugin = new $plagiarismclass;
127         $reflectionmethod = new ReflectionMethod($plagiarismplugin, 'get_form_elements_module');
128         if ($reflectionmethod->getDeclaringClass()->getName() == get_class($plagiarismplugin)) {
129             $text = 'plagiarism_plugin::get_form_elements_module() is deprecated.';
130             $text .= ' Use plagiarism_' . $plugin . '_coursemodule_standard_elements() instead';
131             debugging($text, DEBUG_DEVELOPER);
132         }
134         $plagiarismplugin->get_form_elements_module($mform, $context, $modulename);
135     }
137 /**
138  * Allows a plagiarism plugin to print a button/link at the top of activity overview report pages.
139  *
140  * @param object $course - full Course object
141  * @param object $cm - full cm object
142  * @return string
143  */
144 function plagiarism_update_status($course, $cm) {
145     global $CFG;
146     if (empty($CFG->enableplagiarism)) {
147         return '';
148     }
149     $plagiarismplugins = plagiarism_load_available_plugins();
150     $output = '';
151     foreach ($plagiarismplugins as $plugin => $dir) {
152         require_once($dir.'/lib.php');
153         $plagiarismclass = "plagiarism_plugin_$plugin";
154         $plagiarismplugin = new $plagiarismclass;
155         $output .= $plagiarismplugin->update_status($course, $cm);
156     }
157     return $output;
160 /**
161  * Function that prints the student disclosure notifying that the files will be checked for plagiarism
162  * @param integer $cmid - the cmid of this module
163  * @return string
164  */
165 function plagiarism_print_disclosure($cmid) {
166     global $CFG;
167     if (empty($CFG->enableplagiarism)) {
168         return '';
169     }
170     $plagiarismplugins = plagiarism_load_available_plugins();
171     $output = '';
172     foreach ($plagiarismplugins as $plugin => $dir) {
173         require_once($dir.'/lib.php');
174         $plagiarismclass = "plagiarism_plugin_$plugin";
175         $plagiarismplugin = new $plagiarismclass;
176         $output .= $plagiarismplugin->print_disclosure($cmid);
177     }
178     return $output;
181 /**
182  * Helper function - also loads lib file of plagiarism plugin
183  *
184  * @todo MDL-67872 the deprecated code in this function to be removed in Moodle 4.1
185  * @return array of available plugins
186  */
187 function plagiarism_load_available_plugins() {
188     global $CFG;
189     static $showndeprecatedmessage = array(); // Only show message once per page load.
191     if (empty($CFG->enableplagiarism)) {
192         return array();
193     }
194     $plagiarismplugins = core_component::get_plugin_list('plagiarism');
195     $availableplugins = array();
196     foreach ($plagiarismplugins as $plugin => $dir) {
197         // Check this plugin is enabled and a lib file exists.
198         if (get_config('plagiarism', $plugin."_use")) {
199             // Deprecated Since Moodle 3.9.
200             $pluginenabled = true;
201             if (empty($showndeprecatedmessage[$plugin])) {
202                 $text = 'The setting plagiarism:'.$plugin.'_use is deprecated.';
203                 $text .= ' Use plagiarism_' . $plugin . ':enabled instead';
204                 debugging($text, DEBUG_DEVELOPER);
205                 $showndeprecatedmessage[$plugin] = true;
206             }
207         } else {
208             $pluginenabled = get_config('plagiarism_'.$plugin, 'enabled');
209         }
210         if ($pluginenabled && file_exists($dir."/lib.php")) {
211             require_once($dir.'/lib.php');
212             $plagiarismclass = "plagiarism_plugin_$plugin";
213             if (class_exists($plagiarismclass)) {
214                 $availableplugins[$plugin] = $dir;
215             }
216         }
217     }
218     return $availableplugins;