MDL-41437 fix non-functional message processor uninstall
[moodle.git] / lib / adminlib.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  * Functions and classes used during installation, upgrades and for admin settings.
19  *
20  *  ADMIN SETTINGS TREE INTRODUCTION
21  *
22  *  This file performs the following tasks:
23  *   -it defines the necessary objects and interfaces to build the Moodle
24  *    admin hierarchy
25  *   -it defines the admin_externalpage_setup()
26  *
27  *  ADMIN_SETTING OBJECTS
28  *
29  *  Moodle settings are represented by objects that inherit from the admin_setting
30  *  class. These objects encapsulate how to read a setting, how to write a new value
31  *  to a setting, and how to appropriately display the HTML to modify the setting.
32  *
33  *  ADMIN_SETTINGPAGE OBJECTS
34  *
35  *  The admin_setting objects are then grouped into admin_settingpages. The latter
36  *  appear in the Moodle admin tree block. All interaction with admin_settingpage
37  *  objects is handled by the admin/settings.php file.
38  *
39  *  ADMIN_EXTERNALPAGE OBJECTS
40  *
41  *  There are some settings in Moodle that are too complex to (efficiently) handle
42  *  with admin_settingpages. (Consider, for example, user management and displaying
43  *  lists of users.) In this case, we use the admin_externalpage object. This object
44  *  places a link to an external PHP file in the admin tree block.
45  *
46  *  If you're using an admin_externalpage object for some settings, you can take
47  *  advantage of the admin_externalpage_* functions. For example, suppose you wanted
48  *  to add a foo.php file into admin. First off, you add the following line to
49  *  admin/settings/first.php (at the end of the file) or to some other file in
50  *  admin/settings:
51  * <code>
52  *     $ADMIN->add('userinterface', new admin_externalpage('foo', get_string('foo'),
53  *         $CFG->wwwdir . '/' . '$CFG->admin . '/foo.php', 'some_role_permission'));
54  * </code>
55  *
56  *  Next, in foo.php, your file structure would resemble the following:
57  * <code>
58  *         require(dirname(dirname(dirname(__FILE__))).'/config.php');
59  *         require_once($CFG->libdir.'/adminlib.php');
60  *         admin_externalpage_setup('foo');
61  *         // functionality like processing form submissions goes here
62  *         echo $OUTPUT->header();
63  *         // your HTML goes here
64  *         echo $OUTPUT->footer();
65  * </code>
66  *
67  *  The admin_externalpage_setup() function call ensures the user is logged in,
68  *  and makes sure that they have the proper role permission to access the page.
69  *  It also configures all $PAGE properties needed for navigation.
70  *
71  *  ADMIN_CATEGORY OBJECTS
72  *
73  *  Above and beyond all this, we have admin_category objects. These objects
74  *  appear as folders in the admin tree block. They contain admin_settingpage's,
75  *  admin_externalpage's, and other admin_category's.
76  *
77  *  OTHER NOTES
78  *
79  *  admin_settingpage's, admin_externalpage's, and admin_category's all inherit
80  *  from part_of_admin_tree (a pseudointerface). This interface insists that
81  *  a class has a check_access method for access permissions, a locate method
82  *  used to find a specific node in the admin tree and find parent path.
83  *
84  *  admin_category's inherit from parentable_part_of_admin_tree. This pseudo-
85  *  interface ensures that the class implements a recursive add function which
86  *  accepts a part_of_admin_tree object and searches for the proper place to
87  *  put it. parentable_part_of_admin_tree implies part_of_admin_tree.
88  *
89  *  Please note that the $this->name field of any part_of_admin_tree must be
90  *  UNIQUE throughout the ENTIRE admin tree.
91  *
92  *  The $this->name field of an admin_setting object (which is *not* part_of_
93  *  admin_tree) must be unique on the respective admin_settingpage where it is
94  *  used.
95  *
96  * Original author: Vincenzo K. Marcovecchio
97  * Maintainer:      Petr Skoda
98  *
99  * @package    core
100  * @subpackage admin
101  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
102  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
103  */
105 defined('MOODLE_INTERNAL') || die();
107 /// Add libraries
108 require_once($CFG->libdir.'/ddllib.php');
109 require_once($CFG->libdir.'/xmlize.php');
110 require_once($CFG->libdir.'/messagelib.php');
112 define('INSECURE_DATAROOT_WARNING', 1);
113 define('INSECURE_DATAROOT_ERROR', 2);
115 /**
116  * Automatically clean-up all plugin data and remove the plugin DB tables
117  *
118  * NOTE: do not call directly, use new /admin/plugins.php?uninstall=component instead!
119  *
120  * @param string $type The plugin type, eg. 'mod', 'qtype', 'workshopgrading' etc.
121  * @param string $name The plugin name, eg. 'forum', 'multichoice', 'accumulative' etc.
122  * @uses global $OUTPUT to produce notices and other messages
123  * @return void
124  */
125 function uninstall_plugin($type, $name) {
126     global $CFG, $DB, $OUTPUT;
127     require_once($CFG->libdir.'/pluginlib.php');
129     // This may take a long time.
130     @set_time_limit(0);
132     // Recursively uninstall all subplugins first.
133     $subplugintypes = core_component::get_plugin_types_with_subplugins();
134     if (isset($subplugintypes[$type])) {
135         $base = core_component::get_plugin_directory($type, $name);
136         if (file_exists("$base/db/subplugins.php")) {
137             $subplugins = array();
138             include("$base/db/subplugins.php");
139             foreach ($subplugins as $subplugintype=>$dir) {
140                 $instances = core_component::get_plugin_list($subplugintype);
141                 foreach ($instances as $subpluginname => $notusedpluginpath) {
142                     uninstall_plugin($subplugintype, $subpluginname);
143                 }
144             }
145         }
147     }
149     $component = $type . '_' . $name;  // eg. 'qtype_multichoice' or 'workshopgrading_accumulative' or 'mod_forum'
151     if ($type === 'mod') {
152         $pluginname = $name;  // eg. 'forum'
153         if (get_string_manager()->string_exists('modulename', $component)) {
154             $strpluginname = get_string('modulename', $component);
155         } else {
156             $strpluginname = $component;
157         }
159     } else {
160         $pluginname = $component;
161         if (get_string_manager()->string_exists('pluginname', $component)) {
162             $strpluginname = get_string('pluginname', $component);
163         } else {
164             $strpluginname = $component;
165         }
166     }
168     echo $OUTPUT->heading($pluginname);
170     $plugindirectory = core_component::get_plugin_directory($type, $name);
171     $uninstalllib = $plugindirectory . '/db/uninstall.php';
172     if (file_exists($uninstalllib)) {
173         require_once($uninstalllib);
174         $uninstallfunction = 'xmldb_' . $pluginname . '_uninstall';    // eg. 'xmldb_workshop_uninstall()'
175         if (function_exists($uninstallfunction)) {
176             if (!$uninstallfunction()) {
177                 echo $OUTPUT->notification('Encountered a problem running uninstall function for '. $pluginname);
178             }
179         }
180     }
182     if ($type === 'mod') {
183         // perform cleanup tasks specific for activity modules
185         if (!$module = $DB->get_record('modules', array('name' => $name))) {
186             print_error('moduledoesnotexist', 'error');
187         }
189         // delete all the relevant instances from all course sections
190         if ($coursemods = $DB->get_records('course_modules', array('module' => $module->id))) {
191             foreach ($coursemods as $coursemod) {
192                 if (!delete_mod_from_section($coursemod->id, $coursemod->section)) {
193                     echo $OUTPUT->notification("Could not delete the $strpluginname with id = $coursemod->id from section $coursemod->section");
194                 }
195             }
196         }
198         // Increment course.cacherev for courses that used this module.
199         // This will force cache rebuilding on the next request.
200         increment_revision_number('course', 'cacherev',
201                 "id IN (SELECT DISTINCT course
202                                 FROM {course_modules}
203                                WHERE module=?)",
204                 array($module->id));
206         // delete all the course module records
207         $DB->delete_records('course_modules', array('module' => $module->id));
209         // delete module contexts
210         if ($coursemods) {
211             foreach ($coursemods as $coursemod) {
212                 context_helper::delete_instance(CONTEXT_MODULE, $coursemod->id);
213             }
214         }
216         // delete the module entry itself
217         $DB->delete_records('modules', array('name' => $module->name));
219         // cleanup the gradebook
220         require_once($CFG->libdir.'/gradelib.php');
221         grade_uninstalled_module($module->name);
223         // Perform any custom uninstall tasks
224         if (file_exists($CFG->dirroot . '/mod/' . $module->name . '/lib.php')) {
225             require_once($CFG->dirroot . '/mod/' . $module->name . '/lib.php');
226             $uninstallfunction = $module->name . '_uninstall';
227             if (function_exists($uninstallfunction)) {
228                 debugging("{$uninstallfunction}() has been deprecated. Use the plugin's db/uninstall.php instead", DEBUG_DEVELOPER);
229                 if (!$uninstallfunction()) {
230                     echo $OUTPUT->notification('Encountered a problem running uninstall function for '. $module->name.'!');
231                 }
232             }
233         }
235     } else if ($type === 'enrol') {
236         // NOTE: this is a bit brute force way - it will not trigger events and hooks properly
237         // nuke all role assignments
238         role_unassign_all(array('component'=>$component));
239         // purge participants
240         $DB->delete_records_select('user_enrolments', "enrolid IN (SELECT id FROM {enrol} WHERE enrol = ?)", array($name));
241         // purge enrol instances
242         $DB->delete_records('enrol', array('enrol'=>$name));
243         // tweak enrol settings
244         if (!empty($CFG->enrol_plugins_enabled)) {
245             $enabledenrols = explode(',', $CFG->enrol_plugins_enabled);
246             $enabledenrols = array_unique($enabledenrols);
247             $enabledenrols = array_flip($enabledenrols);
248             unset($enabledenrols[$name]);
249             $enabledenrols = array_flip($enabledenrols);
250             if (is_array($enabledenrols)) {
251                 set_config('enrol_plugins_enabled', implode(',', $enabledenrols));
252             }
253         }
255     } else if ($type === 'block') {
256         if ($block = $DB->get_record('block', array('name'=>$name))) {
257             // Inform block it's about to be deleted
258             if (file_exists("$CFG->dirroot/blocks/$block->name/block_$block->name.php")) {
259                 $blockobject = block_instance($block->name);
260                 if ($blockobject) {
261                     $blockobject->before_delete();  //only if we can create instance, block might have been already removed
262                 }
263             }
265             // First delete instances and related contexts
266             $instances = $DB->get_records('block_instances', array('blockname' => $block->name));
267             foreach($instances as $instance) {
268                 blocks_delete_instance($instance);
269             }
271             // Delete block
272             $DB->delete_records('block', array('id'=>$block->id));
273         }
274     } else if ($type === 'format') {
275         if (($defaultformat = get_config('moodlecourse', 'format')) && $defaultformat !== $name) {
276             $courses = $DB->get_records('course', array('format' => $name), 'id');
277             $data = (object)array('id' => null, 'format' => $defaultformat);
278             foreach ($courses as $record) {
279                 $data->id = $record->id;
280                 update_course($data);
281             }
282         }
283         $DB->delete_records('course_format_options', array('format' => $name));
284     }
286     // Specific plugin type cleanup.
287     $plugininfo = plugin_manager::instance()->get_plugin_info($component);
288     if ($plugininfo) {
289         $plugininfo->uninstall_cleanup();
290         plugin_manager::reset_caches();
291     }
292     $plugininfo = null;
294     // perform clean-up task common for all the plugin/subplugin types
296     //delete the web service functions and pre-built services
297     require_once($CFG->dirroot.'/lib/externallib.php');
298     external_delete_descriptions($component);
300     // delete calendar events
301     $DB->delete_records('event', array('modulename' => $pluginname));
303     // delete all the logs
304     $DB->delete_records('log', array('module' => $pluginname));
306     // delete log_display information
307     $DB->delete_records('log_display', array('component' => $component));
309     // delete the module configuration records
310     unset_all_config_for_plugin($component);
311     if ($type === 'mod') {
312         unset_all_config_for_plugin($pluginname);
313     }
315     // delete message provider
316     message_provider_uninstall($component);
318     // delete the plugin tables
319     $xmldbfilepath = $plugindirectory . '/db/install.xml';
320     drop_plugin_tables($component, $xmldbfilepath, false);
321     if ($type === 'mod' or $type === 'block') {
322         // non-frankenstyle table prefixes
323         drop_plugin_tables($name, $xmldbfilepath, false);
324     }
326     // delete the capabilities that were defined by this module
327     capabilities_cleanup($component);
329     // remove event handlers and dequeue pending events
330     events_uninstall($component);
332     // Delete all remaining files in the filepool owned by the component.
333     $fs = get_file_storage();
334     $fs->delete_component_files($component);
336     // Finally purge all caches.
337     purge_all_caches();
339     // Invalidate the hash used for upgrade detections.
340     set_config('allversionshash', '');
342     echo $OUTPUT->notification(get_string('success'), 'notifysuccess');
345 /**
346  * Returns the version of installed component
347  *
348  * @param string $component component name
349  * @param string $source either 'disk' or 'installed' - where to get the version information from
350  * @return string|bool version number or false if the component is not found
351  */
352 function get_component_version($component, $source='installed') {
353     global $CFG, $DB;
355     list($type, $name) = core_component::normalize_component($component);
357     // moodle core or a core subsystem
358     if ($type === 'core') {
359         if ($source === 'installed') {
360             if (empty($CFG->version)) {
361                 return false;
362             } else {
363                 return $CFG->version;
364             }
365         } else {
366             if (!is_readable($CFG->dirroot.'/version.php')) {
367                 return false;
368             } else {
369                 $version = null; //initialize variable for IDEs
370                 include($CFG->dirroot.'/version.php');
371                 return $version;
372             }
373         }
374     }
376     // activity module
377     if ($type === 'mod') {
378         if ($source === 'installed') {
379             return $DB->get_field('modules', 'version', array('name'=>$name));
380         } else {
381             $mods = core_component::get_plugin_list('mod');
382             if (empty($mods[$name]) or !is_readable($mods[$name].'/version.php')) {
383                 return false;
384             } else {
385                 $plugin = new stdClass();
386                 $plugin->version = null;
387                 $module = $plugin;
388                 include($mods[$name].'/version.php');
389                 return $plugin->version;
390             }
391         }
392     }
394     // block
395     if ($type === 'block') {
396         if ($source === 'installed') {
397             return $DB->get_field('block', 'version', array('name'=>$name));
398         } else {
399             $blocks = core_component::get_plugin_list('block');
400             if (empty($blocks[$name]) or !is_readable($blocks[$name].'/version.php')) {
401                 return false;
402             } else {
403                 $plugin = new stdclass();
404                 include($blocks[$name].'/version.php');
405                 return $plugin->version;
406             }
407         }
408     }
410     // all other plugin types
411     if ($source === 'installed') {
412         return get_config($type.'_'.$name, 'version');
413     } else {
414         $plugins = core_component::get_plugin_list($type);
415         if (empty($plugins[$name])) {
416             return false;
417         } else {
418             $plugin = new stdclass();
419             include($plugins[$name].'/version.php');
420             return $plugin->version;
421         }
422     }
425 /**
426  * Delete all plugin tables
427  *
428  * @param string $name Name of plugin, used as table prefix
429  * @param string $file Path to install.xml file
430  * @param bool $feedback defaults to true
431  * @return bool Always returns true
432  */
433 function drop_plugin_tables($name, $file, $feedback=true) {
434     global $CFG, $DB;
436     // first try normal delete
437     if (file_exists($file) and $DB->get_manager()->delete_tables_from_xmldb_file($file)) {
438         return true;
439     }
441     // then try to find all tables that start with name and are not in any xml file
442     $used_tables = get_used_table_names();
444     $tables = $DB->get_tables();
446     /// Iterate over, fixing id fields as necessary
447     foreach ($tables as $table) {
448         if (in_array($table, $used_tables)) {
449             continue;
450         }
452         if (strpos($table, $name) !== 0) {
453             continue;
454         }
456         // found orphan table --> delete it
457         if ($DB->get_manager()->table_exists($table)) {
458             $xmldb_table = new xmldb_table($table);
459             $DB->get_manager()->drop_table($xmldb_table);
460         }
461     }
463     return true;
466 /**
467  * Returns names of all known tables == tables that moodle knows about.
468  *
469  * @return array Array of lowercase table names
470  */
471 function get_used_table_names() {
472     $table_names = array();
473     $dbdirs = get_db_directories();
475     foreach ($dbdirs as $dbdir) {
476         $file = $dbdir.'/install.xml';
478         $xmldb_file = new xmldb_file($file);
480         if (!$xmldb_file->fileExists()) {
481             continue;
482         }
484         $loaded    = $xmldb_file->loadXMLStructure();
485         $structure = $xmldb_file->getStructure();
487         if ($loaded and $tables = $structure->getTables()) {
488             foreach($tables as $table) {
489                 $table_names[] = strtolower($table->getName());
490             }
491         }
492     }
494     return $table_names;
497 /**
498  * Returns list of all directories where we expect install.xml files
499  * @return array Array of paths
500  */
501 function get_db_directories() {
502     global $CFG;
504     $dbdirs = array();
506     /// First, the main one (lib/db)
507     $dbdirs[] = $CFG->libdir.'/db';
509     /// Then, all the ones defined by core_component::get_plugin_types()
510     $plugintypes = core_component::get_plugin_types();
511     foreach ($plugintypes as $plugintype => $pluginbasedir) {
512         if ($plugins = core_component::get_plugin_list($plugintype)) {
513             foreach ($plugins as $plugin => $plugindir) {
514                 $dbdirs[] = $plugindir.'/db';
515             }
516         }
517     }
519     return $dbdirs;
522 /**
523  * Try to obtain or release the cron lock.
524  * @param string  $name  name of lock
525  * @param int  $until timestamp when this lock considered stale, null means remove lock unconditionally
526  * @param bool $ignorecurrent ignore current lock state, usually extend previous lock, defaults to false
527  * @return bool true if lock obtained
528  */
529 function set_cron_lock($name, $until, $ignorecurrent=false) {
530     global $DB;
531     if (empty($name)) {
532         debugging("Tried to get a cron lock for a null fieldname");
533         return false;
534     }
536     // remove lock by force == remove from config table
537     if (is_null($until)) {
538         set_config($name, null);
539         return true;
540     }
542     if (!$ignorecurrent) {
543         // read value from db - other processes might have changed it
544         $value = $DB->get_field('config', 'value', array('name'=>$name));
546         if ($value and $value > time()) {
547             //lock active
548             return false;
549         }
550     }
552     set_config($name, $until);
553     return true;
556 /**
557  * Test if and critical warnings are present
558  * @return bool
559  */
560 function admin_critical_warnings_present() {
561     global $SESSION;
563     if (!has_capability('moodle/site:config', context_system::instance())) {
564         return 0;
565     }
567     if (!isset($SESSION->admin_critical_warning)) {
568         $SESSION->admin_critical_warning = 0;
569         if (is_dataroot_insecure(true) === INSECURE_DATAROOT_ERROR) {
570             $SESSION->admin_critical_warning = 1;
571         }
572     }
574     return $SESSION->admin_critical_warning;
577 /**
578  * Detects if float supports at least 10 decimal digits
579  *
580  * Detects if float supports at least 10 decimal digits
581  * and also if float-->string conversion works as expected.
582  *
583  * @return bool true if problem found
584  */
585 function is_float_problem() {
586     $num1 = 2009010200.01;
587     $num2 = 2009010200.02;
589     return ((string)$num1 === (string)$num2 or $num1 === $num2 or $num2 <= (string)$num1);
592 /**
593  * Try to verify that dataroot is not accessible from web.
594  *
595  * Try to verify that dataroot is not accessible from web.
596  * It is not 100% correct but might help to reduce number of vulnerable sites.
597  * Protection from httpd.conf and .htaccess is not detected properly.
598  *
599  * @uses INSECURE_DATAROOT_WARNING
600  * @uses INSECURE_DATAROOT_ERROR
601  * @param bool $fetchtest try to test public access by fetching file, default false
602  * @return mixed empty means secure, INSECURE_DATAROOT_ERROR found a critical problem, INSECURE_DATAROOT_WARNING might be problematic
603  */
604 function is_dataroot_insecure($fetchtest=false) {
605     global $CFG;
607     $siteroot = str_replace('\\', '/', strrev($CFG->dirroot.'/')); // win32 backslash workaround
609     $rp = preg_replace('|https?://[^/]+|i', '', $CFG->wwwroot, 1);
610     $rp = strrev(trim($rp, '/'));
611     $rp = explode('/', $rp);
612     foreach($rp as $r) {
613         if (strpos($siteroot, '/'.$r.'/') === 0) {
614             $siteroot = substr($siteroot, strlen($r)+1); // moodle web in subdirectory
615         } else {
616             break; // probably alias root
617         }
618     }
620     $siteroot = strrev($siteroot);
621     $dataroot = str_replace('\\', '/', $CFG->dataroot.'/');
623     if (strpos($dataroot, $siteroot) !== 0) {
624         return false;
625     }
627     if (!$fetchtest) {
628         return INSECURE_DATAROOT_WARNING;
629     }
631     // now try all methods to fetch a test file using http protocol
633     $httpdocroot = str_replace('\\', '/', strrev($CFG->dirroot.'/'));
634     preg_match('|(https?://[^/]+)|i', $CFG->wwwroot, $matches);
635     $httpdocroot = $matches[1];
636     $datarooturl = $httpdocroot.'/'. substr($dataroot, strlen($siteroot));
637     make_upload_directory('diag');
638     $testfile = $CFG->dataroot.'/diag/public.txt';
639     if (!file_exists($testfile)) {
640         file_put_contents($testfile, 'test file, do not delete');
641         @chmod($testfile, $CFG->filepermissions);
642     }
643     $teststr = trim(file_get_contents($testfile));
644     if (empty($teststr)) {
645     // hmm, strange
646         return INSECURE_DATAROOT_WARNING;
647     }
649     $testurl = $datarooturl.'/diag/public.txt';
650     if (extension_loaded('curl') and
651         !(stripos(ini_get('disable_functions'), 'curl_init') !== FALSE) and
652         !(stripos(ini_get('disable_functions'), 'curl_setop') !== FALSE) and
653         ($ch = @curl_init($testurl)) !== false) {
654         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
655         curl_setopt($ch, CURLOPT_HEADER, false);
656         $data = curl_exec($ch);
657         if (!curl_errno($ch)) {
658             $data = trim($data);
659             if ($data === $teststr) {
660                 curl_close($ch);
661                 return INSECURE_DATAROOT_ERROR;
662             }
663         }
664         curl_close($ch);
665     }
667     if ($data = @file_get_contents($testurl)) {
668         $data = trim($data);
669         if ($data === $teststr) {
670             return INSECURE_DATAROOT_ERROR;
671         }
672     }
674     preg_match('|https?://([^/]+)|i', $testurl, $matches);
675     $sitename = $matches[1];
676     $error = 0;
677     if ($fp = @fsockopen($sitename, 80, $error)) {
678         preg_match('|https?://[^/]+(.*)|i', $testurl, $matches);
679         $localurl = $matches[1];
680         $out = "GET $localurl HTTP/1.1\r\n";
681         $out .= "Host: $sitename\r\n";
682         $out .= "Connection: Close\r\n\r\n";
683         fwrite($fp, $out);
684         $data = '';
685         $incoming = false;
686         while (!feof($fp)) {
687             if ($incoming) {
688                 $data .= fgets($fp, 1024);
689             } else if (@fgets($fp, 1024) === "\r\n") {
690                     $incoming = true;
691                 }
692         }
693         fclose($fp);
694         $data = trim($data);
695         if ($data === $teststr) {
696             return INSECURE_DATAROOT_ERROR;
697         }
698     }
700     return INSECURE_DATAROOT_WARNING;
703 /**
704  * Enables CLI maintenance mode by creating new dataroot/climaintenance.html file.
705  */
706 function enable_cli_maintenance_mode() {
707     global $CFG;
709     if (file_exists("$CFG->dataroot/climaintenance.html")) {
710         unlink("$CFG->dataroot/climaintenance.html");
711     }
713     if (isset($CFG->maintenance_message) and !html_is_blank($CFG->maintenance_message)) {
714         $data = $CFG->maintenance_message;
715         $data = bootstrap_renderer::early_error_content($data, null, null, null);
716         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
718     } else if (file_exists("$CFG->dataroot/climaintenance.template.html")) {
719         $data = file_get_contents("$CFG->dataroot/climaintenance.template.html");
721     } else {
722         $data = get_string('sitemaintenance', 'admin');
723         $data = bootstrap_renderer::early_error_content($data, null, null, null);
724         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
725     }
727     file_put_contents("$CFG->dataroot/climaintenance.html", $data);
728     chmod("$CFG->dataroot/climaintenance.html", $CFG->filepermissions);
731 /// CLASS DEFINITIONS /////////////////////////////////////////////////////////
734 /**
735  * Interface for anything appearing in the admin tree
736  *
737  * The interface that is implemented by anything that appears in the admin tree
738  * block. It forces inheriting classes to define a method for checking user permissions
739  * and methods for finding something in the admin tree.
740  *
741  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
742  */
743 interface part_of_admin_tree {
745 /**
746  * Finds a named part_of_admin_tree.
747  *
748  * Used to find a part_of_admin_tree. If a class only inherits part_of_admin_tree
749  * and not parentable_part_of_admin_tree, then this function should only check if
750  * $this->name matches $name. If it does, it should return a reference to $this,
751  * otherwise, it should return a reference to NULL.
752  *
753  * If a class inherits parentable_part_of_admin_tree, this method should be called
754  * recursively on all child objects (assuming, of course, the parent object's name
755  * doesn't match the search criterion).
756  *
757  * @param string $name The internal name of the part_of_admin_tree we're searching for.
758  * @return mixed An object reference or a NULL reference.
759  */
760     public function locate($name);
762     /**
763      * Removes named part_of_admin_tree.
764      *
765      * @param string $name The internal name of the part_of_admin_tree we want to remove.
766      * @return bool success.
767      */
768     public function prune($name);
770     /**
771      * Search using query
772      * @param string $query
773      * @return mixed array-object structure of found settings and pages
774      */
775     public function search($query);
777     /**
778      * Verifies current user's access to this part_of_admin_tree.
779      *
780      * Used to check if the current user has access to this part of the admin tree or
781      * not. If a class only inherits part_of_admin_tree and not parentable_part_of_admin_tree,
782      * then this method is usually just a call to has_capability() in the site context.
783      *
784      * If a class inherits parentable_part_of_admin_tree, this method should return the
785      * logical OR of the return of check_access() on all child objects.
786      *
787      * @return bool True if the user has access, false if she doesn't.
788      */
789     public function check_access();
791     /**
792      * Mostly useful for removing of some parts of the tree in admin tree block.
793      *
794      * @return True is hidden from normal list view
795      */
796     public function is_hidden();
798     /**
799      * Show we display Save button at the page bottom?
800      * @return bool
801      */
802     public function show_save();
806 /**
807  * Interface implemented by any part_of_admin_tree that has children.
808  *
809  * The interface implemented by any part_of_admin_tree that can be a parent
810  * to other part_of_admin_tree's. (For now, this only includes admin_category.) Apart
811  * from ensuring part_of_admin_tree compliancy, it also ensures inheriting methods
812  * include an add method for adding other part_of_admin_tree objects as children.
813  *
814  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
815  */
816 interface parentable_part_of_admin_tree extends part_of_admin_tree {
818 /**
819  * Adds a part_of_admin_tree object to the admin tree.
820  *
821  * Used to add a part_of_admin_tree object to this object or a child of this
822  * object. $something should only be added if $destinationname matches
823  * $this->name. If it doesn't, add should be called on child objects that are
824  * also parentable_part_of_admin_tree's.
825  *
826  * $something should be appended as the last child in the $destinationname. If the
827  * $beforesibling is specified, $something should be prepended to it. If the given
828  * sibling is not found, $something should be appended to the end of $destinationname
829  * and a developer debugging message should be displayed.
830  *
831  * @param string $destinationname The internal name of the new parent for $something.
832  * @param part_of_admin_tree $something The object to be added.
833  * @return bool True on success, false on failure.
834  */
835     public function add($destinationname, $something, $beforesibling = null);
840 /**
841  * The object used to represent folders (a.k.a. categories) in the admin tree block.
842  *
843  * Each admin_category object contains a number of part_of_admin_tree objects.
844  *
845  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
846  */
847 class admin_category implements parentable_part_of_admin_tree {
849     /** @var mixed An array of part_of_admin_tree objects that are this object's children */
850     public $children;
851     /** @var string An internal name for this category. Must be unique amongst ALL part_of_admin_tree objects */
852     public $name;
853     /** @var string The displayed name for this category. Usually obtained through get_string() */
854     public $visiblename;
855     /** @var bool Should this category be hidden in admin tree block? */
856     public $hidden;
857     /** @var mixed Either a string or an array or strings */
858     public $path;
859     /** @var mixed Either a string or an array or strings */
860     public $visiblepath;
862     /** @var array fast lookup category cache, all categories of one tree point to one cache */
863     protected $category_cache;
865     /**
866      * Constructor for an empty admin category
867      *
868      * @param string $name The internal name for this category. Must be unique amongst ALL part_of_admin_tree objects
869      * @param string $visiblename The displayed named for this category. Usually obtained through get_string()
870      * @param bool $hidden hide category in admin tree block, defaults to false
871      */
872     public function __construct($name, $visiblename, $hidden=false) {
873         $this->children    = array();
874         $this->name        = $name;
875         $this->visiblename = $visiblename;
876         $this->hidden      = $hidden;
877     }
879     /**
880      * Returns a reference to the part_of_admin_tree object with internal name $name.
881      *
882      * @param string $name The internal name of the object we want.
883      * @param bool $findpath initialize path and visiblepath arrays
884      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
885      *                  defaults to false
886      */
887     public function locate($name, $findpath=false) {
888         if (!isset($this->category_cache[$this->name])) {
889             // somebody much have purged the cache
890             $this->category_cache[$this->name] = $this;
891         }
893         if ($this->name == $name) {
894             if ($findpath) {
895                 $this->visiblepath[] = $this->visiblename;
896                 $this->path[]        = $this->name;
897             }
898             return $this;
899         }
901         // quick category lookup
902         if (!$findpath and isset($this->category_cache[$name])) {
903             return $this->category_cache[$name];
904         }
906         $return = NULL;
907         foreach($this->children as $childid=>$unused) {
908             if ($return = $this->children[$childid]->locate($name, $findpath)) {
909                 break;
910             }
911         }
913         if (!is_null($return) and $findpath) {
914             $return->visiblepath[] = $this->visiblename;
915             $return->path[]        = $this->name;
916         }
918         return $return;
919     }
921     /**
922      * Search using query
923      *
924      * @param string query
925      * @return mixed array-object structure of found settings and pages
926      */
927     public function search($query) {
928         $result = array();
929         foreach ($this->children as $child) {
930             $subsearch = $child->search($query);
931             if (!is_array($subsearch)) {
932                 debugging('Incorrect search result from '.$child->name);
933                 continue;
934             }
935             $result = array_merge($result, $subsearch);
936         }
937         return $result;
938     }
940     /**
941      * Removes part_of_admin_tree object with internal name $name.
942      *
943      * @param string $name The internal name of the object we want to remove.
944      * @return bool success
945      */
946     public function prune($name) {
948         if ($this->name == $name) {
949             return false;  //can not remove itself
950         }
952         foreach($this->children as $precedence => $child) {
953             if ($child->name == $name) {
954                 // clear cache and delete self
955                 while($this->category_cache) {
956                     // delete the cache, but keep the original array address
957                     array_pop($this->category_cache);
958                 }
959                 unset($this->children[$precedence]);
960                 return true;
961             } else if ($this->children[$precedence]->prune($name)) {
962                 return true;
963             }
964         }
965         return false;
966     }
968     /**
969      * Adds a part_of_admin_tree to a child or grandchild (or great-grandchild, and so forth) of this object.
970      *
971      * By default the new part of the tree is appended as the last child of the parent. You
972      * can specify a sibling node that the new part should be prepended to. If the given
973      * sibling is not found, the part is appended to the end (as it would be by default) and
974      * a developer debugging message is displayed.
975      *
976      * @throws coding_exception if the $beforesibling is empty string or is not string at all.
977      * @param string $destinationame The internal name of the immediate parent that we want for $something.
978      * @param mixed $something A part_of_admin_tree or setting instance to be added.
979      * @param string $beforesibling The name of the parent's child the $something should be prepended to.
980      * @return bool True if successfully added, false if $something can not be added.
981      */
982     public function add($parentname, $something, $beforesibling = null) {
983         global $CFG;
985         $parent = $this->locate($parentname);
986         if (is_null($parent)) {
987             debugging('parent does not exist!');
988             return false;
989         }
991         if ($something instanceof part_of_admin_tree) {
992             if (!($parent instanceof parentable_part_of_admin_tree)) {
993                 debugging('error - parts of tree can be inserted only into parentable parts');
994                 return false;
995             }
996             if ($CFG->debugdeveloper && !is_null($this->locate($something->name))) {
997                 // The name of the node is already used, simply warn the developer that this should not happen.
998                 // It is intentional to check for the debug level before performing the check.
999                 debugging('Duplicate admin page name: ' . $something->name, DEBUG_DEVELOPER);
1000             }
1001             if (is_null($beforesibling)) {
1002                 // Append $something as the parent's last child.
1003                 $parent->children[] = $something;
1004             } else {
1005                 if (!is_string($beforesibling) or trim($beforesibling) === '') {
1006                     throw new coding_exception('Unexpected value of the beforesibling parameter');
1007                 }
1008                 // Try to find the position of the sibling.
1009                 $siblingposition = null;
1010                 foreach ($parent->children as $childposition => $child) {
1011                     if ($child->name === $beforesibling) {
1012                         $siblingposition = $childposition;
1013                         break;
1014                     }
1015                 }
1016                 if (is_null($siblingposition)) {
1017                     debugging('Sibling '.$beforesibling.' not found', DEBUG_DEVELOPER);
1018                     $parent->children[] = $something;
1019                 } else {
1020                     $parent->children = array_merge(
1021                         array_slice($parent->children, 0, $siblingposition),
1022                         array($something),
1023                         array_slice($parent->children, $siblingposition)
1024                     );
1025                 }
1026             }
1027             if ($something instanceof admin_category) {
1028                 if (isset($this->category_cache[$something->name])) {
1029                     debugging('Duplicate admin category name: '.$something->name);
1030                 } else {
1031                     $this->category_cache[$something->name] = $something;
1032                     $something->category_cache =& $this->category_cache;
1033                     foreach ($something->children as $child) {
1034                         // just in case somebody already added subcategories
1035                         if ($child instanceof admin_category) {
1036                             if (isset($this->category_cache[$child->name])) {
1037                                 debugging('Duplicate admin category name: '.$child->name);
1038                             } else {
1039                                 $this->category_cache[$child->name] = $child;
1040                                 $child->category_cache =& $this->category_cache;
1041                             }
1042                         }
1043                     }
1044                 }
1045             }
1046             return true;
1048         } else {
1049             debugging('error - can not add this element');
1050             return false;
1051         }
1053     }
1055     /**
1056      * Checks if the user has access to anything in this category.
1057      *
1058      * @return bool True if the user has access to at least one child in this category, false otherwise.
1059      */
1060     public function check_access() {
1061         foreach ($this->children as $child) {
1062             if ($child->check_access()) {
1063                 return true;
1064             }
1065         }
1066         return false;
1067     }
1069     /**
1070      * Is this category hidden in admin tree block?
1071      *
1072      * @return bool True if hidden
1073      */
1074     public function is_hidden() {
1075         return $this->hidden;
1076     }
1078     /**
1079      * Show we display Save button at the page bottom?
1080      * @return bool
1081      */
1082     public function show_save() {
1083         foreach ($this->children as $child) {
1084             if ($child->show_save()) {
1085                 return true;
1086             }
1087         }
1088         return false;
1089     }
1093 /**
1094  * Root of admin settings tree, does not have any parent.
1095  *
1096  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1097  */
1098 class admin_root extends admin_category {
1099 /** @var array List of errors */
1100     public $errors;
1101     /** @var string search query */
1102     public $search;
1103     /** @var bool full tree flag - true means all settings required, false only pages required */
1104     public $fulltree;
1105     /** @var bool flag indicating loaded tree */
1106     public $loaded;
1107     /** @var mixed site custom defaults overriding defaults in settings files*/
1108     public $custom_defaults;
1110     /**
1111      * @param bool $fulltree true means all settings required,
1112      *                            false only pages required
1113      */
1114     public function __construct($fulltree) {
1115         global $CFG;
1117         parent::__construct('root', get_string('administration'), false);
1118         $this->errors   = array();
1119         $this->search   = '';
1120         $this->fulltree = $fulltree;
1121         $this->loaded   = false;
1123         $this->category_cache = array();
1125         // load custom defaults if found
1126         $this->custom_defaults = null;
1127         $defaultsfile = "$CFG->dirroot/local/defaults.php";
1128         if (is_readable($defaultsfile)) {
1129             $defaults = array();
1130             include($defaultsfile);
1131             if (is_array($defaults) and count($defaults)) {
1132                 $this->custom_defaults = $defaults;
1133             }
1134         }
1135     }
1137     /**
1138      * Empties children array, and sets loaded to false
1139      *
1140      * @param bool $requirefulltree
1141      */
1142     public function purge_children($requirefulltree) {
1143         $this->children = array();
1144         $this->fulltree = ($requirefulltree || $this->fulltree);
1145         $this->loaded   = false;
1146         //break circular dependencies - this helps PHP 5.2
1147         while($this->category_cache) {
1148             array_pop($this->category_cache);
1149         }
1150         $this->category_cache = array();
1151     }
1155 /**
1156  * Links external PHP pages into the admin tree.
1157  *
1158  * See detailed usage example at the top of this document (adminlib.php)
1159  *
1160  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1161  */
1162 class admin_externalpage implements part_of_admin_tree {
1164     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1165     public $name;
1167     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1168     public $visiblename;
1170     /** @var string The external URL that we should link to when someone requests this external page. */
1171     public $url;
1173     /** @var string The role capability/permission a user must have to access this external page. */
1174     public $req_capability;
1176     /** @var object The context in which capability/permission should be checked, default is site context. */
1177     public $context;
1179     /** @var bool hidden in admin tree block. */
1180     public $hidden;
1182     /** @var mixed either string or array of string */
1183     public $path;
1185     /** @var array list of visible names of page parents */
1186     public $visiblepath;
1188     /**
1189      * Constructor for adding an external page into the admin tree.
1190      *
1191      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1192      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1193      * @param string $url The external URL that we should link to when someone requests this external page.
1194      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1195      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1196      * @param stdClass $context The context the page relates to. Not sure what happens
1197      *      if you specify something other than system or front page. Defaults to system.
1198      */
1199     public function __construct($name, $visiblename, $url, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1200         $this->name        = $name;
1201         $this->visiblename = $visiblename;
1202         $this->url         = $url;
1203         if (is_array($req_capability)) {
1204             $this->req_capability = $req_capability;
1205         } else {
1206             $this->req_capability = array($req_capability);
1207         }
1208         $this->hidden = $hidden;
1209         $this->context = $context;
1210     }
1212     /**
1213      * Returns a reference to the part_of_admin_tree object with internal name $name.
1214      *
1215      * @param string $name The internal name of the object we want.
1216      * @param bool $findpath defaults to false
1217      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
1218      */
1219     public function locate($name, $findpath=false) {
1220         if ($this->name == $name) {
1221             if ($findpath) {
1222                 $this->visiblepath = array($this->visiblename);
1223                 $this->path        = array($this->name);
1224             }
1225             return $this;
1226         } else {
1227             $return = NULL;
1228             return $return;
1229         }
1230     }
1232     /**
1233      * This function always returns false, required function by interface
1234      *
1235      * @param string $name
1236      * @return false
1237      */
1238     public function prune($name) {
1239         return false;
1240     }
1242     /**
1243      * Search using query
1244      *
1245      * @param string $query
1246      * @return mixed array-object structure of found settings and pages
1247      */
1248     public function search($query) {
1249         $found = false;
1250         if (strpos(strtolower($this->name), $query) !== false) {
1251             $found = true;
1252         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1253                 $found = true;
1254             }
1255         if ($found) {
1256             $result = new stdClass();
1257             $result->page     = $this;
1258             $result->settings = array();
1259             return array($this->name => $result);
1260         } else {
1261             return array();
1262         }
1263     }
1265     /**
1266      * Determines if the current user has access to this external page based on $this->req_capability.
1267      *
1268      * @return bool True if user has access, false otherwise.
1269      */
1270     public function check_access() {
1271         global $CFG;
1272         $context = empty($this->context) ? context_system::instance() : $this->context;
1273         foreach($this->req_capability as $cap) {
1274             if (has_capability($cap, $context)) {
1275                 return true;
1276             }
1277         }
1278         return false;
1279     }
1281     /**
1282      * Is this external page hidden in admin tree block?
1283      *
1284      * @return bool True if hidden
1285      */
1286     public function is_hidden() {
1287         return $this->hidden;
1288     }
1290     /**
1291      * Show we display Save button at the page bottom?
1292      * @return bool
1293      */
1294     public function show_save() {
1295         return false;
1296     }
1300 /**
1301  * Used to group a number of admin_setting objects into a page and add them to the admin tree.
1302  *
1303  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1304  */
1305 class admin_settingpage implements part_of_admin_tree {
1307     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1308     public $name;
1310     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1311     public $visiblename;
1313     /** @var mixed An array of admin_setting objects that are part of this setting page. */
1314     public $settings;
1316     /** @var string The role capability/permission a user must have to access this external page. */
1317     public $req_capability;
1319     /** @var object The context in which capability/permission should be checked, default is site context. */
1320     public $context;
1322     /** @var bool hidden in admin tree block. */
1323     public $hidden;
1325     /** @var mixed string of paths or array of strings of paths */
1326     public $path;
1328     /** @var array list of visible names of page parents */
1329     public $visiblepath;
1331     /**
1332      * see admin_settingpage for details of this function
1333      *
1334      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1335      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1336      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1337      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1338      * @param stdClass $context The context the page relates to. Not sure what happens
1339      *      if you specify something other than system or front page. Defaults to system.
1340      */
1341     public function __construct($name, $visiblename, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1342         $this->settings    = new stdClass();
1343         $this->name        = $name;
1344         $this->visiblename = $visiblename;
1345         if (is_array($req_capability)) {
1346             $this->req_capability = $req_capability;
1347         } else {
1348             $this->req_capability = array($req_capability);
1349         }
1350         $this->hidden      = $hidden;
1351         $this->context     = $context;
1352     }
1354     /**
1355      * see admin_category
1356      *
1357      * @param string $name
1358      * @param bool $findpath
1359      * @return mixed Object (this) if name ==  this->name, else returns null
1360      */
1361     public function locate($name, $findpath=false) {
1362         if ($this->name == $name) {
1363             if ($findpath) {
1364                 $this->visiblepath = array($this->visiblename);
1365                 $this->path        = array($this->name);
1366             }
1367             return $this;
1368         } else {
1369             $return = NULL;
1370             return $return;
1371         }
1372     }
1374     /**
1375      * Search string in settings page.
1376      *
1377      * @param string $query
1378      * @return array
1379      */
1380     public function search($query) {
1381         $found = array();
1383         foreach ($this->settings as $setting) {
1384             if ($setting->is_related($query)) {
1385                 $found[] = $setting;
1386             }
1387         }
1389         if ($found) {
1390             $result = new stdClass();
1391             $result->page     = $this;
1392             $result->settings = $found;
1393             return array($this->name => $result);
1394         }
1396         $found = false;
1397         if (strpos(strtolower($this->name), $query) !== false) {
1398             $found = true;
1399         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1400                 $found = true;
1401             }
1402         if ($found) {
1403             $result = new stdClass();
1404             $result->page     = $this;
1405             $result->settings = array();
1406             return array($this->name => $result);
1407         } else {
1408             return array();
1409         }
1410     }
1412     /**
1413      * This function always returns false, required by interface
1414      *
1415      * @param string $name
1416      * @return bool Always false
1417      */
1418     public function prune($name) {
1419         return false;
1420     }
1422     /**
1423      * adds an admin_setting to this admin_settingpage
1424      *
1425      * not the same as add for admin_category. adds an admin_setting to this admin_settingpage. settings appear (on the settingpage) in the order in which they're added
1426      * n.b. each admin_setting in an admin_settingpage must have a unique internal name
1427      *
1428      * @param object $setting is the admin_setting object you want to add
1429      * @return bool true if successful, false if not
1430      */
1431     public function add($setting) {
1432         if (!($setting instanceof admin_setting)) {
1433             debugging('error - not a setting instance');
1434             return false;
1435         }
1437         $this->settings->{$setting->name} = $setting;
1438         return true;
1439     }
1441     /**
1442      * see admin_externalpage
1443      *
1444      * @return bool Returns true for yes false for no
1445      */
1446     public function check_access() {
1447         global $CFG;
1448         $context = empty($this->context) ? context_system::instance() : $this->context;
1449         foreach($this->req_capability as $cap) {
1450             if (has_capability($cap, $context)) {
1451                 return true;
1452             }
1453         }
1454         return false;
1455     }
1457     /**
1458      * outputs this page as html in a table (suitable for inclusion in an admin pagetype)
1459      * @return string Returns an XHTML string
1460      */
1461     public function output_html() {
1462         $adminroot = admin_get_root();
1463         $return = '<fieldset>'."\n".'<div class="clearer"><!-- --></div>'."\n";
1464         foreach($this->settings as $setting) {
1465             $fullname = $setting->get_full_name();
1466             if (array_key_exists($fullname, $adminroot->errors)) {
1467                 $data = $adminroot->errors[$fullname]->data;
1468             } else {
1469                 $data = $setting->get_setting();
1470                 // do not use defaults if settings not available - upgrade settings handles the defaults!
1471             }
1472             $return .= $setting->output_html($data);
1473         }
1474         $return .= '</fieldset>';
1475         return $return;
1476     }
1478     /**
1479      * Is this settings page hidden in admin tree block?
1480      *
1481      * @return bool True if hidden
1482      */
1483     public function is_hidden() {
1484         return $this->hidden;
1485     }
1487     /**
1488      * Show we display Save button at the page bottom?
1489      * @return bool
1490      */
1491     public function show_save() {
1492         foreach($this->settings as $setting) {
1493             if (empty($setting->nosave)) {
1494                 return true;
1495             }
1496         }
1497         return false;
1498     }
1502 /**
1503  * Admin settings class. Only exists on setting pages.
1504  * Read & write happens at this level; no authentication.
1505  *
1506  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1507  */
1508 abstract class admin_setting {
1509     /** @var string unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins. */
1510     public $name;
1511     /** @var string localised name */
1512     public $visiblename;
1513     /** @var string localised long description in Markdown format */
1514     public $description;
1515     /** @var mixed Can be string or array of string */
1516     public $defaultsetting;
1517     /** @var string */
1518     public $updatedcallback;
1519     /** @var mixed can be String or Null.  Null means main config table */
1520     public $plugin; // null means main config table
1521     /** @var bool true indicates this setting does not actually save anything, just information */
1522     public $nosave = false;
1523     /** @var bool if set, indicates that a change to this setting requires rebuild course cache */
1524     public $affectsmodinfo = false;
1525     /** @var array of admin_setting_flag - These are extra checkboxes attached to a setting. */
1526     private $flags = array();
1528     /**
1529      * Constructor
1530      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
1531      *                     or 'myplugin/mysetting' for ones in config_plugins.
1532      * @param string $visiblename localised name
1533      * @param string $description localised long description
1534      * @param mixed $defaultsetting string or array depending on implementation
1535      */
1536     public function __construct($name, $visiblename, $description, $defaultsetting) {
1537         $this->parse_setting_name($name);
1538         $this->visiblename    = $visiblename;
1539         $this->description    = $description;
1540         $this->defaultsetting = $defaultsetting;
1541     }
1543     /**
1544      * Generic function to add a flag to this admin setting.
1545      *
1546      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1547      * @param bool $default - The default for the flag
1548      * @param string $shortname - The shortname for this flag. Used as a suffix for the setting name.
1549      * @param string $displayname - The display name for this flag. Used as a label next to the checkbox.
1550      */
1551     protected function set_flag_options($enabled, $default, $shortname, $displayname) {
1552         if (empty($this->flags[$shortname])) {
1553             $this->flags[$shortname] = new admin_setting_flag($enabled, $default, $shortname, $displayname);
1554         } else {
1555             $this->flags[$shortname]->set_options($enabled, $default);
1556         }
1557     }
1559     /**
1560      * Set the enabled options flag on this admin setting.
1561      *
1562      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1563      * @param bool $default - The default for the flag
1564      */
1565     public function set_enabled_flag_options($enabled, $default) {
1566         $this->set_flag_options($enabled, $default, 'enabled', new lang_string('enabled', 'core_admin'));
1567     }
1569     /**
1570      * Set the advanced options flag on this admin setting.
1571      *
1572      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1573      * @param bool $default - The default for the flag
1574      */
1575     public function set_advanced_flag_options($enabled, $default) {
1576         $this->set_flag_options($enabled, $default, 'adv', new lang_string('advanced'));
1577     }
1580     /**
1581      * Set the locked options flag on this admin setting.
1582      *
1583      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1584      * @param bool $default - The default for the flag
1585      */
1586     public function set_locked_flag_options($enabled, $default) {
1587         $this->set_flag_options($enabled, $default, 'locked', new lang_string('locked', 'core_admin'));
1588     }
1590     /**
1591      * Get the currently saved value for a setting flag
1592      *
1593      * @param admin_setting_flag $flag - One of the admin_setting_flag for this admin_setting.
1594      * @return bool
1595      */
1596     public function get_setting_flag_value(admin_setting_flag $flag) {
1597         $value = $this->config_read($this->name . '_' . $flag->get_shortname());
1598         if (!isset($value)) {
1599             $value = $flag->get_default();
1600         }
1602         return !empty($value);
1603     }
1605     /**
1606      * Get the list of defaults for the flags on this setting.
1607      *
1608      * @param array of strings describing the defaults for this setting. This is appended to by this function.
1609      */
1610     public function get_setting_flag_defaults(& $defaults) {
1611         foreach ($this->flags as $flag) {
1612             if ($flag->is_enabled() && $flag->get_default()) {
1613                 $defaults[] = $flag->get_displayname();
1614             }
1615         }
1616     }
1618     /**
1619      * Output the input fields for the advanced and locked flags on this setting.
1620      *
1621      * @param bool $adv - The current value of the advanced flag.
1622      * @param bool $locked - The current value of the locked flag.
1623      * @return string $output - The html for the flags.
1624      */
1625     public function output_setting_flags() {
1626         $output = '';
1628         foreach ($this->flags as $flag) {
1629             if ($flag->is_enabled()) {
1630                 $output .= $flag->output_setting_flag($this);
1631             }
1632         }
1634         if (!empty($output)) {
1635             return html_writer::tag('span', $output, array('class' => 'adminsettingsflags'));
1636         }
1637         return $output;
1638     }
1640     /**
1641      * Write the values of the flags for this admin setting.
1642      *
1643      * @param array $data - The data submitted from the form or null to set the default value for new installs.
1644      * @return bool - true if successful.
1645      */
1646     public function write_setting_flags($data) {
1647         $result = true;
1648         foreach ($this->flags as $flag) {
1649             $result = $result && $flag->write_setting_flag($this, $data);
1650         }
1651         return $result;
1652     }
1654     /**
1655      * Set up $this->name and potentially $this->plugin
1656      *
1657      * Set up $this->name and possibly $this->plugin based on whether $name looks
1658      * like 'settingname' or 'plugin/settingname'. Also, do some sanity checking
1659      * on the names, that is, output a developer debug warning if the name
1660      * contains anything other than [a-zA-Z0-9_]+.
1661      *
1662      * @param string $name the setting name passed in to the constructor.
1663      */
1664     private function parse_setting_name($name) {
1665         $bits = explode('/', $name);
1666         if (count($bits) > 2) {
1667             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1668         }
1669         $this->name = array_pop($bits);
1670         if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->name)) {
1671             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1672         }
1673         if (!empty($bits)) {
1674             $this->plugin = array_pop($bits);
1675             if ($this->plugin === 'moodle') {
1676                 $this->plugin = null;
1677             } else if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->plugin)) {
1678                     throw new moodle_exception('invalidadminsettingname', '', '', $name);
1679                 }
1680         }
1681     }
1683     /**
1684      * Returns the fullname prefixed by the plugin
1685      * @return string
1686      */
1687     public function get_full_name() {
1688         return 's_'.$this->plugin.'_'.$this->name;
1689     }
1691     /**
1692      * Returns the ID string based on plugin and name
1693      * @return string
1694      */
1695     public function get_id() {
1696         return 'id_s_'.$this->plugin.'_'.$this->name;
1697     }
1699     /**
1700      * @param bool $affectsmodinfo If true, changes to this setting will
1701      *   cause the course cache to be rebuilt
1702      */
1703     public function set_affects_modinfo($affectsmodinfo) {
1704         $this->affectsmodinfo = $affectsmodinfo;
1705     }
1707     /**
1708      * Returns the config if possible
1709      *
1710      * @return mixed returns config if successful else null
1711      */
1712     public function config_read($name) {
1713         global $CFG;
1714         if (!empty($this->plugin)) {
1715             $value = get_config($this->plugin, $name);
1716             return $value === false ? NULL : $value;
1718         } else {
1719             if (isset($CFG->$name)) {
1720                 return $CFG->$name;
1721             } else {
1722                 return NULL;
1723             }
1724         }
1725     }
1727     /**
1728      * Used to set a config pair and log change
1729      *
1730      * @param string $name
1731      * @param mixed $value Gets converted to string if not null
1732      * @return bool Write setting to config table
1733      */
1734     public function config_write($name, $value) {
1735         global $DB, $USER, $CFG;
1737         if ($this->nosave) {
1738             return true;
1739         }
1741         // make sure it is a real change
1742         $oldvalue = get_config($this->plugin, $name);
1743         $oldvalue = ($oldvalue === false) ? null : $oldvalue; // normalise
1744         $value = is_null($value) ? null : (string)$value;
1746         if ($oldvalue === $value) {
1747             return true;
1748         }
1750         // store change
1751         set_config($name, $value, $this->plugin);
1753         // Some admin settings affect course modinfo
1754         if ($this->affectsmodinfo) {
1755             // Clear course cache for all courses
1756             rebuild_course_cache(0, true);
1757         }
1759         add_to_config_log($name, $oldvalue, $value, $this->plugin);
1761         return true; // BC only
1762     }
1764     /**
1765      * Returns current value of this setting
1766      * @return mixed array or string depending on instance, NULL means not set yet
1767      */
1768     public abstract function get_setting();
1770     /**
1771      * Returns default setting if exists
1772      * @return mixed array or string depending on instance; NULL means no default, user must supply
1773      */
1774     public function get_defaultsetting() {
1775         $adminroot =  admin_get_root(false, false);
1776         if (!empty($adminroot->custom_defaults)) {
1777             $plugin = is_null($this->plugin) ? 'moodle' : $this->plugin;
1778             if (isset($adminroot->custom_defaults[$plugin])) {
1779                 if (array_key_exists($this->name, $adminroot->custom_defaults[$plugin])) { // null is valid value here ;-)
1780                     return $adminroot->custom_defaults[$plugin][$this->name];
1781                 }
1782             }
1783         }
1784         return $this->defaultsetting;
1785     }
1787     /**
1788      * Store new setting
1789      *
1790      * @param mixed $data string or array, must not be NULL
1791      * @return string empty string if ok, string error message otherwise
1792      */
1793     public abstract function write_setting($data);
1795     /**
1796      * Return part of form with setting
1797      * This function should always be overwritten
1798      *
1799      * @param mixed $data array or string depending on setting
1800      * @param string $query
1801      * @return string
1802      */
1803     public function output_html($data, $query='') {
1804     // should be overridden
1805         return;
1806     }
1808     /**
1809      * Function called if setting updated - cleanup, cache reset, etc.
1810      * @param string $functionname Sets the function name
1811      * @return void
1812      */
1813     public function set_updatedcallback($functionname) {
1814         $this->updatedcallback = $functionname;
1815     }
1817     /**
1818      * Execute postupdatecallback if necessary.
1819      * @param mixed $original original value before write_setting()
1820      * @return bool true if changed, false if not.
1821      */
1822     public function post_write_settings($original) {
1823         // Comparison must work for arrays too.
1824         if (serialize($original) === serialize($this->get_setting())) {
1825             return false;
1826         }
1828         $callbackfunction = $this->updatedcallback;
1829         if (!empty($callbackfunction) and function_exists($callbackfunction)) {
1830             $callbackfunction($this->get_full_name());
1831         }
1832         return true;
1833     }
1835     /**
1836      * Is setting related to query text - used when searching
1837      * @param string $query
1838      * @return bool
1839      */
1840     public function is_related($query) {
1841         if (strpos(strtolower($this->name), $query) !== false) {
1842             return true;
1843         }
1844         if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1845             return true;
1846         }
1847         if (strpos(core_text::strtolower($this->description), $query) !== false) {
1848             return true;
1849         }
1850         $current = $this->get_setting();
1851         if (!is_null($current)) {
1852             if (is_string($current)) {
1853                 if (strpos(core_text::strtolower($current), $query) !== false) {
1854                     return true;
1855                 }
1856             }
1857         }
1858         $default = $this->get_defaultsetting();
1859         if (!is_null($default)) {
1860             if (is_string($default)) {
1861                 if (strpos(core_text::strtolower($default), $query) !== false) {
1862                     return true;
1863                 }
1864             }
1865         }
1866         return false;
1867     }
1870 /**
1871  * An additional option that can be applied to an admin setting.
1872  * The currently supported options are 'ADVANCED' and 'LOCKED'.
1873  *
1874  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1875  */
1876 class admin_setting_flag {
1877     /** @var bool Flag to indicate if this option can be toggled for this setting */
1878     private $enabled = false;
1879     /** @var bool Flag to indicate if this option defaults to true or false */
1880     private $default = false;
1881     /** @var string Short string used to create setting name - e.g. 'adv' */
1882     private $shortname = '';
1883     /** @var string String used as the label for this flag */
1884     private $displayname = '';
1885     /** @const Checkbox for this flag is displayed in admin page */
1886     const ENABLED = true;
1887     /** @const Checkbox for this flag is not displayed in admin page */
1888     const DISABLED = false;
1890     /**
1891      * Constructor
1892      *
1893      * @param bool $enabled Can this option can be toggled.
1894      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
1895      * @param bool $default The default checked state for this setting option.
1896      * @param string $shortname The shortname of this flag. Currently supported flags are 'locked' and 'adv'
1897      * @param string $displayname The displayname of this flag. Used as a label for the flag.
1898      */
1899     public function __construct($enabled, $default, $shortname, $displayname) {
1900         $this->shortname = $shortname;
1901         $this->displayname = $displayname;
1902         $this->set_options($enabled, $default);
1903     }
1905     /**
1906      * Update the values of this setting options class
1907      *
1908      * @param bool $enabled Can this option can be toggled.
1909      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
1910      * @param bool $default The default checked state for this setting option.
1911      */
1912     public function set_options($enabled, $default) {
1913         $this->enabled = $enabled;
1914         $this->default = $default;
1915     }
1917     /**
1918      * Should this option appear in the interface and be toggleable?
1919      *
1920      * @return bool Is it enabled?
1921      */
1922     public function is_enabled() {
1923         return $this->enabled;
1924     }
1926     /**
1927      * Should this option be checked by default?
1928      *
1929      * @return bool Is it on by default?
1930      */
1931     public function get_default() {
1932         return $this->default;
1933     }
1935     /**
1936      * Return the short name for this flag. e.g. 'adv' or 'locked'
1937      *
1938      * @return string
1939      */
1940     public function get_shortname() {
1941         return $this->shortname;
1942     }
1944     /**
1945      * Return the display name for this flag. e.g. 'Advanced' or 'Locked'
1946      *
1947      * @return string
1948      */
1949     public function get_displayname() {
1950         return $this->displayname;
1951     }
1953     /**
1954      * Save the submitted data for this flag - or set it to the default if $data is null.
1955      *
1956      * @param admin_setting $setting - The admin setting for this flag
1957      * @param array $data - The data submitted from the form or null to set the default value for new installs.
1958      * @return bool
1959      */
1960     public function write_setting_flag(admin_setting $setting, $data) {
1961         $result = true;
1962         if ($this->is_enabled()) {
1963             if (!isset($data)) {
1964                 $value = $this->get_default();
1965             } else {
1966                 $value = !empty($data[$setting->get_full_name() . '_' . $this->get_shortname()]);
1967             }
1968             $result = $setting->config_write($setting->name . '_' . $this->get_shortname(), $value);
1969         }
1971         return $result;
1973     }
1975     /**
1976      * Output the checkbox for this setting flag. Should only be called if the flag is enabled.
1977      *
1978      * @param admin_setting $setting - The admin setting for this flag
1979      * @return string - The html for the checkbox.
1980      */
1981     public function output_setting_flag(admin_setting $setting) {
1982         $value = $setting->get_setting_flag_value($this);
1983         $output = ' <input type="checkbox" class="form-checkbox" ' .
1984                         ' id="' .  $setting->get_id() . '_' . $this->get_shortname() . '" ' .
1985                         ' name="' . $setting->get_full_name() .  '_' . $this->get_shortname() . '" ' .
1986                         ' value="1" ' . ($value ? 'checked="checked"' : '') . ' />' .
1987                         ' <label for="' . $setting->get_id() . '_' . $this->get_shortname() . '">' .
1988                         $this->get_displayname() .
1989                         ' </label> ';
1990         return $output;
1991     }
1995 /**
1996  * No setting - just heading and text.
1997  *
1998  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1999  */
2000 class admin_setting_heading extends admin_setting {
2002     /**
2003      * not a setting, just text
2004      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2005      * @param string $heading heading
2006      * @param string $information text in box
2007      */
2008     public function __construct($name, $heading, $information) {
2009         $this->nosave = true;
2010         parent::__construct($name, $heading, $information, '');
2011     }
2013     /**
2014      * Always returns true
2015      * @return bool Always returns true
2016      */
2017     public function get_setting() {
2018         return true;
2019     }
2021     /**
2022      * Always returns true
2023      * @return bool Always returns true
2024      */
2025     public function get_defaultsetting() {
2026         return true;
2027     }
2029     /**
2030      * Never write settings
2031      * @return string Always returns an empty string
2032      */
2033     public function write_setting($data) {
2034     // do not write any setting
2035         return '';
2036     }
2038     /**
2039      * Returns an HTML string
2040      * @return string Returns an HTML string
2041      */
2042     public function output_html($data, $query='') {
2043         global $OUTPUT;
2044         $return = '';
2045         if ($this->visiblename != '') {
2046             $return .= $OUTPUT->heading($this->visiblename, 3, 'main');
2047         }
2048         if ($this->description != '') {
2049             $return .= $OUTPUT->box(highlight($query, markdown_to_html($this->description)), 'generalbox formsettingheading');
2050         }
2051         return $return;
2052     }
2056 /**
2057  * The most flexibly setting, user is typing text
2058  *
2059  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2060  */
2061 class admin_setting_configtext extends admin_setting {
2063     /** @var mixed int means PARAM_XXX type, string is a allowed format in regex */
2064     public $paramtype;
2065     /** @var int default field size */
2066     public $size;
2068     /**
2069      * Config text constructor
2070      *
2071      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2072      * @param string $visiblename localised
2073      * @param string $description long localised info
2074      * @param string $defaultsetting
2075      * @param mixed $paramtype int means PARAM_XXX type, string is a allowed format in regex
2076      * @param int $size default field size
2077      */
2078     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $size=null) {
2079         $this->paramtype = $paramtype;
2080         if (!is_null($size)) {
2081             $this->size  = $size;
2082         } else {
2083             $this->size  = ($paramtype === PARAM_INT) ? 5 : 30;
2084         }
2085         parent::__construct($name, $visiblename, $description, $defaultsetting);
2086     }
2088     /**
2089      * Return the setting
2090      *
2091      * @return mixed returns config if successful else null
2092      */
2093     public function get_setting() {
2094         return $this->config_read($this->name);
2095     }
2097     public function write_setting($data) {
2098         if ($this->paramtype === PARAM_INT and $data === '') {
2099         // do not complain if '' used instead of 0
2100             $data = 0;
2101         }
2102         // $data is a string
2103         $validated = $this->validate($data);
2104         if ($validated !== true) {
2105             return $validated;
2106         }
2107         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2108     }
2110     /**
2111      * Validate data before storage
2112      * @param string data
2113      * @return mixed true if ok string if error found
2114      */
2115     public function validate($data) {
2116         // allow paramtype to be a custom regex if it is the form of /pattern/
2117         if (preg_match('#^/.*/$#', $this->paramtype)) {
2118             if (preg_match($this->paramtype, $data)) {
2119                 return true;
2120             } else {
2121                 return get_string('validateerror', 'admin');
2122             }
2124         } else if ($this->paramtype === PARAM_RAW) {
2125             return true;
2127         } else {
2128             $cleaned = clean_param($data, $this->paramtype);
2129             if ("$data" === "$cleaned") { // implicit conversion to string is needed to do exact comparison
2130                 return true;
2131             } else {
2132                 return get_string('validateerror', 'admin');
2133             }
2134         }
2135     }
2137     /**
2138      * Return an XHTML string for the setting
2139      * @return string Returns an XHTML string
2140      */
2141     public function output_html($data, $query='') {
2142         $default = $this->get_defaultsetting();
2144         return format_admin_setting($this, $this->visiblename,
2145         '<div class="form-text defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" /></div>',
2146         $this->description, true, '', $default, $query);
2147     }
2151 /**
2152  * General text area without html editor.
2153  *
2154  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2155  */
2156 class admin_setting_configtextarea extends admin_setting_configtext {
2157     private $rows;
2158     private $cols;
2160     /**
2161      * @param string $name
2162      * @param string $visiblename
2163      * @param string $description
2164      * @param mixed $defaultsetting string or array
2165      * @param mixed $paramtype
2166      * @param string $cols The number of columns to make the editor
2167      * @param string $rows The number of rows to make the editor
2168      */
2169     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2170         $this->rows = $rows;
2171         $this->cols = $cols;
2172         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
2173     }
2175     /**
2176      * Returns an XHTML string for the editor
2177      *
2178      * @param string $data
2179      * @param string $query
2180      * @return string XHTML string for the editor
2181      */
2182     public function output_html($data, $query='') {
2183         $default = $this->get_defaultsetting();
2185         $defaultinfo = $default;
2186         if (!is_null($default) and $default !== '') {
2187             $defaultinfo = "\n".$default;
2188         }
2190         return format_admin_setting($this, $this->visiblename,
2191         '<div class="form-textarea" ><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'" spellcheck="true">'. s($data) .'</textarea></div>',
2192         $this->description, true, '', $defaultinfo, $query);
2193     }
2197 /**
2198  * General text area with html editor.
2199  */
2200 class admin_setting_confightmleditor extends admin_setting_configtext {
2201     private $rows;
2202     private $cols;
2204     /**
2205      * @param string $name
2206      * @param string $visiblename
2207      * @param string $description
2208      * @param mixed $defaultsetting string or array
2209      * @param mixed $paramtype
2210      */
2211     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2212         $this->rows = $rows;
2213         $this->cols = $cols;
2214         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
2215         editors_head_setup();
2216     }
2218     /**
2219      * Returns an XHTML string for the editor
2220      *
2221      * @param string $data
2222      * @param string $query
2223      * @return string XHTML string for the editor
2224      */
2225     public function output_html($data, $query='') {
2226         $default = $this->get_defaultsetting();
2228         $defaultinfo = $default;
2229         if (!is_null($default) and $default !== '') {
2230             $defaultinfo = "\n".$default;
2231         }
2233         $editor = editors_get_preferred_editor(FORMAT_HTML);
2234         $editor->use_editor($this->get_id(), array('noclean'=>true));
2236         return format_admin_setting($this, $this->visiblename,
2237         '<div class="form-textarea"><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'" spellcheck="true">'. s($data) .'</textarea></div>',
2238         $this->description, true, '', $defaultinfo, $query);
2239     }
2243 /**
2244  * Password field, allows unmasking of password
2245  *
2246  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2247  */
2248 class admin_setting_configpasswordunmask extends admin_setting_configtext {
2249     /**
2250      * Constructor
2251      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2252      * @param string $visiblename localised
2253      * @param string $description long localised info
2254      * @param string $defaultsetting default password
2255      */
2256     public function __construct($name, $visiblename, $description, $defaultsetting) {
2257         parent::__construct($name, $visiblename, $description, $defaultsetting, PARAM_RAW, 30);
2258     }
2260     /**
2261      * Returns XHTML for the field
2262      * Writes Javascript into the HTML below right before the last div
2263      *
2264      * @todo Make javascript available through newer methods if possible
2265      * @param string $data Value for the field
2266      * @param string $query Passed as final argument for format_admin_setting
2267      * @return string XHTML field
2268      */
2269     public function output_html($data, $query='') {
2270         $id = $this->get_id();
2271         $unmask = get_string('unmaskpassword', 'form');
2272         $unmaskjs = '<script type="text/javascript">
2273 //<![CDATA[
2274 var is_ie = (navigator.userAgent.toLowerCase().indexOf("msie") != -1);
2276 document.getElementById("'.$id.'").setAttribute("autocomplete", "off");
2278 var unmaskdiv = document.getElementById("'.$id.'unmaskdiv");
2280 var unmaskchb = document.createElement("input");
2281 unmaskchb.setAttribute("type", "checkbox");
2282 unmaskchb.setAttribute("id", "'.$id.'unmask");
2283 unmaskchb.onchange = function() {unmaskPassword("'.$id.'");};
2284 unmaskdiv.appendChild(unmaskchb);
2286 var unmasklbl = document.createElement("label");
2287 unmasklbl.innerHTML = "'.addslashes_js($unmask).'";
2288 if (is_ie) {
2289   unmasklbl.setAttribute("htmlFor", "'.$id.'unmask");
2290 } else {
2291   unmasklbl.setAttribute("for", "'.$id.'unmask");
2293 unmaskdiv.appendChild(unmasklbl);
2295 if (is_ie) {
2296   // ugly hack to work around the famous onchange IE bug
2297   unmaskchb.onclick = function() {this.blur();};
2298   unmaskdiv.onclick = function() {this.blur();};
2300 //]]>
2301 </script>';
2302         return format_admin_setting($this, $this->visiblename,
2303         '<div class="form-password"><input type="password" size="'.$this->size.'" id="'.$id.'" name="'.$this->get_full_name().'" value="'.s($data).'" /><div class="unmask" id="'.$id.'unmaskdiv"></div>'.$unmaskjs.'</div>',
2304         $this->description, true, '', NULL, $query);
2305     }
2308 /**
2309  * Empty setting used to allow flags (advanced) on settings that can have no sensible default.
2310  * Note: Only advanced makes sense right now - locked does not.
2311  *
2312  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2313  */
2314 class admin_setting_configempty extends admin_setting_configtext {
2316     /**
2317      * @param string $name
2318      * @param string $visiblename
2319      * @param string $description
2320      */
2321     public function __construct($name, $visiblename, $description) {
2322         parent::__construct($name, $visiblename, $description, '', PARAM_RAW);
2323     }
2325     /**
2326      * Returns an XHTML string for the hidden field
2327      *
2328      * @param string $data
2329      * @param string $query
2330      * @return string XHTML string for the editor
2331      */
2332     public function output_html($data, $query='') {
2333         return format_admin_setting($this,
2334                                     $this->visiblename,
2335                                     '<div class="form-empty" >' .
2336                                     '<input type="hidden"' .
2337                                         ' id="'. $this->get_id() .'"' .
2338                                         ' name="'. $this->get_full_name() .'"' .
2339                                         ' value=""/></div>',
2340                                     $this->description,
2341                                     true,
2342                                     '',
2343                                     get_string('none'),
2344                                     $query);
2345     }
2349 /**
2350  * Path to directory
2351  *
2352  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2353  */
2354 class admin_setting_configfile extends admin_setting_configtext {
2355     /**
2356      * Constructor
2357      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2358      * @param string $visiblename localised
2359      * @param string $description long localised info
2360      * @param string $defaultdirectory default directory location
2361      */
2362     public function __construct($name, $visiblename, $description, $defaultdirectory) {
2363         parent::__construct($name, $visiblename, $description, $defaultdirectory, PARAM_RAW, 50);
2364     }
2366     /**
2367      * Returns XHTML for the field
2368      *
2369      * Returns XHTML for the field and also checks whether the file
2370      * specified in $data exists using file_exists()
2371      *
2372      * @param string $data File name and path to use in value attr
2373      * @param string $query
2374      * @return string XHTML field
2375      */
2376     public function output_html($data, $query='') {
2377         $default = $this->get_defaultsetting();
2379         if ($data) {
2380             if (file_exists($data)) {
2381                 $executable = '<span class="pathok">&#x2714;</span>';
2382             } else {
2383                 $executable = '<span class="patherror">&#x2718;</span>';
2384             }
2385         } else {
2386             $executable = '';
2387         }
2389         return format_admin_setting($this, $this->visiblename,
2390         '<div class="form-file defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" />'.$executable.'</div>',
2391         $this->description, true, '', $default, $query);
2392     }
2393     /**
2394      * checks if execpatch has been disabled in config.php
2395      */
2396     public function write_setting($data) {
2397         global $CFG;
2398         if (!empty($CFG->preventexecpath)) {
2399             return '';
2400         }
2401         return parent::write_setting($data);
2402     }
2406 /**
2407  * Path to executable file
2408  *
2409  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2410  */
2411 class admin_setting_configexecutable extends admin_setting_configfile {
2413     /**
2414      * Returns an XHTML field
2415      *
2416      * @param string $data This is the value for the field
2417      * @param string $query
2418      * @return string XHTML field
2419      */
2420     public function output_html($data, $query='') {
2421         global $CFG;
2422         $default = $this->get_defaultsetting();
2424         if ($data) {
2425             if (file_exists($data) and is_executable($data)) {
2426                 $executable = '<span class="pathok">&#x2714;</span>';
2427             } else {
2428                 $executable = '<span class="patherror">&#x2718;</span>';
2429             }
2430         } else {
2431             $executable = '';
2432         }
2433         if (!empty($CFG->preventexecpath)) {
2434             $this->visiblename .= '<div class="form-overridden">'.get_string('execpathnotallowed', 'admin').'</div>';
2435         }
2437         return format_admin_setting($this, $this->visiblename,
2438         '<div class="form-file defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" />'.$executable.'</div>',
2439         $this->description, true, '', $default, $query);
2440     }
2444 /**
2445  * Path to directory
2446  *
2447  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2448  */
2449 class admin_setting_configdirectory extends admin_setting_configfile {
2451     /**
2452      * Returns an XHTML field
2453      *
2454      * @param string $data This is the value for the field
2455      * @param string $query
2456      * @return string XHTML
2457      */
2458     public function output_html($data, $query='') {
2459         $default = $this->get_defaultsetting();
2461         if ($data) {
2462             if (file_exists($data) and is_dir($data)) {
2463                 $executable = '<span class="pathok">&#x2714;</span>';
2464             } else {
2465                 $executable = '<span class="patherror">&#x2718;</span>';
2466             }
2467         } else {
2468             $executable = '';
2469         }
2471         return format_admin_setting($this, $this->visiblename,
2472         '<div class="form-file defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" />'.$executable.'</div>',
2473         $this->description, true, '', $default, $query);
2474     }
2478 /**
2479  * Checkbox
2480  *
2481  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2482  */
2483 class admin_setting_configcheckbox extends admin_setting {
2484     /** @var string Value used when checked */
2485     public $yes;
2486     /** @var string Value used when not checked */
2487     public $no;
2489     /**
2490      * Constructor
2491      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2492      * @param string $visiblename localised
2493      * @param string $description long localised info
2494      * @param string $defaultsetting
2495      * @param string $yes value used when checked
2496      * @param string $no value used when not checked
2497      */
2498     public function __construct($name, $visiblename, $description, $defaultsetting, $yes='1', $no='0') {
2499         parent::__construct($name, $visiblename, $description, $defaultsetting);
2500         $this->yes = (string)$yes;
2501         $this->no  = (string)$no;
2502     }
2504     /**
2505      * Retrieves the current setting using the objects name
2506      *
2507      * @return string
2508      */
2509     public function get_setting() {
2510         return $this->config_read($this->name);
2511     }
2513     /**
2514      * Sets the value for the setting
2515      *
2516      * Sets the value for the setting to either the yes or no values
2517      * of the object by comparing $data to yes
2518      *
2519      * @param mixed $data Gets converted to str for comparison against yes value
2520      * @return string empty string or error
2521      */
2522     public function write_setting($data) {
2523         if ((string)$data === $this->yes) { // convert to strings before comparison
2524             $data = $this->yes;
2525         } else {
2526             $data = $this->no;
2527         }
2528         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2529     }
2531     /**
2532      * Returns an XHTML checkbox field
2533      *
2534      * @param string $data If $data matches yes then checkbox is checked
2535      * @param string $query
2536      * @return string XHTML field
2537      */
2538     public function output_html($data, $query='') {
2539         $default = $this->get_defaultsetting();
2541         if (!is_null($default)) {
2542             if ((string)$default === $this->yes) {
2543                 $defaultinfo = get_string('checkboxyes', 'admin');
2544             } else {
2545                 $defaultinfo = get_string('checkboxno', 'admin');
2546             }
2547         } else {
2548             $defaultinfo = NULL;
2549         }
2551         if ((string)$data === $this->yes) { // convert to strings before comparison
2552             $checked = 'checked="checked"';
2553         } else {
2554             $checked = '';
2555         }
2557         return format_admin_setting($this, $this->visiblename,
2558         '<div class="form-checkbox defaultsnext" ><input type="hidden" name="'.$this->get_full_name().'" value="'.s($this->no).'" /> '
2559             .'<input type="checkbox" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($this->yes).'" '.$checked.' /></div>',
2560         $this->description, true, '', $defaultinfo, $query);
2561     }
2565 /**
2566  * Multiple checkboxes, each represents different value, stored in csv format
2567  *
2568  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2569  */
2570 class admin_setting_configmulticheckbox extends admin_setting {
2571     /** @var array Array of choices value=>label */
2572     public $choices;
2574     /**
2575      * Constructor: uses parent::__construct
2576      *
2577      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2578      * @param string $visiblename localised
2579      * @param string $description long localised info
2580      * @param array $defaultsetting array of selected
2581      * @param array $choices array of $value=>$label for each checkbox
2582      */
2583     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2584         $this->choices = $choices;
2585         parent::__construct($name, $visiblename, $description, $defaultsetting);
2586     }
2588     /**
2589      * This public function may be used in ancestors for lazy loading of choices
2590      *
2591      * @todo Check if this function is still required content commented out only returns true
2592      * @return bool true if loaded, false if error
2593      */
2594     public function load_choices() {
2595         /*
2596         if (is_array($this->choices)) {
2597             return true;
2598         }
2599         .... load choices here
2600         */
2601         return true;
2602     }
2604     /**
2605      * Is setting related to query text - used when searching
2606      *
2607      * @param string $query
2608      * @return bool true on related, false on not or failure
2609      */
2610     public function is_related($query) {
2611         if (!$this->load_choices() or empty($this->choices)) {
2612             return false;
2613         }
2614         if (parent::is_related($query)) {
2615             return true;
2616         }
2618         foreach ($this->choices as $desc) {
2619             if (strpos(core_text::strtolower($desc), $query) !== false) {
2620                 return true;
2621             }
2622         }
2623         return false;
2624     }
2626     /**
2627      * Returns the current setting if it is set
2628      *
2629      * @return mixed null if null, else an array
2630      */
2631     public function get_setting() {
2632         $result = $this->config_read($this->name);
2634         if (is_null($result)) {
2635             return NULL;
2636         }
2637         if ($result === '') {
2638             return array();
2639         }
2640         $enabled = explode(',', $result);
2641         $setting = array();
2642         foreach ($enabled as $option) {
2643             $setting[$option] = 1;
2644         }
2645         return $setting;
2646     }
2648     /**
2649      * Saves the setting(s) provided in $data
2650      *
2651      * @param array $data An array of data, if not array returns empty str
2652      * @return mixed empty string on useless data or bool true=success, false=failed
2653      */
2654     public function write_setting($data) {
2655         if (!is_array($data)) {
2656             return ''; // ignore it
2657         }
2658         if (!$this->load_choices() or empty($this->choices)) {
2659             return '';
2660         }
2661         unset($data['xxxxx']);
2662         $result = array();
2663         foreach ($data as $key => $value) {
2664             if ($value and array_key_exists($key, $this->choices)) {
2665                 $result[] = $key;
2666             }
2667         }
2668         return $this->config_write($this->name, implode(',', $result)) ? '' : get_string('errorsetting', 'admin');
2669     }
2671     /**
2672      * Returns XHTML field(s) as required by choices
2673      *
2674      * Relies on data being an array should data ever be another valid vartype with
2675      * acceptable value this may cause a warning/error
2676      * if (!is_array($data)) would fix the problem
2677      *
2678      * @todo Add vartype handling to ensure $data is an array
2679      *
2680      * @param array $data An array of checked values
2681      * @param string $query
2682      * @return string XHTML field
2683      */
2684     public function output_html($data, $query='') {
2685         if (!$this->load_choices() or empty($this->choices)) {
2686             return '';
2687         }
2688         $default = $this->get_defaultsetting();
2689         if (is_null($default)) {
2690             $default = array();
2691         }
2692         if (is_null($data)) {
2693             $data = array();
2694         }
2695         $options = array();
2696         $defaults = array();
2697         foreach ($this->choices as $key=>$description) {
2698             if (!empty($data[$key])) {
2699                 $checked = 'checked="checked"';
2700             } else {
2701                 $checked = '';
2702             }
2703             if (!empty($default[$key])) {
2704                 $defaults[] = $description;
2705             }
2707             $options[] = '<input type="checkbox" id="'.$this->get_id().'_'.$key.'" name="'.$this->get_full_name().'['.$key.']" value="1" '.$checked.' />'
2708                 .'<label for="'.$this->get_id().'_'.$key.'">'.highlightfast($query, $description).'</label>';
2709         }
2711         if (is_null($default)) {
2712             $defaultinfo = NULL;
2713         } else if (!empty($defaults)) {
2714                 $defaultinfo = implode(', ', $defaults);
2715             } else {
2716                 $defaultinfo = get_string('none');
2717             }
2719         $return = '<div class="form-multicheckbox">';
2720         $return .= '<input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2721         if ($options) {
2722             $return .= '<ul>';
2723             foreach ($options as $option) {
2724                 $return .= '<li>'.$option.'</li>';
2725             }
2726             $return .= '</ul>';
2727         }
2728         $return .= '</div>';
2730         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
2732     }
2736 /**
2737  * Multiple checkboxes 2, value stored as string 00101011
2738  *
2739  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2740  */
2741 class admin_setting_configmulticheckbox2 extends admin_setting_configmulticheckbox {
2743     /**
2744      * Returns the setting if set
2745      *
2746      * @return mixed null if not set, else an array of set settings
2747      */
2748     public function get_setting() {
2749         $result = $this->config_read($this->name);
2750         if (is_null($result)) {
2751             return NULL;
2752         }
2753         if (!$this->load_choices()) {
2754             return NULL;
2755         }
2756         $result = str_pad($result, count($this->choices), '0');
2757         $result = preg_split('//', $result, -1, PREG_SPLIT_NO_EMPTY);
2758         $setting = array();
2759         foreach ($this->choices as $key=>$unused) {
2760             $value = array_shift($result);
2761             if ($value) {
2762                 $setting[$key] = 1;
2763             }
2764         }
2765         return $setting;
2766     }
2768     /**
2769      * Save setting(s) provided in $data param
2770      *
2771      * @param array $data An array of settings to save
2772      * @return mixed empty string for bad data or bool true=>success, false=>error
2773      */
2774     public function write_setting($data) {
2775         if (!is_array($data)) {
2776             return ''; // ignore it
2777         }
2778         if (!$this->load_choices() or empty($this->choices)) {
2779             return '';
2780         }
2781         $result = '';
2782         foreach ($this->choices as $key=>$unused) {
2783             if (!empty($data[$key])) {
2784                 $result .= '1';
2785             } else {
2786                 $result .= '0';
2787             }
2788         }
2789         return $this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin');
2790     }
2794 /**
2795  * Select one value from list
2796  *
2797  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2798  */
2799 class admin_setting_configselect extends admin_setting {
2800     /** @var array Array of choices value=>label */
2801     public $choices;
2803     /**
2804      * Constructor
2805      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2806      * @param string $visiblename localised
2807      * @param string $description long localised info
2808      * @param string|int $defaultsetting
2809      * @param array $choices array of $value=>$label for each selection
2810      */
2811     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2812         $this->choices = $choices;
2813         parent::__construct($name, $visiblename, $description, $defaultsetting);
2814     }
2816     /**
2817      * This function may be used in ancestors for lazy loading of choices
2818      *
2819      * Override this method if loading of choices is expensive, such
2820      * as when it requires multiple db requests.
2821      *
2822      * @return bool true if loaded, false if error
2823      */
2824     public function load_choices() {
2825         /*
2826         if (is_array($this->choices)) {
2827             return true;
2828         }
2829         .... load choices here
2830         */
2831         return true;
2832     }
2834     /**
2835      * Check if this is $query is related to a choice
2836      *
2837      * @param string $query
2838      * @return bool true if related, false if not
2839      */
2840     public function is_related($query) {
2841         if (parent::is_related($query)) {
2842             return true;
2843         }
2844         if (!$this->load_choices()) {
2845             return false;
2846         }
2847         foreach ($this->choices as $key=>$value) {
2848             if (strpos(core_text::strtolower($key), $query) !== false) {
2849                 return true;
2850             }
2851             if (strpos(core_text::strtolower($value), $query) !== false) {
2852                 return true;
2853             }
2854         }
2855         return false;
2856     }
2858     /**
2859      * Return the setting
2860      *
2861      * @return mixed returns config if successful else null
2862      */
2863     public function get_setting() {
2864         return $this->config_read($this->name);
2865     }
2867     /**
2868      * Save a setting
2869      *
2870      * @param string $data
2871      * @return string empty of error string
2872      */
2873     public function write_setting($data) {
2874         if (!$this->load_choices() or empty($this->choices)) {
2875             return '';
2876         }
2877         if (!array_key_exists($data, $this->choices)) {
2878             return ''; // ignore it
2879         }
2881         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2882     }
2884     /**
2885      * Returns XHTML select field
2886      *
2887      * Ensure the options are loaded, and generate the XHTML for the select
2888      * element and any warning message. Separating this out from output_html
2889      * makes it easier to subclass this class.
2890      *
2891      * @param string $data the option to show as selected.
2892      * @param string $current the currently selected option in the database, null if none.
2893      * @param string $default the default selected option.
2894      * @return array the HTML for the select element, and a warning message.
2895      */
2896     public function output_select_html($data, $current, $default, $extraname = '') {
2897         if (!$this->load_choices() or empty($this->choices)) {
2898             return array('', '');
2899         }
2901         $warning = '';
2902         if (is_null($current)) {
2903         // first run
2904         } else if (empty($current) and (array_key_exists('', $this->choices) or array_key_exists(0, $this->choices))) {
2905             // no warning
2906             } else if (!array_key_exists($current, $this->choices)) {
2907                     $warning = get_string('warningcurrentsetting', 'admin', s($current));
2908                     if (!is_null($default) and $data == $current) {
2909                         $data = $default; // use default instead of first value when showing the form
2910                     }
2911                 }
2913         $selecthtml = '<select id="'.$this->get_id().'" name="'.$this->get_full_name().$extraname.'">';
2914         foreach ($this->choices as $key => $value) {
2915         // the string cast is needed because key may be integer - 0 is equal to most strings!
2916             $selecthtml .= '<option value="'.$key.'"'.((string)$key==$data ? ' selected="selected"' : '').'>'.$value.'</option>';
2917         }
2918         $selecthtml .= '</select>';
2919         return array($selecthtml, $warning);
2920     }
2922     /**
2923      * Returns XHTML select field and wrapping div(s)
2924      *
2925      * @see output_select_html()
2926      *
2927      * @param string $data the option to show as selected
2928      * @param string $query
2929      * @return string XHTML field and wrapping div
2930      */
2931     public function output_html($data, $query='') {
2932         $default = $this->get_defaultsetting();
2933         $current = $this->get_setting();
2935         list($selecthtml, $warning) = $this->output_select_html($data, $current, $default);
2936         if (!$selecthtml) {
2937             return '';
2938         }
2940         if (!is_null($default) and array_key_exists($default, $this->choices)) {
2941             $defaultinfo = $this->choices[$default];
2942         } else {
2943             $defaultinfo = NULL;
2944         }
2946         $return = '<div class="form-select defaultsnext">' . $selecthtml . '</div>';
2948         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, $warning, $defaultinfo, $query);
2949     }
2953 /**
2954  * Select multiple items from list
2955  *
2956  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2957  */
2958 class admin_setting_configmultiselect extends admin_setting_configselect {
2959     /**
2960      * Constructor
2961      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2962      * @param string $visiblename localised
2963      * @param string $description long localised info
2964      * @param array $defaultsetting array of selected items
2965      * @param array $choices array of $value=>$label for each list item
2966      */
2967     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2968         parent::__construct($name, $visiblename, $description, $defaultsetting, $choices);
2969     }
2971     /**
2972      * Returns the select setting(s)
2973      *
2974      * @return mixed null or array. Null if no settings else array of setting(s)
2975      */
2976     public function get_setting() {
2977         $result = $this->config_read($this->name);
2978         if (is_null($result)) {
2979             return NULL;
2980         }
2981         if ($result === '') {
2982             return array();
2983         }
2984         return explode(',', $result);
2985     }
2987     /**
2988      * Saves setting(s) provided through $data
2989      *
2990      * Potential bug in the works should anyone call with this function
2991      * using a vartype that is not an array
2992      *
2993      * @param array $data
2994      */
2995     public function write_setting($data) {
2996         if (!is_array($data)) {
2997             return ''; //ignore it
2998         }
2999         if (!$this->load_choices() or empty($this->choices)) {
3000             return '';
3001         }
3003         unset($data['xxxxx']);
3005         $save = array();
3006         foreach ($data as $value) {
3007             if (!array_key_exists($value, $this->choices)) {
3008                 continue; // ignore it
3009             }
3010             $save[] = $value;
3011         }
3013         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
3014     }
3016     /**
3017      * Is setting related to query text - used when searching
3018      *
3019      * @param string $query
3020      * @return bool true if related, false if not
3021      */
3022     public function is_related($query) {
3023         if (!$this->load_choices() or empty($this->choices)) {
3024             return false;
3025         }
3026         if (parent::is_related($query)) {
3027             return true;
3028         }
3030         foreach ($this->choices as $desc) {
3031             if (strpos(core_text::strtolower($desc), $query) !== false) {
3032                 return true;
3033             }
3034         }
3035         return false;
3036     }
3038     /**
3039      * Returns XHTML multi-select field
3040      *
3041      * @todo Add vartype handling to ensure $data is an array
3042      * @param array $data Array of values to select by default
3043      * @param string $query
3044      * @return string XHTML multi-select field
3045      */
3046     public function output_html($data, $query='') {
3047         if (!$this->load_choices() or empty($this->choices)) {
3048             return '';
3049         }
3050         $choices = $this->choices;
3051         $default = $this->get_defaultsetting();
3052         if (is_null($default)) {
3053             $default = array();
3054         }
3055         if (is_null($data)) {
3056             $data = array();
3057         }
3059         $defaults = array();
3060         $size = min(10, count($this->choices));
3061         $return = '<div class="form-select"><input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
3062         $return .= '<select id="'.$this->get_id().'" name="'.$this->get_full_name().'[]" size="'.$size.'" multiple="multiple">';
3063         foreach ($this->choices as $key => $description) {
3064             if (in_array($key, $data)) {
3065                 $selected = 'selected="selected"';
3066             } else {
3067                 $selected = '';
3068             }
3069             if (in_array($key, $default)) {
3070                 $defaults[] = $description;
3071             }
3073             $return .= '<option value="'.s($key).'" '.$selected.'>'.$description.'</option>';
3074         }
3076         if (is_null($default)) {
3077             $defaultinfo = NULL;
3078         } if (!empty($defaults)) {
3079             $defaultinfo = implode(', ', $defaults);
3080         } else {
3081             $defaultinfo = get_string('none');
3082         }
3084         $return .= '</select></div>';
3085         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, '', $defaultinfo, $query);
3086     }
3089 /**
3090  * Time selector
3091  *
3092  * This is a liiitle bit messy. we're using two selects, but we're returning
3093  * them as an array named after $name (so we only use $name2 internally for the setting)
3094  *
3095  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3096  */
3097 class admin_setting_configtime extends admin_setting {
3098     /** @var string Used for setting second select (minutes) */
3099     public $name2;
3101     /**
3102      * Constructor
3103      * @param string $hoursname setting for hours
3104      * @param string $minutesname setting for hours
3105      * @param string $visiblename localised
3106      * @param string $description long localised info
3107      * @param array $defaultsetting array representing default time 'h'=>hours, 'm'=>minutes
3108      */
3109     public function __construct($hoursname, $minutesname, $visiblename, $description, $defaultsetting) {
3110         $this->name2 = $minutesname;
3111         parent::__construct($hoursname, $visiblename, $description, $defaultsetting);
3112     }
3114     /**
3115      * Get the selected time
3116      *
3117      * @return mixed An array containing 'h'=>xx, 'm'=>xx, or null if not set
3118      */
3119     public function get_setting() {
3120         $result1 = $this->config_read($this->name);
3121         $result2 = $this->config_read($this->name2);
3122         if (is_null($result1) or is_null($result2)) {
3123             return NULL;
3124         }
3126         return array('h' => $result1, 'm' => $result2);
3127     }
3129     /**
3130      * Store the time (hours and minutes)
3131      *
3132      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3133      * @return bool true if success, false if not
3134      */
3135     public function write_setting($data) {
3136         if (!is_array($data)) {
3137             return '';
3138         }
3140         $result = $this->config_write($this->name, (int)$data['h']) && $this->config_write($this->name2, (int)$data['m']);
3141         return ($result ? '' : get_string('errorsetting', 'admin'));
3142     }
3144     /**
3145      * Returns XHTML time select fields
3146      *
3147      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3148      * @param string $query
3149      * @return string XHTML time select fields and wrapping div(s)
3150      */
3151     public function output_html($data, $query='') {
3152         $default = $this->get_defaultsetting();
3154         if (is_array($default)) {
3155             $defaultinfo = $default['h'].':'.$default['m'];
3156         } else {
3157             $defaultinfo = NULL;
3158         }
3160         $return = '<div class="form-time defaultsnext">'.
3161             '<select id="'.$this->get_id().'h" name="'.$this->get_full_name().'[h]">';
3162         for ($i = 0; $i < 24; $i++) {
3163             $return .= '<option value="'.$i.'"'.($i == $data['h'] ? ' selected="selected"' : '').'>'.$i.'</option>';
3164         }
3165         $return .= '</select>:<select id="'.$this->get_id().'m" name="'.$this->get_full_name().'[m]">';
3166         for ($i = 0; $i < 60; $i += 5) {
3167             $return .= '<option value="'.$i.'"'.($i == $data['m'] ? ' selected="selected"' : '').'>'.$i.'</option>';
3168         }
3169         $return .= '</select></div>';
3170         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
3171     }
3176 /**
3177  * Seconds duration setting.
3178  *
3179  * @copyright 2012 Petr Skoda (http://skodak.org)
3180  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3181  */
3182 class admin_setting_configduration extends admin_setting {
3184     /** @var int default duration unit */
3185     protected $defaultunit;
3187     /**
3188      * Constructor
3189      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
3190      *                     or 'myplugin/mysetting' for ones in config_plugins.
3191      * @param string $visiblename localised name
3192      * @param string $description localised long description
3193      * @param mixed $defaultsetting string or array depending on implementation
3194      * @param int $defaultunit - day, week, etc. (in seconds)
3195      */
3196     public function __construct($name, $visiblename, $description, $defaultsetting, $defaultunit = 86400) {
3197         if (is_number($defaultsetting)) {
3198             $defaultsetting = self::parse_seconds($defaultsetting);
3199         }
3200         $units = self::get_units();
3201         if (isset($units[$defaultunit])) {
3202             $this->defaultunit = $defaultunit;
3203         } else {
3204             $this->defaultunit = 86400;
3205         }
3206         parent::__construct($name, $visiblename, $description, $defaultsetting);
3207     }
3209     /**
3210      * Returns selectable units.
3211      * @static
3212      * @return array
3213      */
3214     protected static function get_units() {
3215         return array(
3216             604800 => get_string('weeks'),
3217             86400 => get_string('days'),
3218             3600 => get_string('hours'),
3219             60 => get_string('minutes'),
3220             1 => get_string('seconds'),
3221         );
3222     }
3224     /**
3225      * Converts seconds to some more user friendly string.
3226      * @static
3227      * @param int $seconds
3228      * @return string
3229      */
3230     protected static function get_duration_text($seconds) {
3231         if (empty($seconds)) {
3232             return get_string('none');
3233         }
3234         $data = self::parse_seconds($seconds);
3235         switch ($data['u']) {
3236             case (60*60*24*7):
3237                 return get_string('numweeks', '', $data['v']);
3238             case (60*60*24):
3239                 return get_string('numdays', '', $data['v']);
3240             case (60*60):
3241                 return get_string('numhours', '', $data['v']);
3242             case (60):
3243                 return get_string('numminutes', '', $data['v']);
3244             default:
3245                 return get_string('numseconds', '', $data['v']*$data['u']);
3246         }
3247     }
3249     /**
3250      * Finds suitable units for given duration.
3251      * @static
3252      * @param int $seconds
3253      * @return array
3254      */
3255     protected static function parse_seconds($seconds) {
3256         foreach (self::get_units() as $unit => $unused) {
3257             if ($seconds % $unit === 0) {
3258                 return array('v'=>(int)($seconds/$unit), 'u'=>$unit);
3259             }
3260         }
3261         return array('v'=>(int)$seconds, 'u'=>1);
3262     }
3264     /**
3265      * Get the selected duration as array.
3266      *
3267      * @return mixed An array containing 'v'=>xx, 'u'=>xx, or null if not set
3268      */
3269     public function get_setting() {
3270         $seconds = $this->config_read($this->name);
3271         if (is_null($seconds)) {
3272             return null;
3273         }
3275         return self::parse_seconds($seconds);
3276     }
3278     /**
3279      * Store the duration as seconds.
3280      *
3281      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3282      * @return bool true if success, false if not
3283      */
3284     public function write_setting($data) {
3285         if (!is_array($data)) {
3286             return '';
3287         }
3289         $seconds = (int)($data['v']*$data['u']);
3290         if ($seconds < 0) {
3291             return get_string('errorsetting', 'admin');
3292         }
3294         $result = $this->config_write($this->name, $seconds);
3295         return ($result ? '' : get_string('errorsetting', 'admin'));
3296     }
3298     /**
3299      * Returns duration text+select fields.
3300      *
3301      * @param array $data Must be form 'v'=>xx, 'u'=>xx
3302      * @param string $query
3303      * @return string duration text+select fields and wrapping div(s)
3304      */
3305     public function output_html($data, $query='') {
3306         $default = $this->get_defaultsetting();
3308         if (is_number($default)) {
3309             $defaultinfo = self::get_duration_text($default);
3310         } else if (is_array($default)) {
3311             $defaultinfo = self::get_duration_text($default['v']*$default['u']);
3312         } else {
3313             $defaultinfo = null;
3314         }
3316         $units = self::get_units();
3318         $return = '<div class="form-duration defaultsnext">';
3319         $return .= '<input type="text" size="5" id="'.$this->get_id().'v" name="'.$this->get_full_name().'[v]" value="'.s($data['v']).'" />';
3320         $return .= '<select id="'.$this->get_id().'u" name="'.$this->get_full_name().'[u]">';
3321         foreach ($units as $val => $text) {
3322             $selected = '';
3323             if ($data['v'] == 0) {
3324                 if ($val == $this->defaultunit) {
3325                     $selected = ' selected="selected"';
3326                 }
3327             } else if ($val == $data['u']) {
3328                 $selected = ' selected="selected"';
3329             }
3330             $return .= '<option value="'.$val.'"'.$selected.'>'.$text.'</option>';
3331         }
3332         $return .= '</select></div>';
3333         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
3334     }
3338 /**
3339  * Used to validate a textarea used for ip addresses
3340  *
3341  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3342  */
3343 class admin_setting_configiplist extends admin_setting_configtextarea {
3345     /**
3346      * Validate the contents of the textarea as IP addresses
3347      *
3348      * Used to validate a new line separated list of IP addresses collected from
3349      * a textarea control
3350      *
3351      * @param string $data A list of IP Addresses separated by new lines
3352      * @return mixed bool true for success or string:error on failure
3353      */
3354     public function validate($data) {
3355         if(!empty($data)) {
3356             $ips = explode("\n", $data);
3357         } else {
3358             return true;
3359         }
3360         $result = true;
3361         foreach($ips as $ip) {
3362             $ip = trim($ip);
3363             if (preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}$#', $ip, $match) ||
3364                 preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}(\/\d{1,2})$#', $ip, $match) ||
3365                 preg_match('#^(\d{1,3})(\.\d{1,3}){3}(-\d{1,3})$#', $ip, $match)) {
3366                 $result = true;
3367             } else {
3368                 $result = false;
3369                 break;
3370             }
3371         }
3372         if($result) {
3373             return true;
3374         } else {
3375             return get_string('validateerror', 'admin');
3376         }
3377     }
3381 /**
3382  * An admin setting for selecting one or more users who have a capability
3383  * in the system context
3384  *
3385  * An admin setting for selecting one or more users, who have a particular capability
3386  * in the system context. Warning, make sure the list will never be too long. There is
3387  * no paging or searching of this list.
3388  *
3389  * To correctly get a list of users from this config setting, you need to call the
3390  * get_users_from_config($CFG->mysetting, $capability); function in moodlelib.php.
3391  *
3392  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3393  */
3394 class admin_setting_users_with_capability extends admin_setting_configmultiselect {
3395     /** @var string The capabilities name */
3396     protected $capability;
3397     /** @var int include admin users too */
3398     protected $includeadmins;
3400     /**
3401      * Constructor.
3402      *
3403      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
3404      * @param string $visiblename localised name
3405      * @param string $description localised long description
3406      * @param array $defaultsetting array of usernames
3407      * @param string $capability string capability name.
3408      * @param bool $includeadmins include administrators
3409      */
3410     function __construct($name, $visiblename, $description, $defaultsetting, $capability, $includeadmins = true) {
3411         $this->capability    = $capability;
3412         $this->includeadmins = $includeadmins;
3413         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
3414     }
3416     /**
3417      * Load all of the uses who have the capability into choice array
3418      *
3419      * @return bool Always returns true
3420      */
3421     function load_choices() {
3422         if (is_array($this->choices)) {
3423             return true;
3424         }
3425         list($sort, $sortparams) = users_order_by_sql('u');
3426         if (!empty($sortparams)) {
3427             throw new coding_exception('users_order_by_sql returned some query parameters. ' .
3428                     'This is unexpected, and a problem because there is no way to pass these ' .
3429                     'parameters to get_users_by_capability. See MDL-34657.');
3430         }
3431         $users = get_users_by_capability(context_system::instance(),
3432                 $this->capability, 'u.id,u.username,u.firstname,u.lastname', $sort);
3433         $this->choices = array(
3434             '$@NONE@$' => get_string('nobody'),
3435             '$@ALL@$' => get_string('everyonewhocan', 'admin', get_capability_string($this->capability)),
3436         );
3437         if ($this->includeadmins) {
3438             $admins = get_admins();
3439             foreach ($admins as $user) {
3440                 $this->choices[$user->id] = fullname($user);
3441             }
3442         }
3443         if (is_array($users)) {
3444             foreach ($users as $user) {
3445                 $this->choices[$user->id] = fullname($user);
3446             }
3447         }
3448         return true;
3449     }
3451     /**
3452      * Returns the default setting for class
3453      *
3454      * @return mixed Array, or string. Empty string if no default
3455      */
3456     public function get_defaultsetting() {
3457         $this->load_choices();
3458         $defaultsetting = parent::get_defaultsetting();
3459         if (empty($defaultsetting)) {
3460             return array('$@NONE@$');
3461         } else if (array_key_exists($defaultsetting, $this->choices)) {
3462                 return $defaultsetting;
3463             } else {
3464                 return '';
3465             }
3466     }
3468     /**
3469      * Returns the current setting
3470      *
3471      * @return mixed array or string
3472      */
3473     public function get_setting() {
3474         $result = parent::get_setting();
3475         if ($result === null) {
3476             // this is necessary for settings upgrade
3477             return null;
3478         }
3479         if (empty($result)) {
3480             $result = array('$@NONE@$');
3481         }
3482         return $result;
3483     }
3485     /**
3486      * Save the chosen setting provided as $data
3487      *
3488      * @param array $data
3489      * @return mixed string or array
3490      */
3491     public function write_setting($data) {
3492     // If all is selected, remove any explicit options.
3493         if (in_array('$@ALL@$', $data)) {
3494             $data = array('$@ALL@$');
3495         }
3496         // None never needs to be written to the DB.
3497         if (in_array('$@NONE@$', $data)) {
3498             unset($data[array_search('$@NONE@$', $data)]);
3499         }
3500         return parent::write_setting($data);
3501     }
3505 /**
3506  * Special checkbox for calendar - resets SESSION vars.
3507  *
3508  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3509  */
3510 class admin_setting_special_adminseesall extends admin_setting_configcheckbox {
3511     /**
3512      * Calls the parent::__construct with default values
3513      *
3514      * name =>  calendar_adminseesall
3515      * visiblename => get_string('adminseesall', 'admin')
3516      * description => get_string('helpadminseesall', 'admin')
3517      * defaultsetting => 0
3518      */
3519     public function __construct() {
3520         parent::__construct('calendar_adminseesall', get_string('adminseesall', 'admin'),
3521             get_string('helpadminseesall', 'admin'), '0');
3522     }
3524     /**
3525      * Stores the setting passed in $data
3526      *
3527      * @param mixed gets converted to string for comparison
3528      * @return string empty string or error message
3529      */
3530     public function write_setting($data) {
3531         global $SESSION;
3532         return parent::write_setting($data);
3533     }
3536 /**
3537  * Special select for settings that are altered in setup.php and can not be altered on the fly
3538  *
3539  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3540  */
3541 class admin_setting_special_selectsetup extends admin_setting_configselect {
3542     /**
3543      * Reads the setting directly from the database
3544      *
3545      * @return mixed
3546      */
3547     public function get_setting() {
3548     // read directly from db!
3549         return get_config(NULL, $this->name);
3550     }
3552     /**
3553      * Save the setting passed in $data
3554      *
3555      * @param string $data The setting to save
3556      * @return string empty or error message
3557      */
3558     public function write_setting($data) {
3559         global $CFG;
3560         // do not change active CFG setting!
3561         $current = $CFG->{$this->name};
3562         $result = parent::write_setting($data);
3563         $CFG->{$this->name} = $current;
3564         return $result;
3565     }
3569 /**
3570  * Special select for frontpage - stores data in course table
3571  *
3572  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3573  */
3574 class admin_setting_sitesetselect extends admin_setting_configselect {
3575     /**
3576      * Returns the site name for the selected site
3577      *
3578      * @see get_site()
3579      * @return string The site name of the selected site
3580      */
3581     public function get_setting() {
3582         $site = course_get_format(get_site())->get_course();
3583         return $site->{$this->name};
3584     }
3586     /**
3587      * Updates the database and save the setting
3588      *
3589      * @param string data
3590      * @return string empty or error message
3591      */
3592     public function write_setting($data) {
3593         global $DB, $SITE, $COURSE;
3594         if (!in_array($data, array_keys($this->choices))) {
3595             return get_string('errorsetting', 'admin');
3596         }
3597         $record = new stdClass();
3598         $record->id           = SITEID;
3599         $temp                 = $this->name;
3600         $record->$temp        = $data;
3601         $record->timemodified = time();
3603         course_get_format($SITE)->update_course_format_options($record);
3604         $DB->update_record('course', $record);
3606         // Reset caches.
3607         $SITE = $DB->get_record('course', array('id'=>$SITE->id), '*', MUST_EXIST);
3608         if ($SITE->id == $COURSE->id) {
3609             $COURSE = $SITE;
3610         }
3611         format_base::reset_course_cache($SITE->id);
3613         return '';
3615     }
3619 /**
3620  * Select for blog's bloglevel setting: if set to 0, will set blog_menu
3621  * block to hidden.
3622  *
3623  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3624  */
3625 class admin_setting_bloglevel extends admin_setting_configselect {
3626     /**
3627      * Updates the database and save the setting
3628      *
3629      * @param string data
3630      * @return string empty or error message
3631      */
3632     public function write_setting($data) {
3633         global $DB, $CFG;
3634         if ($data == 0) {
3635             $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 1");
3636             foreach ($blogblocks as $block) {
3637                 $DB->set_field('block', 'visible', 0, array('id' => $block->id));
3638             }
3639         } else {
3640             // reenable all blocks only when switching from disabled blogs
3641             if (isset($CFG->bloglevel) and $CFG->bloglevel == 0) {
3642                 $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 0");
3643                 foreach ($blogblocks as $block) {
3644                     $DB->set_field('block', 'visible', 1, array('id' => $block->id));
3645                 }
3646             }
3647         }
3648         return parent::write_setting($data);
3649     }
3653 /**
3654  * Special select - lists on the frontpage - hacky
3655  *
3656  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later