MDL-29031 drop unused block tables
[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  * @param string $type The plugin type, eg. 'mod', 'qtype', 'workshopgrading' etc.
119  * @param string $name The plugin name, eg. 'forum', 'multichoice', 'accumulative' etc.
120  * @uses global $OUTPUT to produce notices and other messages
121  * @return void
122  */
123 function uninstall_plugin($type, $name) {
124     global $CFG, $DB, $OUTPUT;
126     // recursively uninstall all module subplugins first
127     if ($type === 'mod') {
128         if (file_exists("$CFG->dirroot/mod/$name/db/subplugins.php")) {
129             $subplugins = array();
130             include("$CFG->dirroot/mod/$name/db/subplugins.php");
131             foreach ($subplugins as $subplugintype=>$dir) {
132                 $instances = get_plugin_list($subplugintype);
133                 foreach ($instances as $subpluginname => $notusedpluginpath) {
134                     uninstall_plugin($subplugintype, $subpluginname);
135                 }
136             }
137         }
139     }
141     $component = $type . '_' . $name;  // eg. 'qtype_multichoice' or 'workshopgrading_accumulative' or 'mod_forum'
143     if ($type === 'mod') {
144         $pluginname = $name;  // eg. 'forum'
145         if (get_string_manager()->string_exists('modulename', $component)) {
146             $strpluginname = get_string('modulename', $component);
147         } else {
148             $strpluginname = $component;
149         }
151     } else {
152         $pluginname = $component;
153         if (get_string_manager()->string_exists('pluginname', $component)) {
154             $strpluginname = get_string('pluginname', $component);
155         } else {
156             $strpluginname = $component;
157         }
158     }
160     echo $OUTPUT->heading($pluginname);
162     $plugindirectory = get_plugin_directory($type, $name);
163     $uninstalllib = $plugindirectory . '/db/uninstall.php';
164     if (file_exists($uninstalllib)) {
165         require_once($uninstalllib);
166         $uninstallfunction = 'xmldb_' . $pluginname . '_uninstall';    // eg. 'xmldb_workshop_uninstall()'
167         if (function_exists($uninstallfunction)) {
168             if (!$uninstallfunction()) {
169                 echo $OUTPUT->notification('Encountered a problem running uninstall function for '. $pluginname);
170             }
171         }
172     }
174     if ($type === 'mod') {
175         // perform cleanup tasks specific for activity modules
177         if (!$module = $DB->get_record('modules', array('name' => $name))) {
178             print_error('moduledoesnotexist', 'error');
179         }
181         // delete all the relevant instances from all course sections
182         if ($coursemods = $DB->get_records('course_modules', array('module' => $module->id))) {
183             foreach ($coursemods as $coursemod) {
184                 if (!delete_mod_from_section($coursemod->id, $coursemod->section)) {
185                     echo $OUTPUT->notification("Could not delete the $strpluginname with id = $coursemod->id from section $coursemod->section");
186                 }
187             }
188         }
190         // clear course.modinfo for courses that used this module
191         $sql = "UPDATE {course}
192                    SET modinfo=''
193                  WHERE id IN (SELECT DISTINCT course
194                                 FROM {course_modules}
195                                WHERE module=?)";
196         $DB->execute($sql, array($module->id));
198         // delete all the course module records
199         $DB->delete_records('course_modules', array('module' => $module->id));
201         // delete module contexts
202         if ($coursemods) {
203             foreach ($coursemods as $coursemod) {
204                 if (!delete_context(CONTEXT_MODULE, $coursemod->id)) {
205                     echo $OUTPUT->notification("Could not delete the context for $strpluginname with id = $coursemod->id");
206                 }
207             }
208         }
210         // delete the module entry itself
211         $DB->delete_records('modules', array('name' => $module->name));
213         // cleanup the gradebook
214         require_once($CFG->libdir.'/gradelib.php');
215         grade_uninstalled_module($module->name);
217         // Perform any custom uninstall tasks
218         if (file_exists($CFG->dirroot . '/mod/' . $module->name . '/lib.php')) {
219             require_once($CFG->dirroot . '/mod/' . $module->name . '/lib.php');
220             $uninstallfunction = $module->name . '_uninstall';
221             if (function_exists($uninstallfunction)) {
222                 debugging("{$uninstallfunction}() has been deprecated. Use the plugin's db/uninstall.php instead", DEBUG_DEVELOPER);
223                 if (!$uninstallfunction()) {
224                     echo $OUTPUT->notification('Encountered a problem running uninstall function for '. $module->name.'!');
225                 }
226             }
227         }
229     } else if ($type === 'enrol') {
230         // NOTE: this is a bit brute force way - it will not trigger events and hooks properly
231         // nuke all role assignments
232         role_unassign_all(array('component'=>$component));
233         // purge participants
234         $DB->delete_records_select('user_enrolments', "enrolid IN (SELECT id FROM {enrol} WHERE enrol = ?)", array($name));
235         // purge enrol instances
236         $DB->delete_records('enrol', array('enrol'=>$name));
237         // tweak enrol settings
238         if (!empty($CFG->enrol_plugins_enabled)) {
239             $enabledenrols = explode(',', $CFG->enrol_plugins_enabled);
240             $enabledenrols = array_unique($enabledenrols);
241             $enabledenrols = array_flip($enabledenrols);
242             unset($enabledenrols[$name]);
243             $enabledenrols = array_flip($enabledenrols);
244             if (is_array($enabledenrols)) {
245                 set_config('enrol_plugins_enabled', implode(',', $enabledenrols));
246             }
247         }
248     }
250     // perform clean-up task common for all the plugin/subplugin types
252     // delete calendar events
253     $DB->delete_records('event', array('modulename' => $pluginname));
255     // delete all the logs
256     $DB->delete_records('log', array('module' => $pluginname));
258     // delete log_display information
259     $DB->delete_records('log_display', array('component' => $component));
261     // delete the module configuration records
262     unset_all_config_for_plugin($pluginname);
264     // delete message provider
265     message_provider_uninstall($component);
267     // delete message processor
268     if ($type === 'message') {
269         message_processor_uninstall($name);
270     }
272     // delete the plugin tables
273     $xmldbfilepath = $plugindirectory . '/db/install.xml';
274     drop_plugin_tables($pluginname, $xmldbfilepath, false);
276     // delete the capabilities that were defined by this module
277     capabilities_cleanup($component);
279     // remove event handlers and dequeue pending events
280     events_uninstall($component);
282     echo $OUTPUT->notification(get_string('success'), 'notifysuccess');
285 /**
286  * Returns the version of installed component
287  *
288  * @param string $component component name
289  * @param string $source either 'disk' or 'installed' - where to get the version information from
290  * @return string|bool version number or false if the component is not found
291  */
292 function get_component_version($component, $source='installed') {
293     global $CFG, $DB;
295     list($type, $name) = normalize_component($component);
297     // moodle core or a core subsystem
298     if ($type === 'core') {
299         if ($source === 'installed') {
300             if (empty($CFG->version)) {
301                 return false;
302             } else {
303                 return $CFG->version;
304             }
305         } else {
306             if (!is_readable($CFG->dirroot.'/version.php')) {
307                 return false;
308             } else {
309                 $version = null; //initialize variable for IDEs
310                 include($CFG->dirroot.'/version.php');
311                 return $version;
312             }
313         }
314     }
316     // activity module
317     if ($type === 'mod') {
318         if ($source === 'installed') {
319             return $DB->get_field('modules', 'version', array('name'=>$name));
320         } else {
321             $mods = get_plugin_list('mod');
322             if (empty($mods[$name]) or !is_readable($mods[$name].'/version.php')) {
323                 return false;
324             } else {
325                 $module = new stdclass();
326                 include($mods[$name].'/version.php');
327                 return $module->version;
328             }
329         }
330     }
332     // block
333     if ($type === 'block') {
334         if ($source === 'installed') {
335             return $DB->get_field('block', 'version', array('name'=>$name));
336         } else {
337             $blocks = get_plugin_list('block');
338             if (empty($blocks[$name]) or !is_readable($blocks[$name].'/version.php')) {
339                 return false;
340             } else {
341                 $plugin = new stdclass();
342                 include($blocks[$name].'/version.php');
343                 return $plugin->version;
344             }
345         }
346     }
348     // all other plugin types
349     if ($source === 'installed') {
350         return get_config($type.'_'.$name, 'version');
351     } else {
352         $plugins = get_plugin_list($type);
353         if (empty($plugins[$name])) {
354             return false;
355         } else {
356             $plugin = new stdclass();
357             include($plugins[$name].'/version.php');
358             return $plugin->version;
359         }
360     }
363 /**
364  * Delete all plugin tables
365  *
366  * @param string $name Name of plugin, used as table prefix
367  * @param string $file Path to install.xml file
368  * @param bool $feedback defaults to true
369  * @return bool Always returns true
370  */
371 function drop_plugin_tables($name, $file, $feedback=true) {
372     global $CFG, $DB;
374     // first try normal delete
375     if (file_exists($file) and $DB->get_manager()->delete_tables_from_xmldb_file($file)) {
376         return true;
377     }
379     // then try to find all tables that start with name and are not in any xml file
380     $used_tables = get_used_table_names();
382     $tables = $DB->get_tables();
384     /// Iterate over, fixing id fields as necessary
385     foreach ($tables as $table) {
386         if (in_array($table, $used_tables)) {
387             continue;
388         }
390         if (strpos($table, $name) !== 0) {
391             continue;
392         }
394         // found orphan table --> delete it
395         if ($DB->get_manager()->table_exists($table)) {
396             $xmldb_table = new xmldb_table($table);
397             $DB->get_manager()->drop_table($xmldb_table);
398         }
399     }
401     return true;
404 /**
405  * Returns names of all known tables == tables that moodle knows about.
406  *
407  * @return array Array of lowercase table names
408  */
409 function get_used_table_names() {
410     $table_names = array();
411     $dbdirs = get_db_directories();
413     foreach ($dbdirs as $dbdir) {
414         $file = $dbdir.'/install.xml';
416         $xmldb_file = new xmldb_file($file);
418         if (!$xmldb_file->fileExists()) {
419             continue;
420         }
422         $loaded    = $xmldb_file->loadXMLStructure();
423         $structure = $xmldb_file->getStructure();
425         if ($loaded and $tables = $structure->getTables()) {
426             foreach($tables as $table) {
427                 $table_names[] = strtolower($table->name);
428             }
429         }
430     }
432     return $table_names;
435 /**
436  * Returns list of all directories where we expect install.xml files
437  * @return array Array of paths
438  */
439 function get_db_directories() {
440     global $CFG;
442     $dbdirs = array();
444     /// First, the main one (lib/db)
445     $dbdirs[] = $CFG->libdir.'/db';
447     /// Then, all the ones defined by get_plugin_types()
448     $plugintypes = get_plugin_types();
449     foreach ($plugintypes as $plugintype => $pluginbasedir) {
450         if ($plugins = get_plugin_list($plugintype)) {
451             foreach ($plugins as $plugin => $plugindir) {
452                 $dbdirs[] = $plugindir.'/db';
453             }
454         }
455     }
457     return $dbdirs;
460 /**
461  * Try to obtain or release the cron lock.
462  * @param string  $name  name of lock
463  * @param int  $until timestamp when this lock considered stale, null means remove lock unconditionally
464  * @param bool $ignorecurrent ignore current lock state, usually extend previous lock, defaults to false
465  * @return bool true if lock obtained
466  */
467 function set_cron_lock($name, $until, $ignorecurrent=false) {
468     global $DB;
469     if (empty($name)) {
470         debugging("Tried to get a cron lock for a null fieldname");
471         return false;
472     }
474     // remove lock by force == remove from config table
475     if (is_null($until)) {
476         set_config($name, null);
477         return true;
478     }
480     if (!$ignorecurrent) {
481         // read value from db - other processes might have changed it
482         $value = $DB->get_field('config', 'value', array('name'=>$name));
484         if ($value and $value > time()) {
485             //lock active
486             return false;
487         }
488     }
490     set_config($name, $until);
491     return true;
494 /**
495  * Test if and critical warnings are present
496  * @return bool
497  */
498 function admin_critical_warnings_present() {
499     global $SESSION;
501     if (!has_capability('moodle/site:config', get_context_instance(CONTEXT_SYSTEM))) {
502         return 0;
503     }
505     if (!isset($SESSION->admin_critical_warning)) {
506         $SESSION->admin_critical_warning = 0;
507         if (is_dataroot_insecure(true) === INSECURE_DATAROOT_ERROR) {
508             $SESSION->admin_critical_warning = 1;
509         }
510     }
512     return $SESSION->admin_critical_warning;
515 /**
516  * Detects if float supports at least 10 decimal digits
517  *
518  * Detects if float supports at least 10 decimal digits
519  * and also if float-->string conversion works as expected.
520  *
521  * @return bool true if problem found
522  */
523 function is_float_problem() {
524     $num1 = 2009010200.01;
525     $num2 = 2009010200.02;
527     return ((string)$num1 === (string)$num2 or $num1 === $num2 or $num2 <= (string)$num1);
530 /**
531  * Try to verify that dataroot is not accessible from web.
532  *
533  * Try to verify that dataroot is not accessible from web.
534  * It is not 100% correct but might help to reduce number of vulnerable sites.
535  * Protection from httpd.conf and .htaccess is not detected properly.
536  *
537  * @uses INSECURE_DATAROOT_WARNING
538  * @uses INSECURE_DATAROOT_ERROR
539  * @param bool $fetchtest try to test public access by fetching file, default false
540  * @return mixed empty means secure, INSECURE_DATAROOT_ERROR found a critical problem, INSECURE_DATAROOT_WARNING might be problematic
541  */
542 function is_dataroot_insecure($fetchtest=false) {
543     global $CFG;
545     $siteroot = str_replace('\\', '/', strrev($CFG->dirroot.'/')); // win32 backslash workaround
547     $rp = preg_replace('|https?://[^/]+|i', '', $CFG->wwwroot, 1);
548     $rp = strrev(trim($rp, '/'));
549     $rp = explode('/', $rp);
550     foreach($rp as $r) {
551         if (strpos($siteroot, '/'.$r.'/') === 0) {
552             $siteroot = substr($siteroot, strlen($r)+1); // moodle web in subdirectory
553         } else {
554             break; // probably alias root
555         }
556     }
558     $siteroot = strrev($siteroot);
559     $dataroot = str_replace('\\', '/', $CFG->dataroot.'/');
561     if (strpos($dataroot, $siteroot) !== 0) {
562         return false;
563     }
565     if (!$fetchtest) {
566         return INSECURE_DATAROOT_WARNING;
567     }
569     // now try all methods to fetch a test file using http protocol
571     $httpdocroot = str_replace('\\', '/', strrev($CFG->dirroot.'/'));
572     preg_match('|(https?://[^/]+)|i', $CFG->wwwroot, $matches);
573     $httpdocroot = $matches[1];
574     $datarooturl = $httpdocroot.'/'. substr($dataroot, strlen($siteroot));
575     make_upload_directory('diag');
576     $testfile = $CFG->dataroot.'/diag/public.txt';
577     if (!file_exists($testfile)) {
578         file_put_contents($testfile, 'test file, do not delete');
579     }
580     $teststr = trim(file_get_contents($testfile));
581     if (empty($teststr)) {
582     // hmm, strange
583         return INSECURE_DATAROOT_WARNING;
584     }
586     $testurl = $datarooturl.'/diag/public.txt';
587     if (extension_loaded('curl') and
588         !(stripos(ini_get('disable_functions'), 'curl_init') !== FALSE) and
589         !(stripos(ini_get('disable_functions'), 'curl_setop') !== FALSE) and
590         ($ch = @curl_init($testurl)) !== false) {
591         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
592         curl_setopt($ch, CURLOPT_HEADER, false);
593         $data = curl_exec($ch);
594         if (!curl_errno($ch)) {
595             $data = trim($data);
596             if ($data === $teststr) {
597                 curl_close($ch);
598                 return INSECURE_DATAROOT_ERROR;
599             }
600         }
601         curl_close($ch);
602     }
604     if ($data = @file_get_contents($testurl)) {
605         $data = trim($data);
606         if ($data === $teststr) {
607             return INSECURE_DATAROOT_ERROR;
608         }
609     }
611     preg_match('|https?://([^/]+)|i', $testurl, $matches);
612     $sitename = $matches[1];
613     $error = 0;
614     if ($fp = @fsockopen($sitename, 80, $error)) {
615         preg_match('|https?://[^/]+(.*)|i', $testurl, $matches);
616         $localurl = $matches[1];
617         $out = "GET $localurl HTTP/1.1\r\n";
618         $out .= "Host: $sitename\r\n";
619         $out .= "Connection: Close\r\n\r\n";
620         fwrite($fp, $out);
621         $data = '';
622         $incoming = false;
623         while (!feof($fp)) {
624             if ($incoming) {
625                 $data .= fgets($fp, 1024);
626             } else if (@fgets($fp, 1024) === "\r\n") {
627                     $incoming = true;
628                 }
629         }
630         fclose($fp);
631         $data = trim($data);
632         if ($data === $teststr) {
633             return INSECURE_DATAROOT_ERROR;
634         }
635     }
637     return INSECURE_DATAROOT_WARNING;
640 /// CLASS DEFINITIONS /////////////////////////////////////////////////////////
643 /**
644  * Interface for anything appearing in the admin tree
645  *
646  * The interface that is implemented by anything that appears in the admin tree
647  * block. It forces inheriting classes to define a method for checking user permissions
648  * and methods for finding something in the admin tree.
649  *
650  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
651  */
652 interface part_of_admin_tree {
654 /**
655  * Finds a named part_of_admin_tree.
656  *
657  * Used to find a part_of_admin_tree. If a class only inherits part_of_admin_tree
658  * and not parentable_part_of_admin_tree, then this function should only check if
659  * $this->name matches $name. If it does, it should return a reference to $this,
660  * otherwise, it should return a reference to NULL.
661  *
662  * If a class inherits parentable_part_of_admin_tree, this method should be called
663  * recursively on all child objects (assuming, of course, the parent object's name
664  * doesn't match the search criterion).
665  *
666  * @param string $name The internal name of the part_of_admin_tree we're searching for.
667  * @return mixed An object reference or a NULL reference.
668  */
669     public function locate($name);
671     /**
672      * Removes named part_of_admin_tree.
673      *
674      * @param string $name The internal name of the part_of_admin_tree we want to remove.
675      * @return bool success.
676      */
677     public function prune($name);
679     /**
680      * Search using query
681      * @param string $query
682      * @return mixed array-object structure of found settings and pages
683      */
684     public function search($query);
686     /**
687      * Verifies current user's access to this part_of_admin_tree.
688      *
689      * Used to check if the current user has access to this part of the admin tree or
690      * not. If a class only inherits part_of_admin_tree and not parentable_part_of_admin_tree,
691      * then this method is usually just a call to has_capability() in the site context.
692      *
693      * If a class inherits parentable_part_of_admin_tree, this method should return the
694      * logical OR of the return of check_access() on all child objects.
695      *
696      * @return bool True if the user has access, false if she doesn't.
697      */
698     public function check_access();
700     /**
701      * Mostly useful for removing of some parts of the tree in admin tree block.
702      *
703      * @return True is hidden from normal list view
704      */
705     public function is_hidden();
707     /**
708      * Show we display Save button at the page bottom?
709      * @return bool
710      */
711     public function show_save();
715 /**
716  * Interface implemented by any part_of_admin_tree that has children.
717  *
718  * The interface implemented by any part_of_admin_tree that can be a parent
719  * to other part_of_admin_tree's. (For now, this only includes admin_category.) Apart
720  * from ensuring part_of_admin_tree compliancy, it also ensures inheriting methods
721  * include an add method for adding other part_of_admin_tree objects as children.
722  *
723  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
724  */
725 interface parentable_part_of_admin_tree extends part_of_admin_tree {
727 /**
728  * Adds a part_of_admin_tree object to the admin tree.
729  *
730  * Used to add a part_of_admin_tree object to this object or a child of this
731  * object. $something should only be added if $destinationname matches
732  * $this->name. If it doesn't, add should be called on child objects that are
733  * also parentable_part_of_admin_tree's.
734  *
735  * @param string $destinationname The internal name of the new parent for $something.
736  * @param part_of_admin_tree $something The object to be added.
737  * @return bool True on success, false on failure.
738  */
739     public function add($destinationname, $something);
744 /**
745  * The object used to represent folders (a.k.a. categories) in the admin tree block.
746  *
747  * Each admin_category object contains a number of part_of_admin_tree objects.
748  *
749  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
750  */
751 class admin_category implements parentable_part_of_admin_tree {
753     /** @var mixed An array of part_of_admin_tree objects that are this object's children */
754     public $children;
755     /** @var string An internal name for this category. Must be unique amongst ALL part_of_admin_tree objects */
756     public $name;
757     /** @var string The displayed name for this category. Usually obtained through get_string() */
758     public $visiblename;
759     /** @var bool Should this category be hidden in admin tree block? */
760     public $hidden;
761     /** @var mixed Either a string or an array or strings */
762     public $path;
763     /** @var mixed Either a string or an array or strings */
764     public $visiblepath;
766     /** @var array fast lookup category cache, all categories of one tree point to one cache */
767     protected $category_cache;
769     /**
770      * Constructor for an empty admin category
771      *
772      * @param string $name The internal name for this category. Must be unique amongst ALL part_of_admin_tree objects
773      * @param string $visiblename The displayed named for this category. Usually obtained through get_string()
774      * @param bool $hidden hide category in admin tree block, defaults to false
775      */
776     public function __construct($name, $visiblename, $hidden=false) {
777         $this->children    = array();
778         $this->name        = $name;
779         $this->visiblename = $visiblename;
780         $this->hidden      = $hidden;
781     }
783     /**
784      * Returns a reference to the part_of_admin_tree object with internal name $name.
785      *
786      * @param string $name The internal name of the object we want.
787      * @param bool $findpath initialize path and visiblepath arrays
788      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
789      *                  defaults to false
790      */
791     public function locate($name, $findpath=false) {
792         if (is_array($this->category_cache) and !isset($this->category_cache[$this->name])) {
793             // somebody much have purged the cache
794             $this->category_cache[$this->name] = $this;
795         }
797         if ($this->name == $name) {
798             if ($findpath) {
799                 $this->visiblepath[] = $this->visiblename;
800                 $this->path[]        = $this->name;
801             }
802             return $this;
803         }
805         // quick category lookup
806         if (!$findpath and is_array($this->category_cache) and isset($this->category_cache[$name])) {
807             return $this->category_cache[$name];
808         }
810         $return = NULL;
811         foreach($this->children as $childid=>$unused) {
812             if ($return = $this->children[$childid]->locate($name, $findpath)) {
813                 break;
814             }
815         }
817         if (!is_null($return) and $findpath) {
818             $return->visiblepath[] = $this->visiblename;
819             $return->path[]        = $this->name;
820         }
822         return $return;
823     }
825     /**
826      * Search using query
827      *
828      * @param string query
829      * @return mixed array-object structure of found settings and pages
830      */
831     public function search($query) {
832         $result = array();
833         foreach ($this->children as $child) {
834             $subsearch = $child->search($query);
835             if (!is_array($subsearch)) {
836                 debugging('Incorrect search result from '.$child->name);
837                 continue;
838             }
839             $result = array_merge($result, $subsearch);
840         }
841         return $result;
842     }
844     /**
845      * Removes part_of_admin_tree object with internal name $name.
846      *
847      * @param string $name The internal name of the object we want to remove.
848      * @return bool success
849      */
850     public function prune($name) {
852         if ($this->name == $name) {
853             return false;  //can not remove itself
854         }
856         foreach($this->children as $precedence => $child) {
857             if ($child->name == $name) {
858                 // clear cache and delete self
859                 if (is_array($this->category_cache)) {
860                     while($this->category_cache) {
861                         // delete the cache, but keep the original array address
862                         array_pop($this->category_cache);
863                     }
864                 }
865                 unset($this->children[$precedence]);
866                 return true;
867             } else if ($this->children[$precedence]->prune($name)) {
868                 return true;
869             }
870         }
871         return false;
872     }
874     /**
875      * Adds a part_of_admin_tree to a child or grandchild (or great-grandchild, and so forth) of this object.
876      *
877      * @param string $destinationame The internal name of the immediate parent that we want for $something.
878      * @param mixed $something A part_of_admin_tree or setting instance to be added.
879      * @return bool True if successfully added, false if $something can not be added.
880      */
881     public function add($parentname, $something) {
882         $parent = $this->locate($parentname);
883         if (is_null($parent)) {
884             debugging('parent does not exist!');
885             return false;
886         }
888         if ($something instanceof part_of_admin_tree) {
889             if (!($parent instanceof parentable_part_of_admin_tree)) {
890                 debugging('error - parts of tree can be inserted only into parentable parts');
891                 return false;
892             }
893             $parent->children[] = $something;
894             if (is_array($this->category_cache) and ($something instanceof admin_category)) {
895                 if (isset($this->category_cache[$something->name])) {
896                     debugging('Duplicate admin category name: '.$something->name);
897                 } else {
898                     $this->category_cache[$something->name] = $something;
899                     $something->category_cache =& $this->category_cache;
900                     foreach ($something->children as $child) {
901                         // just in case somebody already added subcategories
902                         if ($child instanceof admin_category) {
903                             if (isset($this->category_cache[$child->name])) {
904                                 debugging('Duplicate admin category name: '.$child->name);
905                             } else {
906                                 $this->category_cache[$child->name] = $child;
907                                 $child->category_cache =& $this->category_cache;
908                             }
909                         }
910                     }
911                 }
912             }
913             return true;
915         } else {
916             debugging('error - can not add this element');
917             return false;
918         }
920     }
922     /**
923      * Checks if the user has access to anything in this category.
924      *
925      * @return bool True if the user has access to at least one child in this category, false otherwise.
926      */
927     public function check_access() {
928         foreach ($this->children as $child) {
929             if ($child->check_access()) {
930                 return true;
931             }
932         }
933         return false;
934     }
936     /**
937      * Is this category hidden in admin tree block?
938      *
939      * @return bool True if hidden
940      */
941     public function is_hidden() {
942         return $this->hidden;
943     }
945     /**
946      * Show we display Save button at the page bottom?
947      * @return bool
948      */
949     public function show_save() {
950         foreach ($this->children as $child) {
951             if ($child->show_save()) {
952                 return true;
953             }
954         }
955         return false;
956     }
960 /**
961  * Root of admin settings tree, does not have any parent.
962  *
963  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
964  */
965 class admin_root extends admin_category {
966 /** @var array List of errors */
967     public $errors;
968     /** @var string search query */
969     public $search;
970     /** @var bool full tree flag - true means all settings required, false only pages required */
971     public $fulltree;
972     /** @var bool flag indicating loaded tree */
973     public $loaded;
974     /** @var mixed site custom defaults overriding defaults in settings files*/
975     public $custom_defaults;
977     /**
978      * @param bool $fulltree true means all settings required,
979      *                            false only pages required
980      */
981     public function __construct($fulltree) {
982         global $CFG;
984         parent::__construct('root', get_string('administration'), false);
985         $this->errors   = array();
986         $this->search   = '';
987         $this->fulltree = $fulltree;
988         $this->loaded   = false;
990         $this->category_cache = array();
992         // load custom defaults if found
993         $this->custom_defaults = null;
994         $defaultsfile = "$CFG->dirroot/local/defaults.php";
995         if (is_readable($defaultsfile)) {
996             $defaults = array();
997             include($defaultsfile);
998             if (is_array($defaults) and count($defaults)) {
999                 $this->custom_defaults = $defaults;
1000             }
1001         }
1002     }
1004     /**
1005      * Empties children array, and sets loaded to false
1006      *
1007      * @param bool $requirefulltree
1008      */
1009     public function purge_children($requirefulltree) {
1010         $this->children = array();
1011         $this->fulltree = ($requirefulltree || $this->fulltree);
1012         $this->loaded   = false;
1013         //break circular dependencies - this helps PHP 5.2
1014         while($this->category_cache) {
1015             array_pop($this->category_cache);
1016         }
1017         $this->category_cache = array();
1018     }
1022 /**
1023  * Links external PHP pages into the admin tree.
1024  *
1025  * See detailed usage example at the top of this document (adminlib.php)
1026  *
1027  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1028  */
1029 class admin_externalpage implements part_of_admin_tree {
1031     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1032     public $name;
1034     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1035     public $visiblename;
1037     /** @var string The external URL that we should link to when someone requests this external page. */
1038     public $url;
1040     /** @var string The role capability/permission a user must have to access this external page. */
1041     public $req_capability;
1043     /** @var object The context in which capability/permission should be checked, default is site context. */
1044     public $context;
1046     /** @var bool hidden in admin tree block. */
1047     public $hidden;
1049     /** @var mixed either string or array of string */
1050     public $path;
1052     /** @var array list of visible names of page parents */
1053     public $visiblepath;
1055     /**
1056      * Constructor for adding an external page into the admin tree.
1057      *
1058      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1059      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1060      * @param string $url The external URL that we should link to when someone requests this external page.
1061      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1062      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1063      * @param stdClass $context The context the page relates to. Not sure what happens
1064      *      if you specify something other than system or front page. Defaults to system.
1065      */
1066     public function __construct($name, $visiblename, $url, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1067         $this->name        = $name;
1068         $this->visiblename = $visiblename;
1069         $this->url         = $url;
1070         if (is_array($req_capability)) {
1071             $this->req_capability = $req_capability;
1072         } else {
1073             $this->req_capability = array($req_capability);
1074         }
1075         $this->hidden = $hidden;
1076         $this->context = $context;
1077     }
1079     /**
1080      * Returns a reference to the part_of_admin_tree object with internal name $name.
1081      *
1082      * @param string $name The internal name of the object we want.
1083      * @param bool $findpath defaults to false
1084      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
1085      */
1086     public function locate($name, $findpath=false) {
1087         if ($this->name == $name) {
1088             if ($findpath) {
1089                 $this->visiblepath = array($this->visiblename);
1090                 $this->path        = array($this->name);
1091             }
1092             return $this;
1093         } else {
1094             $return = NULL;
1095             return $return;
1096         }
1097     }
1099     /**
1100      * This function always returns false, required function by interface
1101      *
1102      * @param string $name
1103      * @return false
1104      */
1105     public function prune($name) {
1106         return false;
1107     }
1109     /**
1110      * Search using query
1111      *
1112      * @param string $query
1113      * @return mixed array-object structure of found settings and pages
1114      */
1115     public function search($query) {
1116         $textlib = textlib_get_instance();
1118         $found = false;
1119         if (strpos(strtolower($this->name), $query) !== false) {
1120             $found = true;
1121         } else if (strpos($textlib->strtolower($this->visiblename), $query) !== false) {
1122                 $found = true;
1123             }
1124         if ($found) {
1125             $result = new stdClass();
1126             $result->page     = $this;
1127             $result->settings = array();
1128             return array($this->name => $result);
1129         } else {
1130             return array();
1131         }
1132     }
1134     /**
1135      * Determines if the current user has access to this external page based on $this->req_capability.
1136      *
1137      * @return bool True if user has access, false otherwise.
1138      */
1139     public function check_access() {
1140         global $CFG;
1141         $context = empty($this->context) ? get_context_instance(CONTEXT_SYSTEM) : $this->context;
1142         foreach($this->req_capability as $cap) {
1143             if (has_capability($cap, $context)) {
1144                 return true;
1145             }
1146         }
1147         return false;
1148     }
1150     /**
1151      * Is this external page hidden in admin tree block?
1152      *
1153      * @return bool True if hidden
1154      */
1155     public function is_hidden() {
1156         return $this->hidden;
1157     }
1159     /**
1160      * Show we display Save button at the page bottom?
1161      * @return bool
1162      */
1163     public function show_save() {
1164         return false;
1165     }
1169 /**
1170  * Used to group a number of admin_setting objects into a page and add them to the admin tree.
1171  *
1172  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1173  */
1174 class admin_settingpage implements part_of_admin_tree {
1176     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1177     public $name;
1179     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1180     public $visiblename;
1182     /** @var mixed An array of admin_setting objects that are part of this setting page. */
1183     public $settings;
1185     /** @var string The role capability/permission a user must have to access this external page. */
1186     public $req_capability;
1188     /** @var object The context in which capability/permission should be checked, default is site context. */
1189     public $context;
1191     /** @var bool hidden in admin tree block. */
1192     public $hidden;
1194     /** @var mixed string of paths or array of strings of paths */
1195     public $path;
1197     /** @var array list of visible names of page parents */
1198     public $visiblepath;
1200     /**
1201      * see admin_settingpage for details of this function
1202      *
1203      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1204      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1205      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1206      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1207      * @param stdClass $context The context the page relates to. Not sure what happens
1208      *      if you specify something other than system or front page. Defaults to system.
1209      */
1210     public function __construct($name, $visiblename, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1211         $this->settings    = new stdClass();
1212         $this->name        = $name;
1213         $this->visiblename = $visiblename;
1214         if (is_array($req_capability)) {
1215             $this->req_capability = $req_capability;
1216         } else {
1217             $this->req_capability = array($req_capability);
1218         }
1219         $this->hidden      = $hidden;
1220         $this->context     = $context;
1221     }
1223     /**
1224      * see admin_category
1225      *
1226      * @param string $name
1227      * @param bool $findpath
1228      * @return mixed Object (this) if name ==  this->name, else returns null
1229      */
1230     public function locate($name, $findpath=false) {
1231         if ($this->name == $name) {
1232             if ($findpath) {
1233                 $this->visiblepath = array($this->visiblename);
1234                 $this->path        = array($this->name);
1235             }
1236             return $this;
1237         } else {
1238             $return = NULL;
1239             return $return;
1240         }
1241     }
1243     /**
1244      * Search string in settings page.
1245      *
1246      * @param string $query
1247      * @return array
1248      */
1249     public function search($query) {
1250         $found = array();
1252         foreach ($this->settings as $setting) {
1253             if ($setting->is_related($query)) {
1254                 $found[] = $setting;
1255             }
1256         }
1258         if ($found) {
1259             $result = new stdClass();
1260             $result->page     = $this;
1261             $result->settings = $found;
1262             return array($this->name => $result);
1263         }
1265         $textlib = textlib_get_instance();
1267         $found = false;
1268         if (strpos(strtolower($this->name), $query) !== false) {
1269             $found = true;
1270         } else if (strpos($textlib->strtolower($this->visiblename), $query) !== false) {
1271                 $found = true;
1272             }
1273         if ($found) {
1274             $result = new stdClass();
1275             $result->page     = $this;
1276             $result->settings = array();
1277             return array($this->name => $result);
1278         } else {
1279             return array();
1280         }
1281     }
1283     /**
1284      * This function always returns false, required by interface
1285      *
1286      * @param string $name
1287      * @return bool Always false
1288      */
1289     public function prune($name) {
1290         return false;
1291     }
1293     /**
1294      * adds an admin_setting to this admin_settingpage
1295      *
1296      * 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
1297      * n.b. each admin_setting in an admin_settingpage must have a unique internal name
1298      *
1299      * @param object $setting is the admin_setting object you want to add
1300      * @return bool true if successful, false if not
1301      */
1302     public function add($setting) {
1303         if (!($setting instanceof admin_setting)) {
1304             debugging('error - not a setting instance');
1305             return false;
1306         }
1308         $this->settings->{$setting->name} = $setting;
1309         return true;
1310     }
1312     /**
1313      * see admin_externalpage
1314      *
1315      * @return bool Returns true for yes false for no
1316      */
1317     public function check_access() {
1318         global $CFG;
1319         $context = empty($this->context) ? get_context_instance(CONTEXT_SYSTEM) : $this->context;
1320         foreach($this->req_capability as $cap) {
1321             if (has_capability($cap, $context)) {
1322                 return true;
1323             }
1324         }
1325         return false;
1326     }
1328     /**
1329      * outputs this page as html in a table (suitable for inclusion in an admin pagetype)
1330      * @return string Returns an XHTML string
1331      */
1332     public function output_html() {
1333         $adminroot = admin_get_root();
1334         $return = '<fieldset>'."\n".'<div class="clearer"><!-- --></div>'."\n";
1335         foreach($this->settings as $setting) {
1336             $fullname = $setting->get_full_name();
1337             if (array_key_exists($fullname, $adminroot->errors)) {
1338                 $data = $adminroot->errors[$fullname]->data;
1339             } else {
1340                 $data = $setting->get_setting();
1341                 // do not use defaults if settings not available - upgrade settings handles the defaults!
1342             }
1343             $return .= $setting->output_html($data);
1344         }
1345         $return .= '</fieldset>';
1346         return $return;
1347     }
1349     /**
1350      * Is this settings page hidden in admin tree block?
1351      *
1352      * @return bool True if hidden
1353      */
1354     public function is_hidden() {
1355         return $this->hidden;
1356     }
1358     /**
1359      * Show we display Save button at the page bottom?
1360      * @return bool
1361      */
1362     public function show_save() {
1363         foreach($this->settings as $setting) {
1364             if (empty($setting->nosave)) {
1365                 return true;
1366             }
1367         }
1368         return false;
1369     }
1373 /**
1374  * Admin settings class. Only exists on setting pages.
1375  * Read & write happens at this level; no authentication.
1376  *
1377  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1378  */
1379 abstract class admin_setting {
1380     /** @var string unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins. */
1381     public $name;
1382     /** @var string localised name */
1383     public $visiblename;
1384     /** @var string localised long description in Markdown format */
1385     public $description;
1386     /** @var mixed Can be string or array of string */
1387     public $defaultsetting;
1388     /** @var string */
1389     public $updatedcallback;
1390     /** @var mixed can be String or Null.  Null means main config table */
1391     public $plugin; // null means main config table
1392     /** @var bool true indicates this setting does not actually save anything, just information */
1393     public $nosave = false;
1394     /** @var bool if set, indicates that a change to this setting requires rebuild course cache */
1395     public $affectsmodinfo = false;
1397     /**
1398      * Constructor
1399      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
1400      *                     or 'myplugin/mysetting' for ones in config_plugins.
1401      * @param string $visiblename localised name
1402      * @param string $description localised long description
1403      * @param mixed $defaultsetting string or array depending on implementation
1404      */
1405     public function __construct($name, $visiblename, $description, $defaultsetting) {
1406         $this->parse_setting_name($name);
1407         $this->visiblename    = $visiblename;
1408         $this->description    = $description;
1409         $this->defaultsetting = $defaultsetting;
1410     }
1412     /**
1413      * Set up $this->name and potentially $this->plugin
1414      *
1415      * Set up $this->name and possibly $this->plugin based on whether $name looks
1416      * like 'settingname' or 'plugin/settingname'. Also, do some sanity checking
1417      * on the names, that is, output a developer debug warning if the name
1418      * contains anything other than [a-zA-Z0-9_]+.
1419      *
1420      * @param string $name the setting name passed in to the constructor.
1421      */
1422     private function parse_setting_name($name) {
1423         $bits = explode('/', $name);
1424         if (count($bits) > 2) {
1425             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1426         }
1427         $this->name = array_pop($bits);
1428         if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->name)) {
1429             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1430         }
1431         if (!empty($bits)) {
1432             $this->plugin = array_pop($bits);
1433             if ($this->plugin === 'moodle') {
1434                 $this->plugin = null;
1435             } else if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->plugin)) {
1436                     throw new moodle_exception('invalidadminsettingname', '', '', $name);
1437                 }
1438         }
1439     }
1441     /**
1442      * Returns the fullname prefixed by the plugin
1443      * @return string
1444      */
1445     public function get_full_name() {
1446         return 's_'.$this->plugin.'_'.$this->name;
1447     }
1449     /**
1450      * Returns the ID string based on plugin and name
1451      * @return string
1452      */
1453     public function get_id() {
1454         return 'id_s_'.$this->plugin.'_'.$this->name;
1455     }
1457     /**
1458      * @param bool $affectsmodinfo If true, changes to this setting will
1459      *   cause the course cache to be rebuilt
1460      */
1461     public function set_affects_modinfo($affectsmodinfo) {
1462         $this->affectsmodinfo = $affectsmodinfo;
1463     }
1465     /**
1466      * Returns the config if possible
1467      *
1468      * @return mixed returns config if successful else null
1469      */
1470     public function config_read($name) {
1471         global $CFG;
1472         if (!empty($this->plugin)) {
1473             $value = get_config($this->plugin, $name);
1474             return $value === false ? NULL : $value;
1476         } else {
1477             if (isset($CFG->$name)) {
1478                 return $CFG->$name;
1479             } else {
1480                 return NULL;
1481             }
1482         }
1483     }
1485     /**
1486      * Used to set a config pair and log change
1487      *
1488      * @param string $name
1489      * @param mixed $value Gets converted to string if not null
1490      * @return bool Write setting to config table
1491      */
1492     public function config_write($name, $value) {
1493         global $DB, $USER, $CFG;
1495         if ($this->nosave) {
1496             return true;
1497         }
1499         // make sure it is a real change
1500         $oldvalue = get_config($this->plugin, $name);
1501         $oldvalue = ($oldvalue === false) ? null : $oldvalue; // normalise
1502         $value = is_null($value) ? null : (string)$value;
1504         if ($oldvalue === $value) {
1505             return true;
1506         }
1508         // store change
1509         set_config($name, $value, $this->plugin);
1511         // Some admin settings affect course modinfo
1512         if ($this->affectsmodinfo) {
1513             // Clear course cache for all courses
1514             rebuild_course_cache(0, true);
1515         }
1517         // log change
1518         $log = new stdClass();
1519         $log->userid       = during_initial_install() ? 0 :$USER->id; // 0 as user id during install
1520         $log->timemodified = time();
1521         $log->plugin       = $this->plugin;
1522         $log->name         = $name;
1523         $log->value        = $value;
1524         $log->oldvalue     = $oldvalue;
1525         $DB->insert_record('config_log', $log);
1527         return true; // BC only
1528     }
1530     /**
1531      * Returns current value of this setting
1532      * @return mixed array or string depending on instance, NULL means not set yet
1533      */
1534     public abstract function get_setting();
1536     /**
1537      * Returns default setting if exists
1538      * @return mixed array or string depending on instance; NULL means no default, user must supply
1539      */
1540     public function get_defaultsetting() {
1541         $adminroot =  admin_get_root(false, false);
1542         if (!empty($adminroot->custom_defaults)) {
1543             $plugin = is_null($this->plugin) ? 'moodle' : $this->plugin;
1544             if (isset($adminroot->custom_defaults[$plugin])) {
1545                 if (array_key_exists($this->name, $adminroot->custom_defaults[$plugin])) { // null is valid value here ;-)
1546                     return $adminroot->custom_defaults[$plugin][$this->name];
1547                 }
1548             }
1549         }
1550         return $this->defaultsetting;
1551     }
1553     /**
1554      * Store new setting
1555      *
1556      * @param mixed $data string or array, must not be NULL
1557      * @return string empty string if ok, string error message otherwise
1558      */
1559     public abstract function write_setting($data);
1561     /**
1562      * Return part of form with setting
1563      * This function should always be overwritten
1564      *
1565      * @param mixed $data array or string depending on setting
1566      * @param string $query
1567      * @return string
1568      */
1569     public function output_html($data, $query='') {
1570     // should be overridden
1571         return;
1572     }
1574     /**
1575      * Function called if setting updated - cleanup, cache reset, etc.
1576      * @param string $functionname Sets the function name
1577      * @return void
1578      */
1579     public function set_updatedcallback($functionname) {
1580         $this->updatedcallback = $functionname;
1581     }
1583     /**
1584      * Is setting related to query text - used when searching
1585      * @param string $query
1586      * @return bool
1587      */
1588     public function is_related($query) {
1589         if (strpos(strtolower($this->name), $query) !== false) {
1590             return true;
1591         }
1592         $textlib = textlib_get_instance();
1593         if (strpos($textlib->strtolower($this->visiblename), $query) !== false) {
1594             return true;
1595         }
1596         if (strpos($textlib->strtolower($this->description), $query) !== false) {
1597             return true;
1598         }
1599         $current = $this->get_setting();
1600         if (!is_null($current)) {
1601             if (is_string($current)) {
1602                 if (strpos($textlib->strtolower($current), $query) !== false) {
1603                     return true;
1604                 }
1605             }
1606         }
1607         $default = $this->get_defaultsetting();
1608         if (!is_null($default)) {
1609             if (is_string($default)) {
1610                 if (strpos($textlib->strtolower($default), $query) !== false) {
1611                     return true;
1612                 }
1613             }
1614         }
1615         return false;
1616     }
1620 /**
1621  * No setting - just heading and text.
1622  *
1623  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1624  */
1625 class admin_setting_heading extends admin_setting {
1627     /**
1628      * not a setting, just text
1629      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1630      * @param string $heading heading
1631      * @param string $information text in box
1632      */
1633     public function __construct($name, $heading, $information) {
1634         $this->nosave = true;
1635         parent::__construct($name, $heading, $information, '');
1636     }
1638     /**
1639      * Always returns true
1640      * @return bool Always returns true
1641      */
1642     public function get_setting() {
1643         return true;
1644     }
1646     /**
1647      * Always returns true
1648      * @return bool Always returns true
1649      */
1650     public function get_defaultsetting() {
1651         return true;
1652     }
1654     /**
1655      * Never write settings
1656      * @return string Always returns an empty string
1657      */
1658     public function write_setting($data) {
1659     // do not write any setting
1660         return '';
1661     }
1663     /**
1664      * Returns an HTML string
1665      * @return string Returns an HTML string
1666      */
1667     public function output_html($data, $query='') {
1668         global $OUTPUT;
1669         $return = '';
1670         if ($this->visiblename != '') {
1671             $return .= $OUTPUT->heading($this->visiblename, 3, 'main');
1672         }
1673         if ($this->description != '') {
1674             $return .= $OUTPUT->box(highlight($query, markdown_to_html($this->description)), 'generalbox formsettingheading');
1675         }
1676         return $return;
1677     }
1681 /**
1682  * The most flexibly setting, user is typing text
1683  *
1684  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1685  */
1686 class admin_setting_configtext extends admin_setting {
1688     /** @var mixed int means PARAM_XXX type, string is a allowed format in regex */
1689     public $paramtype;
1690     /** @var int default field size */
1691     public $size;
1693     /**
1694      * Config text constructor
1695      *
1696      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1697      * @param string $visiblename localised
1698      * @param string $description long localised info
1699      * @param string $defaultsetting
1700      * @param mixed $paramtype int means PARAM_XXX type, string is a allowed format in regex
1701      * @param int $size default field size
1702      */
1703     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $size=null) {
1704         $this->paramtype = $paramtype;
1705         if (!is_null($size)) {
1706             $this->size  = $size;
1707         } else {
1708             $this->size  = ($paramtype === PARAM_INT) ? 5 : 30;
1709         }
1710         parent::__construct($name, $visiblename, $description, $defaultsetting);
1711     }
1713     /**
1714      * Return the setting
1715      *
1716      * @return mixed returns config if successful else null
1717      */
1718     public function get_setting() {
1719         return $this->config_read($this->name);
1720     }
1722     public function write_setting($data) {
1723         if ($this->paramtype === PARAM_INT and $data === '') {
1724         // do not complain if '' used instead of 0
1725             $data = 0;
1726         }
1727         // $data is a string
1728         $validated = $this->validate($data);
1729         if ($validated !== true) {
1730             return $validated;
1731         }
1732         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
1733     }
1735     /**
1736      * Validate data before storage
1737      * @param string data
1738      * @return mixed true if ok string if error found
1739      */
1740     public function validate($data) {
1741         // allow paramtype to be a custom regex if it is the form of /pattern/
1742         if (preg_match('#^/.*/$#', $this->paramtype)) {
1743             if (preg_match($this->paramtype, $data)) {
1744                 return true;
1745             } else {
1746                 return get_string('validateerror', 'admin');
1747             }
1749         } else if ($this->paramtype === PARAM_RAW) {
1750             return true;
1752         } else {
1753             $cleaned = clean_param($data, $this->paramtype);
1754             if ("$data" === "$cleaned") { // implicit conversion to string is needed to do exact comparison
1755                 return true;
1756             } else {
1757                 return get_string('validateerror', 'admin');
1758             }
1759         }
1760     }
1762     /**
1763      * Return an XHTML string for the setting
1764      * @return string Returns an XHTML string
1765      */
1766     public function output_html($data, $query='') {
1767         $default = $this->get_defaultsetting();
1769         return format_admin_setting($this, $this->visiblename,
1770         '<div class="form-text defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" /></div>',
1771         $this->description, true, '', $default, $query);
1772     }
1776 /**
1777  * General text area without html editor.
1778  *
1779  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1780  */
1781 class admin_setting_configtextarea extends admin_setting_configtext {
1782     private $rows;
1783     private $cols;
1785     /**
1786      * @param string $name
1787      * @param string $visiblename
1788      * @param string $description
1789      * @param mixed $defaultsetting string or array
1790      * @param mixed $paramtype
1791      * @param string $cols The number of columns to make the editor
1792      * @param string $rows The number of rows to make the editor
1793      */
1794     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
1795         $this->rows = $rows;
1796         $this->cols = $cols;
1797         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
1798     }
1800     /**
1801      * Returns an XHTML string for the editor
1802      *
1803      * @param string $data
1804      * @param string $query
1805      * @return string XHTML string for the editor
1806      */
1807     public function output_html($data, $query='') {
1808         $default = $this->get_defaultsetting();
1810         $defaultinfo = $default;
1811         if (!is_null($default) and $default !== '') {
1812             $defaultinfo = "\n".$default;
1813         }
1815         return format_admin_setting($this, $this->visiblename,
1816         '<div class="form-textarea" ><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'">'. s($data) .'</textarea></div>',
1817         $this->description, true, '', $defaultinfo, $query);
1818     }
1822 /**
1823  * General text area with html editor.
1824  */
1825 class admin_setting_confightmleditor extends admin_setting_configtext {
1826     private $rows;
1827     private $cols;
1829     /**
1830      * @param string $name
1831      * @param string $visiblename
1832      * @param string $description
1833      * @param mixed $defaultsetting string or array
1834      * @param mixed $paramtype
1835      */
1836     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
1837         $this->rows = $rows;
1838         $this->cols = $cols;
1839         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
1840         editors_head_setup();
1841     }
1843     /**
1844      * Returns an XHTML string for the editor
1845      *
1846      * @param string $data
1847      * @param string $query
1848      * @return string XHTML string for the editor
1849      */
1850     public function output_html($data, $query='') {
1851         $default = $this->get_defaultsetting();
1853         $defaultinfo = $default;
1854         if (!is_null($default) and $default !== '') {
1855             $defaultinfo = "\n".$default;
1856         }
1858         $editor = editors_get_preferred_editor(FORMAT_HTML);
1859         $editor->use_editor($this->get_id(), array('noclean'=>true));
1861         return format_admin_setting($this, $this->visiblename,
1862         '<div class="form-textarea"><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'">'. s($data) .'</textarea></div>',
1863         $this->description, true, '', $defaultinfo, $query);
1864     }
1868 /**
1869  * Password field, allows unmasking of password
1870  *
1871  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1872  */
1873 class admin_setting_configpasswordunmask extends admin_setting_configtext {
1874     /**
1875      * Constructor
1876      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1877      * @param string $visiblename localised
1878      * @param string $description long localised info
1879      * @param string $defaultsetting default password
1880      */
1881     public function __construct($name, $visiblename, $description, $defaultsetting) {
1882         parent::__construct($name, $visiblename, $description, $defaultsetting, PARAM_RAW, 30);
1883     }
1885     /**
1886      * Returns XHTML for the field
1887      * Writes Javascript into the HTML below right before the last div
1888      *
1889      * @todo Make javascript available through newer methods if possible
1890      * @param string $data Value for the field
1891      * @param string $query Passed as final argument for format_admin_setting
1892      * @return string XHTML field
1893      */
1894     public function output_html($data, $query='') {
1895         $id = $this->get_id();
1896         $unmask = get_string('unmaskpassword', 'form');
1897         $unmaskjs = '<script type="text/javascript">
1898 //<![CDATA[
1899 var is_ie = (navigator.userAgent.toLowerCase().indexOf("msie") != -1);
1901 document.getElementById("'.$id.'").setAttribute("autocomplete", "off");
1903 var unmaskdiv = document.getElementById("'.$id.'unmaskdiv");
1905 var unmaskchb = document.createElement("input");
1906 unmaskchb.setAttribute("type", "checkbox");
1907 unmaskchb.setAttribute("id", "'.$id.'unmask");
1908 unmaskchb.onchange = function() {unmaskPassword("'.$id.'");};
1909 unmaskdiv.appendChild(unmaskchb);
1911 var unmasklbl = document.createElement("label");
1912 unmasklbl.innerHTML = "'.addslashes_js($unmask).'";
1913 if (is_ie) {
1914   unmasklbl.setAttribute("htmlFor", "'.$id.'unmask");
1915 } else {
1916   unmasklbl.setAttribute("for", "'.$id.'unmask");
1918 unmaskdiv.appendChild(unmasklbl);
1920 if (is_ie) {
1921   // ugly hack to work around the famous onchange IE bug
1922   unmaskchb.onclick = function() {this.blur();};
1923   unmaskdiv.onclick = function() {this.blur();};
1925 //]]>
1926 </script>';
1927         return format_admin_setting($this, $this->visiblename,
1928         '<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>',
1929         $this->description, true, '', NULL, $query);
1930     }
1934 /**
1935  * Path to directory
1936  *
1937  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1938  */
1939 class admin_setting_configfile extends admin_setting_configtext {
1940     /**
1941      * Constructor
1942      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1943      * @param string $visiblename localised
1944      * @param string $description long localised info
1945      * @param string $defaultdirectory default directory location
1946      */
1947     public function __construct($name, $visiblename, $description, $defaultdirectory) {
1948         parent::__construct($name, $visiblename, $description, $defaultdirectory, PARAM_RAW, 50);
1949     }
1951     /**
1952      * Returns XHTML for the field
1953      *
1954      * Returns XHTML for the field and also checks whether the file
1955      * specified in $data exists using file_exists()
1956      *
1957      * @param string $data File name and path to use in value attr
1958      * @param string $query
1959      * @return string XHTML field
1960      */
1961     public function output_html($data, $query='') {
1962         $default = $this->get_defaultsetting();
1964         if ($data) {
1965             if (file_exists($data)) {
1966                 $executable = '<span class="pathok">&#x2714;</span>';
1967             } else {
1968                 $executable = '<span class="patherror">&#x2718;</span>';
1969             }
1970         } else {
1971             $executable = '';
1972         }
1974         return format_admin_setting($this, $this->visiblename,
1975         '<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>',
1976         $this->description, true, '', $default, $query);
1977     }
1981 /**
1982  * Path to executable file
1983  *
1984  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1985  */
1986 class admin_setting_configexecutable extends admin_setting_configfile {
1988     /**
1989      * Returns an XHTML field
1990      *
1991      * @param string $data This is the value for the field
1992      * @param string $query
1993      * @return string XHTML field
1994      */
1995     public function output_html($data, $query='') {
1996         $default = $this->get_defaultsetting();
1998         if ($data) {
1999             if (file_exists($data) and is_executable($data)) {
2000                 $executable = '<span class="pathok">&#x2714;</span>';
2001             } else {
2002                 $executable = '<span class="patherror">&#x2718;</span>';
2003             }
2004         } else {
2005             $executable = '';
2006         }
2008         return format_admin_setting($this, $this->visiblename,
2009         '<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>',
2010         $this->description, true, '', $default, $query);
2011     }
2015 /**
2016  * Path to directory
2017  *
2018  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2019  */
2020 class admin_setting_configdirectory extends admin_setting_configfile {
2022     /**
2023      * Returns an XHTML field
2024      *
2025      * @param string $data This is the value for the field
2026      * @param string $query
2027      * @return string XHTML
2028      */
2029     public function output_html($data, $query='') {
2030         $default = $this->get_defaultsetting();
2032         if ($data) {
2033             if (file_exists($data) and is_dir($data)) {
2034                 $executable = '<span class="pathok">&#x2714;</span>';
2035             } else {
2036                 $executable = '<span class="patherror">&#x2718;</span>';
2037             }
2038         } else {
2039             $executable = '';
2040         }
2042         return format_admin_setting($this, $this->visiblename,
2043         '<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>',
2044         $this->description, true, '', $default, $query);
2045     }
2049 /**
2050  * Checkbox
2051  *
2052  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2053  */
2054 class admin_setting_configcheckbox extends admin_setting {
2055     /** @var string Value used when checked */
2056     public $yes;
2057     /** @var string Value used when not checked */
2058     public $no;
2060     /**
2061      * Constructor
2062      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2063      * @param string $visiblename localised
2064      * @param string $description long localised info
2065      * @param string $defaultsetting
2066      * @param string $yes value used when checked
2067      * @param string $no value used when not checked
2068      */
2069     public function __construct($name, $visiblename, $description, $defaultsetting, $yes='1', $no='0') {
2070         parent::__construct($name, $visiblename, $description, $defaultsetting);
2071         $this->yes = (string)$yes;
2072         $this->no  = (string)$no;
2073     }
2075     /**
2076      * Retrieves the current setting using the objects name
2077      *
2078      * @return string
2079      */
2080     public function get_setting() {
2081         return $this->config_read($this->name);
2082     }
2084     /**
2085      * Sets the value for the setting
2086      *
2087      * Sets the value for the setting to either the yes or no values
2088      * of the object by comparing $data to yes
2089      *
2090      * @param mixed $data Gets converted to str for comparison against yes value
2091      * @return string empty string or error
2092      */
2093     public function write_setting($data) {
2094         if ((string)$data === $this->yes) { // convert to strings before comparison
2095             $data = $this->yes;
2096         } else {
2097             $data = $this->no;
2098         }
2099         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2100     }
2102     /**
2103      * Returns an XHTML checkbox field
2104      *
2105      * @param string $data If $data matches yes then checkbox is checked
2106      * @param string $query
2107      * @return string XHTML field
2108      */
2109     public function output_html($data, $query='') {
2110         $default = $this->get_defaultsetting();
2112         if (!is_null($default)) {
2113             if ((string)$default === $this->yes) {
2114                 $defaultinfo = get_string('checkboxyes', 'admin');
2115             } else {
2116                 $defaultinfo = get_string('checkboxno', 'admin');
2117             }
2118         } else {
2119             $defaultinfo = NULL;
2120         }
2122         if ((string)$data === $this->yes) { // convert to strings before comparison
2123             $checked = 'checked="checked"';
2124         } else {
2125             $checked = '';
2126         }
2128         return format_admin_setting($this, $this->visiblename,
2129         '<div class="form-checkbox defaultsnext" ><input type="hidden" name="'.$this->get_full_name().'" value="'.s($this->no).'" /> '
2130             .'<input type="checkbox" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($this->yes).'" '.$checked.' /></div>',
2131         $this->description, true, '', $defaultinfo, $query);
2132     }
2136 /**
2137  * Multiple checkboxes, each represents different value, stored in csv format
2138  *
2139  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2140  */
2141 class admin_setting_configmulticheckbox extends admin_setting {
2142     /** @var array Array of choices value=>label */
2143     public $choices;
2145     /**
2146      * Constructor: uses parent::__construct
2147      *
2148      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2149      * @param string $visiblename localised
2150      * @param string $description long localised info
2151      * @param array $defaultsetting array of selected
2152      * @param array $choices array of $value=>$label for each checkbox
2153      */
2154     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2155         $this->choices = $choices;
2156         parent::__construct($name, $visiblename, $description, $defaultsetting);
2157     }
2159     /**
2160      * This public function may be used in ancestors for lazy loading of choices
2161      *
2162      * @todo Check if this function is still required content commented out only returns true
2163      * @return bool true if loaded, false if error
2164      */
2165     public function load_choices() {
2166         /*
2167         if (is_array($this->choices)) {
2168             return true;
2169         }
2170         .... load choices here
2171         */
2172         return true;
2173     }
2175     /**
2176      * Is setting related to query text - used when searching
2177      *
2178      * @param string $query
2179      * @return bool true on related, false on not or failure
2180      */
2181     public function is_related($query) {
2182         if (!$this->load_choices() or empty($this->choices)) {
2183             return false;
2184         }
2185         if (parent::is_related($query)) {
2186             return true;
2187         }
2189         $textlib = textlib_get_instance();
2190         foreach ($this->choices as $desc) {
2191             if (strpos($textlib->strtolower($desc), $query) !== false) {
2192                 return true;
2193             }
2194         }
2195         return false;
2196     }
2198     /**
2199      * Returns the current setting if it is set
2200      *
2201      * @return mixed null if null, else an array
2202      */
2203     public function get_setting() {
2204         $result = $this->config_read($this->name);
2206         if (is_null($result)) {
2207             return NULL;
2208         }
2209         if ($result === '') {
2210             return array();
2211         }
2212         $enabled = explode(',', $result);
2213         $setting = array();
2214         foreach ($enabled as $option) {
2215             $setting[$option] = 1;
2216         }
2217         return $setting;
2218     }
2220     /**
2221      * Saves the setting(s) provided in $data
2222      *
2223      * @param array $data An array of data, if not array returns empty str
2224      * @return mixed empty string on useless data or bool true=success, false=failed
2225      */
2226     public function write_setting($data) {
2227         if (!is_array($data)) {
2228             return ''; // ignore it
2229         }
2230         if (!$this->load_choices() or empty($this->choices)) {
2231             return '';
2232         }
2233         unset($data['xxxxx']);
2234         $result = array();
2235         foreach ($data as $key => $value) {
2236             if ($value and array_key_exists($key, $this->choices)) {
2237                 $result[] = $key;
2238             }
2239         }
2240         return $this->config_write($this->name, implode(',', $result)) ? '' : get_string('errorsetting', 'admin');
2241     }
2243     /**
2244      * Returns XHTML field(s) as required by choices
2245      *
2246      * Relies on data being an array should data ever be another valid vartype with
2247      * acceptable value this may cause a warning/error
2248      * if (!is_array($data)) would fix the problem
2249      *
2250      * @todo Add vartype handling to ensure $data is an array
2251      *
2252      * @param array $data An array of checked values
2253      * @param string $query
2254      * @return string XHTML field
2255      */
2256     public function output_html($data, $query='') {
2257         if (!$this->load_choices() or empty($this->choices)) {
2258             return '';
2259         }
2260         $default = $this->get_defaultsetting();
2261         if (is_null($default)) {
2262             $default = array();
2263         }
2264         if (is_null($data)) {
2265             $data = array();
2266         }
2267         $options = array();
2268         $defaults = array();
2269         foreach ($this->choices as $key=>$description) {
2270             if (!empty($data[$key])) {
2271                 $checked = 'checked="checked"';
2272             } else {
2273                 $checked = '';
2274             }
2275             if (!empty($default[$key])) {
2276                 $defaults[] = $description;
2277             }
2279             $options[] = '<input type="checkbox" id="'.$this->get_id().'_'.$key.'" name="'.$this->get_full_name().'['.$key.']" value="1" '.$checked.' />'
2280                 .'<label for="'.$this->get_id().'_'.$key.'">'.highlightfast($query, $description).'</label>';
2281         }
2283         if (is_null($default)) {
2284             $defaultinfo = NULL;
2285         } else if (!empty($defaults)) {
2286                 $defaultinfo = implode(', ', $defaults);
2287             } else {
2288                 $defaultinfo = get_string('none');
2289             }
2291         $return = '<div class="form-multicheckbox">';
2292         $return .= '<input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2293         if ($options) {
2294             $return .= '<ul>';
2295             foreach ($options as $option) {
2296                 $return .= '<li>'.$option.'</li>';
2297             }
2298             $return .= '</ul>';
2299         }
2300         $return .= '</div>';
2302         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
2304     }
2308 /**
2309  * Multiple checkboxes 2, value stored as string 00101011
2310  *
2311  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2312  */
2313 class admin_setting_configmulticheckbox2 extends admin_setting_configmulticheckbox {
2315     /**
2316      * Returns the setting if set
2317      *
2318      * @return mixed null if not set, else an array of set settings
2319      */
2320     public function get_setting() {
2321         $result = $this->config_read($this->name);
2322         if (is_null($result)) {
2323             return NULL;
2324         }
2325         if (!$this->load_choices()) {
2326             return NULL;
2327         }
2328         $result = str_pad($result, count($this->choices), '0');
2329         $result = preg_split('//', $result, -1, PREG_SPLIT_NO_EMPTY);
2330         $setting = array();
2331         foreach ($this->choices as $key=>$unused) {
2332             $value = array_shift($result);
2333             if ($value) {
2334                 $setting[$key] = 1;
2335             }
2336         }
2337         return $setting;
2338     }
2340     /**
2341      * Save setting(s) provided in $data param
2342      *
2343      * @param array $data An array of settings to save
2344      * @return mixed empty string for bad data or bool true=>success, false=>error
2345      */
2346     public function write_setting($data) {
2347         if (!is_array($data)) {
2348             return ''; // ignore it
2349         }
2350         if (!$this->load_choices() or empty($this->choices)) {
2351             return '';
2352         }
2353         $result = '';
2354         foreach ($this->choices as $key=>$unused) {
2355             if (!empty($data[$key])) {
2356                 $result .= '1';
2357             } else {
2358                 $result .= '0';
2359             }
2360         }
2361         return $this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin');
2362     }
2366 /**
2367  * Select one value from list
2368  *
2369  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2370  */
2371 class admin_setting_configselect extends admin_setting {
2372     /** @var array Array of choices value=>label */
2373     public $choices;
2375     /**
2376      * Constructor
2377      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2378      * @param string $visiblename localised
2379      * @param string $description long localised info
2380      * @param string|int $defaultsetting
2381      * @param array $choices array of $value=>$label for each selection
2382      */
2383     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2384         $this->choices = $choices;
2385         parent::__construct($name, $visiblename, $description, $defaultsetting);
2386     }
2388     /**
2389      * This function may be used in ancestors for lazy loading of choices
2390      *
2391      * Override this method if loading of choices is expensive, such
2392      * as when it requires multiple db requests.
2393      *
2394      * @return bool true if loaded, false if error
2395      */
2396     public function load_choices() {
2397         /*
2398         if (is_array($this->choices)) {
2399             return true;
2400         }
2401         .... load choices here
2402         */
2403         return true;
2404     }
2406     /**
2407      * Check if this is $query is related to a choice
2408      *
2409      * @param string $query
2410      * @return bool true if related, false if not
2411      */
2412     public function is_related($query) {
2413         if (parent::is_related($query)) {
2414             return true;
2415         }
2416         if (!$this->load_choices()) {
2417             return false;
2418         }
2419         $textlib = textlib_get_instance();
2420         foreach ($this->choices as $key=>$value) {
2421             if (strpos($textlib->strtolower($key), $query) !== false) {
2422                 return true;
2423             }
2424             if (strpos($textlib->strtolower($value), $query) !== false) {
2425                 return true;
2426             }
2427         }
2428         return false;
2429     }
2431     /**
2432      * Return the setting
2433      *
2434      * @return mixed returns config if successful else null
2435      */
2436     public function get_setting() {
2437         return $this->config_read($this->name);
2438     }
2440     /**
2441      * Save a setting
2442      *
2443      * @param string $data
2444      * @return string empty of error string
2445      */
2446     public function write_setting($data) {
2447         if (!$this->load_choices() or empty($this->choices)) {
2448             return '';
2449         }
2450         if (!array_key_exists($data, $this->choices)) {
2451             return ''; // ignore it
2452         }
2454         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2455     }
2457     /**
2458      * Returns XHTML select field
2459      *
2460      * Ensure the options are loaded, and generate the XHTML for the select
2461      * element and any warning message. Separating this out from output_html
2462      * makes it easier to subclass this class.
2463      *
2464      * @param string $data the option to show as selected.
2465      * @param string $current the currently selected option in the database, null if none.
2466      * @param string $default the default selected option.
2467      * @return array the HTML for the select element, and a warning message.
2468      */
2469     public function output_select_html($data, $current, $default, $extraname = '') {
2470         if (!$this->load_choices() or empty($this->choices)) {
2471             return array('', '');
2472         }
2474         $warning = '';
2475         if (is_null($current)) {
2476         // first run
2477         } else if (empty($current) and (array_key_exists('', $this->choices) or array_key_exists(0, $this->choices))) {
2478             // no warning
2479             } else if (!array_key_exists($current, $this->choices)) {
2480                     $warning = get_string('warningcurrentsetting', 'admin', s($current));
2481                     if (!is_null($default) and $data == $current) {
2482                         $data = $default; // use default instead of first value when showing the form
2483                     }
2484                 }
2486         $selecthtml = '<select id="'.$this->get_id().'" name="'.$this->get_full_name().$extraname.'">';
2487         foreach ($this->choices as $key => $value) {
2488         // the string cast is needed because key may be integer - 0 is equal to most strings!
2489             $selecthtml .= '<option value="'.$key.'"'.((string)$key==$data ? ' selected="selected"' : '').'>'.$value.'</option>';
2490         }
2491         $selecthtml .= '</select>';
2492         return array($selecthtml, $warning);
2493     }
2495     /**
2496      * Returns XHTML select field and wrapping div(s)
2497      *
2498      * @see output_select_html()
2499      *
2500      * @param string $data the option to show as selected
2501      * @param string $query
2502      * @return string XHTML field and wrapping div
2503      */
2504     public function output_html($data, $query='') {
2505         $default = $this->get_defaultsetting();
2506         $current = $this->get_setting();
2508         list($selecthtml, $warning) = $this->output_select_html($data, $current, $default);
2509         if (!$selecthtml) {
2510             return '';
2511         }
2513         if (!is_null($default) and array_key_exists($default, $this->choices)) {
2514             $defaultinfo = $this->choices[$default];
2515         } else {
2516             $defaultinfo = NULL;
2517         }
2519         $return = '<div class="form-select defaultsnext">' . $selecthtml . '</div>';
2521         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, $warning, $defaultinfo, $query);
2522     }
2526 /**
2527  * Select multiple items from list
2528  *
2529  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2530  */
2531 class admin_setting_configmultiselect extends admin_setting_configselect {
2532     /**
2533      * Constructor
2534      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2535      * @param string $visiblename localised
2536      * @param string $description long localised info
2537      * @param array $defaultsetting array of selected items
2538      * @param array $choices array of $value=>$label for each list item
2539      */
2540     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2541         parent::__construct($name, $visiblename, $description, $defaultsetting, $choices);
2542     }
2544     /**
2545      * Returns the select setting(s)
2546      *
2547      * @return mixed null or array. Null if no settings else array of setting(s)
2548      */
2549     public function get_setting() {
2550         $result = $this->config_read($this->name);
2551         if (is_null($result)) {
2552             return NULL;
2553         }
2554         if ($result === '') {
2555             return array();
2556         }
2557         return explode(',', $result);
2558     }
2560     /**
2561      * Saves setting(s) provided through $data
2562      *
2563      * Potential bug in the works should anyone call with this function
2564      * using a vartype that is not an array
2565      *
2566      * @param array $data
2567      */
2568     public function write_setting($data) {
2569         if (!is_array($data)) {
2570             return ''; //ignore it
2571         }
2572         if (!$this->load_choices() or empty($this->choices)) {
2573             return '';
2574         }
2576         unset($data['xxxxx']);
2578         $save = array();
2579         foreach ($data as $value) {
2580             if (!array_key_exists($value, $this->choices)) {
2581                 continue; // ignore it
2582             }
2583             $save[] = $value;
2584         }
2586         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
2587     }
2589     /**
2590      * Is setting related to query text - used when searching
2591      *
2592      * @param string $query
2593      * @return bool true if related, false if not
2594      */
2595     public function is_related($query) {
2596         if (!$this->load_choices() or empty($this->choices)) {
2597             return false;
2598         }
2599         if (parent::is_related($query)) {
2600             return true;
2601         }
2603         $textlib = textlib_get_instance();
2604         foreach ($this->choices as $desc) {
2605             if (strpos($textlib->strtolower($desc), $query) !== false) {
2606                 return true;
2607             }
2608         }
2609         return false;
2610     }
2612     /**
2613      * Returns XHTML multi-select field
2614      *
2615      * @todo Add vartype handling to ensure $data is an array
2616      * @param array $data Array of values to select by default
2617      * @param string $query
2618      * @return string XHTML multi-select field
2619      */
2620     public function output_html($data, $query='') {
2621         if (!$this->load_choices() or empty($this->choices)) {
2622             return '';
2623         }
2624         $choices = $this->choices;
2625         $default = $this->get_defaultsetting();
2626         if (is_null($default)) {
2627             $default = array();
2628         }
2629         if (is_null($data)) {
2630             $data = array();
2631         }
2633         $defaults = array();
2634         $size = min(10, count($this->choices));
2635         $return = '<div class="form-select"><input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2636         $return .= '<select id="'.$this->get_id().'" name="'.$this->get_full_name().'[]" size="'.$size.'" multiple="multiple">';
2637         foreach ($this->choices as $key => $description) {
2638             if (in_array($key, $data)) {
2639                 $selected = 'selected="selected"';
2640             } else {
2641                 $selected = '';
2642             }
2643             if (in_array($key, $default)) {
2644                 $defaults[] = $description;
2645             }
2647             $return .= '<option value="'.s($key).'" '.$selected.'>'.$description.'</option>';
2648         }
2650         if (is_null($default)) {
2651             $defaultinfo = NULL;
2652         } if (!empty($defaults)) {
2653             $defaultinfo = implode(', ', $defaults);
2654         } else {
2655             $defaultinfo = get_string('none');
2656         }
2658         $return .= '</select></div>';
2659         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, '', $defaultinfo, $query);
2660     }
2663 /**
2664  * Time selector
2665  *
2666  * This is a liiitle bit messy. we're using two selects, but we're returning
2667  * them as an array named after $name (so we only use $name2 internally for the setting)
2668  *
2669  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2670  */
2671 class admin_setting_configtime extends admin_setting {
2672     /** @var string Used for setting second select (minutes) */
2673     public $name2;
2675     /**
2676      * Constructor
2677      * @param string $hoursname setting for hours
2678      * @param string $minutesname setting for hours
2679      * @param string $visiblename localised
2680      * @param string $description long localised info
2681      * @param array $defaultsetting array representing default time 'h'=>hours, 'm'=>minutes
2682      */
2683     public function __construct($hoursname, $minutesname, $visiblename, $description, $defaultsetting) {
2684         $this->name2 = $minutesname;
2685         parent::__construct($hoursname, $visiblename, $description, $defaultsetting);
2686     }
2688     /**
2689      * Get the selected time
2690      *
2691      * @return mixed An array containing 'h'=>xx, 'm'=>xx, or null if not set
2692      */
2693     public function get_setting() {
2694         $result1 = $this->config_read($this->name);
2695         $result2 = $this->config_read($this->name2);
2696         if (is_null($result1) or is_null($result2)) {
2697             return NULL;
2698         }
2700         return array('h' => $result1, 'm' => $result2);
2701     }
2703     /**
2704      * Store the time (hours and minutes)
2705      *
2706      * @param array $data Must be form 'h'=>xx, 'm'=>xx
2707      * @return bool true if success, false if not
2708      */
2709     public function write_setting($data) {
2710         if (!is_array($data)) {
2711             return '';
2712         }
2714         $result = $this->config_write($this->name, (int)$data['h']) && $this->config_write($this->name2, (int)$data['m']);
2715         return ($result ? '' : get_string('errorsetting', 'admin'));
2716     }
2718     /**
2719      * Returns XHTML time select fields
2720      *
2721      * @param array $data Must be form 'h'=>xx, 'm'=>xx
2722      * @param string $query
2723      * @return string XHTML time select fields and wrapping div(s)
2724      */
2725     public function output_html($data, $query='') {
2726         $default = $this->get_defaultsetting();
2728         if (is_array($default)) {
2729             $defaultinfo = $default['h'].':'.$default['m'];
2730         } else {
2731             $defaultinfo = NULL;
2732         }
2734         $return = '<div class="form-time defaultsnext">'.
2735             '<select id="'.$this->get_id().'h" name="'.$this->get_full_name().'[h]">';
2736         for ($i = 0; $i < 24; $i++) {
2737             $return .= '<option value="'.$i.'"'.($i == $data['h'] ? ' selected="selected"' : '').'>'.$i.'</option>';
2738         }
2739         $return .= '</select>:<select id="'.$this->get_id().'m" name="'.$this->get_full_name().'[m]">';
2740         for ($i = 0; $i < 60; $i += 5) {
2741             $return .= '<option value="'.$i.'"'.($i == $data['m'] ? ' selected="selected"' : '').'>'.$i.'</option>';
2742         }
2743         $return .= '</select></div>';
2744         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
2745     }
2750 /**
2751  * Used to validate a textarea used for ip addresses
2752  *
2753  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2754  */
2755 class admin_setting_configiplist extends admin_setting_configtextarea {
2757     /**
2758      * Validate the contents of the textarea as IP addresses
2759      *
2760      * Used to validate a new line separated list of IP addresses collected from
2761      * a textarea control
2762      *
2763      * @param string $data A list of IP Addresses separated by new lines
2764      * @return mixed bool true for success or string:error on failure
2765      */
2766     public function validate($data) {
2767         if(!empty($data)) {
2768             $ips = explode("\n", $data);
2769         } else {
2770             return true;
2771         }
2772         $result = true;
2773         foreach($ips as $ip) {
2774             $ip = trim($ip);
2775             if (preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}$#', $ip, $match) ||
2776                 preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}(\/\d{1,2})$#', $ip, $match) ||
2777                 preg_match('#^(\d{1,3})(\.\d{1,3}){3}(-\d{1,3})$#', $ip, $match)) {
2778                 $result = true;
2779             } else {
2780                 $result = false;
2781                 break;
2782             }
2783         }
2784         if($result) {
2785             return true;
2786         } else {
2787             return get_string('validateerror', 'admin');
2788         }
2789     }
2793 /**
2794  * An admin setting for selecting one or more users who have a capability
2795  * in the system context
2796  *
2797  * An admin setting for selecting one or more users, who have a particular capability
2798  * in the system context. Warning, make sure the list will never be too long. There is
2799  * no paging or searching of this list.
2800  *
2801  * To correctly get a list of users from this config setting, you need to call the
2802  * get_users_from_config($CFG->mysetting, $capability); function in moodlelib.php.
2803  *
2804  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2805  */
2806 class admin_setting_users_with_capability extends admin_setting_configmultiselect {
2807     /** @var string The capabilities name */
2808     protected $capability;
2809     /** @var int include admin users too */
2810     protected $includeadmins;
2812     /**
2813      * Constructor.
2814      *
2815      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2816      * @param string $visiblename localised name
2817      * @param string $description localised long description
2818      * @param array $defaultsetting array of usernames
2819      * @param string $capability string capability name.
2820      * @param bool $includeadmins include administrators
2821      */
2822     function __construct($name, $visiblename, $description, $defaultsetting, $capability, $includeadmins = true) {
2823         $this->capability    = $capability;
2824         $this->includeadmins = $includeadmins;
2825         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
2826     }
2828     /**
2829      * Load all of the uses who have the capability into choice array
2830      *
2831      * @return bool Always returns true
2832      */
2833     function load_choices() {
2834         if (is_array($this->choices)) {
2835             return true;
2836         }
2837         $users = get_users_by_capability(get_context_instance(CONTEXT_SYSTEM),
2838             $this->capability, 'u.id,u.username,u.firstname,u.lastname', 'u.lastname,u.firstname');
2839         $this->choices = array(
2840             '$@NONE@$' => get_string('nobody'),
2841             '$@ALL@$' => get_string('everyonewhocan', 'admin', get_capability_string($this->capability)),
2842         );
2843         if ($this->includeadmins) {
2844             $admins = get_admins();
2845             foreach ($admins as $user) {
2846                 $this->choices[$user->id] = fullname($user);
2847             }
2848         }
2849         if (is_array($users)) {
2850             foreach ($users as $user) {
2851                 $this->choices[$user->id] = fullname($user);
2852             }
2853         }
2854         return true;
2855     }
2857     /**
2858      * Returns the default setting for class
2859      *
2860      * @return mixed Array, or string. Empty string if no default
2861      */
2862     public function get_defaultsetting() {
2863         $this->load_choices();
2864         $defaultsetting = parent::get_defaultsetting();
2865         if (empty($defaultsetting)) {
2866             return array('$@NONE@$');
2867         } else if (array_key_exists($defaultsetting, $this->choices)) {
2868                 return $defaultsetting;
2869             } else {
2870                 return '';
2871             }
2872     }
2874     /**
2875      * Returns the current setting
2876      *
2877      * @return mixed array or string
2878      */
2879     public function get_setting() {
2880         $result = parent::get_setting();
2881         if ($result === null) {
2882             // this is necessary for settings upgrade
2883             return null;
2884         }
2885         if (empty($result)) {
2886             $result = array('$@NONE@$');
2887         }
2888         return $result;
2889     }
2891     /**
2892      * Save the chosen setting provided as $data
2893      *
2894      * @param array $data
2895      * @return mixed string or array
2896      */
2897     public function write_setting($data) {
2898     // If all is selected, remove any explicit options.
2899         if (in_array('$@ALL@$', $data)) {
2900             $data = array('$@ALL@$');
2901         }
2902         // None never needs to be written to the DB.
2903         if (in_array('$@NONE@$', $data)) {
2904             unset($data[array_search('$@NONE@$', $data)]);
2905         }
2906         return parent::write_setting($data);
2907     }
2911 /**
2912  * Special checkbox for calendar - resets SESSION vars.
2913  *
2914  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2915  */
2916 class admin_setting_special_adminseesall extends admin_setting_configcheckbox {
2917     /**
2918      * Calls the parent::__construct with default values
2919      *
2920      * name =>  calendar_adminseesall
2921      * visiblename => get_string('adminseesall', 'admin')
2922      * description => get_string('helpadminseesall', 'admin')
2923      * defaultsetting => 0
2924      */
2925     public function __construct() {
2926         parent::__construct('calendar_adminseesall', get_string('adminseesall', 'admin'),
2927             get_string('helpadminseesall', 'admin'), '0');
2928     }
2930     /**
2931      * Stores the setting passed in $data
2932      *
2933      * @param mixed gets converted to string for comparison
2934      * @return string empty string or error message
2935      */
2936     public function write_setting($data) {
2937         global $SESSION;
2938         return parent::write_setting($data);
2939     }
2942 /**
2943  * Special select for settings that are altered in setup.php and can not be altered on the fly
2944  *
2945  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2946  */
2947 class admin_setting_special_selectsetup extends admin_setting_configselect {
2948     /**
2949      * Reads the setting directly from the database
2950      *
2951      * @return mixed
2952      */
2953     public function get_setting() {
2954     // read directly from db!
2955         return get_config(NULL, $this->name);
2956     }
2958     /**
2959      * Save the setting passed in $data
2960      *
2961      * @param string $data The setting to save
2962      * @return string empty or error message
2963      */
2964     public function write_setting($data) {
2965         global $CFG;
2966         // do not change active CFG setting!
2967         $current = $CFG->{$this->name};
2968         $result = parent::write_setting($data);
2969         $CFG->{$this->name} = $current;
2970         return $result;
2971     }
2975 /**
2976  * Special select for frontpage - stores data in course table
2977  *
2978  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2979  */
2980 class admin_setting_sitesetselect extends admin_setting_configselect {
2981     /**
2982      * Returns the site name for the selected site
2983      *
2984      * @see get_site()
2985      * @return string The site name of the selected site
2986      */
2987     public function get_setting() {
2988         $site = get_site();
2989         return $site->{$this->name};
2990     }
2992     /**
2993      * Updates the database and save the setting
2994      *
2995      * @param string data
2996      * @return string empty or error message
2997      */
2998     public function write_setting($data) {
2999         global $DB, $SITE;
3000         if (!in_array($data, array_keys($this->choices))) {
3001             return get_string('errorsetting', 'admin');
3002         }
3003         $record = new stdClass();
3004         $record->id           = SITEID;
3005         $temp                 = $this->name;
3006         $record->$temp        = $data;
3007         $record->timemodified = time();
3008         // update $SITE
3009         $SITE->{$this->name} = $data;
3010         return ($DB->update_record('course', $record) ? '' : get_string('errorsetting', 'admin'));
3011     }
3015 /**
3016  * Select for blog's bloglevel setting: if set to 0, will set blog_menu
3017  * block to hidden.
3018  *
3019  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3020  */
3021 class admin_setting_bloglevel extends admin_setting_configselect {
3022     /**
3023      * Updates the database and save the setting
3024      *
3025      * @param string data
3026      * @return string empty or error message
3027      */
3028     public function write_setting($data) {
3029         global $DB, $CFG;
3030         if ($data['bloglevel'] == 0) {
3031             $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 1");
3032             foreach ($blogblocks as $block) {
3033                 $DB->set_field('block', 'visible', 0, array('id' => $block->id));
3034             }
3035         } else {
3036             // reenable all blocks only when switching from disabled blogs
3037             if (isset($CFG->bloglevel) and $CFG->bloglevel == 0) {
3038                 $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 0");
3039                 foreach ($blogblocks as $block) {
3040                     $DB->set_field('block', 'visible', 1, array('id' => $block->id));
3041                 }
3042             }
3043         }
3044         return parent::write_setting($data);
3045     }
3049 /**
3050  * Special select - lists on the frontpage - hacky
3051  *
3052  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3053  */
3054 class admin_setting_courselist_frontpage extends admin_setting {
3055     /** @var array Array of choices value=>label */
3056     public $choices;
3058     /**
3059      * Construct override, requires one param
3060      *
3061      * @param bool $loggedin Is the user logged in
3062      */
3063     public function __construct($loggedin) {
3064         global $CFG;
3065         require_once($CFG->dirroot.'/course/lib.php');
3066         $name        = 'frontpage'.($loggedin ? 'loggedin' : '');
3067         $visiblename = get_string('frontpage'.($loggedin ? 'loggedin' : ''),'admin');
3068         $description = get_string('configfrontpage'.($loggedin ? 'loggedin' : ''),'admin');
3069         $defaults    = array(FRONTPAGECOURSELIST);
3070         parent::__construct($name, $visiblename, $description, $defaults);
3071     }
3073     /**
3074      * Loads the choices available
3075      *
3076      * @return bool always returns true
3077      */
3078     public function load_choices() {
3079         global $DB;
3080         if (is_array($this->choices)) {
3081             return true;
3082         }
3083         $this->choices = array(FRONTPAGENEWS          => get_string('frontpagenews'),
3084             FRONTPAGECOURSELIST    => get_string('frontpagecourselist'),
3085             FRONTPAGECATEGORYNAMES => get_string('frontpagecategorynames'),
3086             FRONTPAGECATEGORYCOMBO => get_string('frontpagecategorycombo'),
3087             'none'                 => get_string('none'));
3088         if ($this->name == 'frontpage' and $DB->count_records('course') > FRONTPAGECOURSELIMIT) {
3089             unset($this->choices[FRONTPAGECOURSELIST]);
3090         }
3091         return true;
3092     }
3094     /**
3095      * Returns the selected settings
3096      *
3097      * @param mixed array or setting or null
3098      */
3099     public function get_setting() {
3100         $result = $this->config_read($this->name);
3101         if (is_null($result)) {
3102             return NULL;
3103         }
3104         if ($result === '') {
3105             return array();
3106         }
3107         return explode(',', $result);
3108     }
3110     /**
3111      * Save the selected options
3112      *
3113      * @param array $data
3114      * @return mixed empty string (data is not an array) or bool true=success false=failure
3115      */
3116     public function write_setting($data) {
3117         if (!is_array($data)) {
3118             return '';
3119         }
3120         $this->load_choices();
3121         $save = array();
3122         foreach($data as $datum) {
3123             if ($datum == 'none' or !array_key_exists($datum, $this->choices)) {
3124                 continue;
3125             }
3126             $save[$datum] = $datum; // no duplicates
3127         }
3128         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
3129     }
3131     /**
3132      * Return XHTML select field and wrapping div
3133      *
3134      * @todo Add vartype handling to make sure $data is an array
3135      * @param array $data Array of elements to select by default
3136      * @return string XHTML select field and wrapping div
3137      */
3138     public function output_html($data, $query='') {
3139         $this->load_choices();
3140         $currentsetting = array();
3141         foreach ($data as $key) {
3142             if ($key != 'none' and array_key_exists($key, $this->choices)) {
3143                 $currentsetting[] = $key; // already selected first
3144             }
3145         }
3147         $return = '<div class="form-group">';
3148         for ($i = 0; $i < count($this->choices) - 1; $i++) {
3149             if (!array_key_exists($i, $currentsetting)) {
3150                 $currentsetting[$i] = 'none'; //none
3151             }
3152             $return .='<select class="form-select" id="'.$this->get_id().$i.'" name="'.$this->get_full_name().'[]">';
3153             foreach ($this->choices as $key => $value) {
3154                 $return .= '<option value="'.$key.'"'.("$key" == $currentsetting[$i] ? ' selected="selected"' : '').'>'.$value.'</option>';
3155             }
3156             $return .= '</select>';
3157             if ($i !== count($this->choices) - 2) {
3158                 $return .= '<br />';
3159             }
3160         }
3161         $return .= '</div>';
3163         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
3164     }
3168 /**
3169  * Special checkbox for frontpage - stores data in course table
3170  *
3171  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3172  */
3173 class admin_setting_sitesetcheckbox extends admin_setting_configcheckbox {
3174     /**
3175      * Returns the current sites name
3176      *
3177      * @return string
3178      */
3179     public function get_setting() {
3180         $site = get_site();
3181         return $site->{$this->name};
3182     }
3184     /**
3185      * Save the selected setting
3186      *
3187      * @param string $data The selected site
3188      * @return string empty string or error message
3189      */
3190     public function write_setting($data) {
3191         global $DB, $SITE;
3192         $record = new stdClass();
3193         $record->id            = SITEID;
3194         $record->{$this->name} = ($data == '1' ? 1 : 0);
3195         $record->timemodified  = time();
3196         // update $SITE
3197         $SITE->{$this->name} = $data;
3198         return ($DB->update_record('course', $record) ? '' : get_string('errorsetting', 'admin'));
3199     }
3202 /**
3203  * Special text for frontpage - stores data in course table.
3204  * Empty string means not set here. Manual setting is required.
3205  *
3206  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3207  */
3208 class admin_setting_sitesettext extends admin_setting_configtext {
3209     /**
3210      * Return the current setting
3211      *
3212      * @return mixed string or null
3213      */
3214     public function get_setting() {
3215         $site = get_site();
3216         return $site->{$this->name} != '' ? $site->{$this->name} : NULL;
3217     }
3219     /**
3220      * Validate the selected data
3221      *
3222      * @param string $data The selected value to validate
3223      * @return mixed true or message string
3224      */
3225     public function validate($data) {
3226         $cleaned = clean_param($data, PARAM_MULTILANG);
3227         if ($cleaned === '') {
3228             return get_string('required');
3229         }
3230         if ("$data" == "$cleaned") { // implicit conversion to string is needed to do exact comparison
3231             return true;
3232         } else {
3233             return get_string('validateerror', 'admin');
3234         }
3235     }
3237     /**
3238      * Save the selected setting
3239      *
3240      * @param string $data The selected value
3241      * @return string empty or error message
3242      */
3243     public function write_setting($data) {
3244         global $DB, $SITE;
3245         $data = trim($data);
3246         $validated = $this->validate($data);
3247         if ($validated !== true) {
3248             return $validated;
3249         }
3251         $record = new stdClass();
3252         $record->id            = SITEID;
3253         $record->{$this->name} = $data;
3254         $record->timemodified  = time();
3255         // update $SITE
3256         $SITE->{$this->name} = $data;
3257         return ($DB->update_record('course', $record) ? '' : get_string('dbupdatefailed', 'error'));
3258     }
3262 /**
3263  * Special text editor for site description.
3264  *
3265  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3266  */
3267 class admin_setting_special_frontpagedesc extends admin_setting {
3268     /**
3269      * Calls parent::__construct with specific arguments
3270      */
3271     public function __construct() {
3272         parent::__construct('summary', get_string('frontpagedescription'), get_string('frontpagedescriptionhelp'), NULL);
3273         editors_head_setup();
3274     }
3276     /**
3277      * Return the current setting
3278      * @return string The current setting
3279      */
3280     public function get_setting() {
3281         $site = get_site();
3282         return $site->{$this->name};
3283     }
3285     /**
3286      * Save the new setting
3287      *
3288      * @param string $data The new value to save
3289      * @return string empty or error message
3290      */
3291     public function write_setting($data) {
3292         global $DB, $SITE;
3293         $record = new stdClass();
3294         $record->id            = SITEID;
3295         $record->{$this->name} = $data;
3296         $record->timemodified  = time();
3297         $SITE->{$this->name} = $data;
3298         return ($DB->update_record('course', $record) ? '' : get_string('errorsetting', 'admin'));
3299     }
3301     /**
3302      * Returns XHTML for the field plus wrapping div
3303      *
3304      * @param string $data The current value
3305      * @param string $query
3306      * @return string The XHTML output
3307      */
3308     public function output_html($data, $query='') {
3309         global $CFG;
3311         $CFG->adminusehtmleditor = can_use_html_editor();
3312         $return = '<div class="form-htmlarea">'.print_textarea($CFG->adminusehtmleditor, 15, 60, 0, 0, $this->get_full_name(), $data, 0, true, 'summary') .'</div>';
3314         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
3315     }
3319 /**
3320  * Administration interface for emoticon_manager settings.
3321  *
3322  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3323  */
3324 class admin_setting_emoticons extends admin_setting {
3326     /**
3327      * Calls parent::__construct with specific args
3328      */
3329     public function __construct() {
3330         global $CFG;
3332         $manager = get_emoticon_manager();
3333         $defaults = $this->prepare_form_data($manager->default_emoticons());
3334         parent::__construct('emoticons', get_string('emoticons', 'admin'), get_string('emoticons_desc', 'admin'), $defaults);
3335     }
3337     /**
3338      * Return the current setting(s)
3339      *
3340      * @return array Current settings array
3341      */
3342     public function get_setting() {
3343         global $CFG;
3345         $manager = get_emoticon_manager();
3347         $config = $this->config_read($this->name);
3348         if (is_null($config)) {
3349             return null;
3350         }
3352         $config = $manager->decode_stored_config($config);
3353         if (is_null($config)) {
3354             return null;
3355         }
3357         return $this->prepare_form_data($config);
3358     }
3360     /**
3361      * Save selected settings
3362      *
3363      * @param array $data Array of settings to save
3364      * @return bool
3365      */
3366     public function write_setting($data) {
3368         $manager = get_emoticon_manager();
3369         $emoticons = $this->process_form_data($data);
3371         if ($emoticons === false) {
3372             return false;
3373         }
3375         if ($this->config_write($this->name, $manager->encode_stored_config($emoticons))) {
3376             return ''; // success
3377         } else {
3378             return get_string('errorsetting', 'admin') . $this->visiblename . html_writer::empty_tag('br');
3379         }
3380     }
3382     /**
3383      * Return XHTML field(s) for options
3384      *
3385      * @param array $data Array of options to set in HTML
3386      * @return string XHTML string for the fields and wrapping div(s)
3387      */
3388     public function output_html($data, $query='') {
3389         global $OUTPUT;
3391         $out  = html_writer::start_tag('table', array('border' => 1, 'class' => 'generaltable'));
3392         $out .= html_writer::start_tag('thead');
3393         $out .= html_writer::start_tag('tr');
3394         $out .= html_writer::tag('th', get_string('emoticontext', 'admin'));
3395         $out .= html_writer::tag('th', get_string('emoticonimagename', 'admin'));
3396         $out .= html_writer::tag('th', get_string('emoticoncomponent', 'admin'));
3397         $out .= html_writer::tag('th', get_string('emoticonalt', 'admin'), array('colspan' => 2));
3398         $out .= html_writer::tag('th', '');
3399         $out .= html_writer::end_tag('tr');
3400         $out .= html_writer::end_tag('thead');
3401         $out .= html_writer::start_tag('tbody');
3402         $i = 0;
3403         foreach($data as $field => $value) {
3404             switch ($i) {
3405             case 0:
3406                 $out .= html_writer::start_tag('tr');
3407                 $current_text = $value;
3408                 $current_filename = '';
3409                 $current_imagecomponent = '';
3410                 $current_altidentifier = '';
3411                 $current_altcomponent = '';
3412             case 1:
3413                 $current_filename = $value;
3414             case 2:
3415                 $current_imagecomponent = $value;
3416             case 3:
3417                 $current_altidentifier = $value;
3418             case 4:
3419                 $current_altcomponent = $value;
3420             }
3422             $out .= html_writer::tag('td',
3423                 html_writer::empty_tag('input',
3424                     array(
3425                         'type'  => 'text',
3426                         'class' => 'form-text',
3427                         'name'  => $this->get_full_name().'['.$field.']',
3428                         'value' => $value,
3429                     )
3430                 ), array('class' => 'c'.$i)
3431             );
3433             if ($i == 4) {
3434                 if (get_string_manager()->string_exists($current_altidentifier, $current_altcomponent)) {
3435                     $alt = get_string($current_altidentifier, $current_altcomponent);
3436                 } else {
3437                     $alt = $current_text;
3438                 }
3439                 if ($current_filename) {
3440                     $out .= html_writer::tag('td', $OUTPUT->render(new pix_emoticon($current_filename, $alt, $current_imagecomponent)));
3441                 } else {
3442                     $out .= html_writer::tag('td', '');
3443                 }
3444                 $out .= html_writer::end_tag('tr');
3445                 $i = 0;
3446             } else {
3447                 $i++;
3448             }
3450         }
3451         $out .= html_writer::end_tag('tbody');
3452         $out .= html_writer::end_tag('table');
3453         $out  = html_writer::tag('div', $out, array('class' => 'form-group'));
3454         $out .= html_writer::tag('div', html_writer::link(new moodle_url('/admin/resetemoticons.php'), get_string('emoticonsreset', 'admin')));
3456         return format_admin_setting($this, $this->visiblename, $out, $this->description, false, '', NULL, $query);
3457     }
3459     /**
3460      * Converts the array of emoticon objects provided by {@see emoticon_manager} into admin settings form data
3461      *
3462      * @see self::process_form_data()
3463      * @param array $emoticons array of emoticon objects as returned by {@see emoticon_manager}
3464      * @return array of form fields and their values
3465      */
3466     protected function prepare_form_data(array $emoticons) {
3468         $form = array();
3469         $i = 0;
3470         foreach ($emoticons as $emoticon) {
3471             $form['text'.$i]            = $emoticon->text;
3472             $form['imagename'.$i]       = $emoticon->imagename;
3473             $form['imagecomponent'.$i]  = $emoticon->imagecomponent;
3474             $form['altidentifier'.$i]   = $emoticon->altidentifier;
3475             $form['altcomponent'.$i]    = $emoticon->altcomponent;
3476             $i++;
3477         }
3478         // add one more blank field set for new object
3479         $form['text'.$i]            = '';
3480         $form['imagename'.$i]       = '';
3481         $form['imagecomponent'.$i]  = '';
3482         $form['altidentifier'.$i]   = '';
3483         $form['altcomponent'.$i]    = '';
3485         return $form;
3486     }
3488     /**
3489      * Converts the data from admin settings form into an array of emoticon objects
3490      *
3491      * @see self::prepare_form_data()
3492      * @param array $data array of admin form fields and values
3493      * @return false|array of emoticon objects
3494      */
3495     protected function process_form_data(array $form) {
3497         $count = count($form); // number of form field values
3499         if ($count % 5) {
3500             // we must get five fields per emoticon object
3501             return false;
3502         }
3504         $emoticons = array();
3505         for ($i = 0; $i < $count / 5; $i++) {
3506             $emoticon                   = new stdClass();
3507             $emoticon->text             = clean_param(trim($form['text'.$i]), PARAM_NOTAGS);
3508             $emoticon->imagename        = clean_param(trim($form['imagename'.$i]), PARAM_PATH);
3509             $emoticon->imagecomponent   = clean_param(trim($form['imagecomponent'.$i]), PARAM_SAFEDIR);
3510             $emoticon->altidentifier    = clean_param(trim($form['altidentifier'.$i]), PARAM_STRINGID);
3511             $emoticon->altcomponent     = clean_param(trim($form['altcomponent'.$i]), PARAM_SAFEDIR);
3513             if (strpos($emoticon->text, ':/') !== false or strpos($emoticon->text, '//') !== false) {
3514                 // prevent from breaking http://url.addresses by accident
3515                 $emoticon->text = '';
3516             }
3518             if (strlen($emoticon->text) < 2) {
3519                 // do not allow single character emoticons
3520                 $emoticon->text = '';
3521             }
3523             if (preg_match('/^[a-zA-Z]+[a-zA-Z0-9]*$/', $emoticon->text)) {
3524                 // emoticon text must contain some non-alphanumeric character to prevent
3525                 // breaking HTML tags
3526                 $emoticon->text = '';
3527             }
3529             if ($emoticon->text !== '' and $emoticon->imagename !== '' and $emoticon->imagecomponent !== '') {
3530                 $emoticons[] = $emoticon;
3531             }
3532         }
3533         return $emoticons;
3534     }
3538 /**
3539  * Special setting for limiting of the list of available languages.
3540  *
3541  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3542  */
3543 class admin_setting_langlist extends admin_setting_configtext {
3544     /**
3545      * Calls parent::__construct with specific arguments
3546      */
3547     public function __construct() {
3548         parent::__construct('langlist', get_string('langlist', 'admin'), get_string('configlanglist', 'admin'), '', PARAM_NOTAGS);
3549     }
3551     /**
3552      * Save the new setting
3553      *
3554      * @param string $data The new setting
3555      * @return bool
3556      */
3557     public function write_setting($data) {
3558         $return = parent::write_setting($data);
3559         get_string_manager()->reset_caches();
3560         return $return;
3561     }
3565 /**
3566  * Selection of one of the recognised countries using the list
3567  * returned by {@link get_list_of_countries()}.
3568  *
3569  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3570  */
3571 class admin_settings_country_select extends admin_setting_configselect {
3572     protected $includeall;
3573     public function __construct($name, $visiblename, $description, $defaultsetting, $includeall=false) {
3574         $this->includeall = $includeall;
3575         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
3576     }
3578     /**
3579      * Lazy-load the available choices for the select box
3580      */
3581     public function load_choices() {
3582         global $CFG;
3583         if (is_array($this->choices)) {
3584             return true;
3585         }
3586         $this->choices = array_merge(
3587                 array('0' => get_string('choosedots')),
3588                 get_string_manager()->get_list_of_countries($this->includeall));
3589         return true;
3590     }
3594 /**
3595  * admin_setting_configselect for the default number of sections in a course,
3596  * simply so we can lazy-load the choices.
3597  *
3598  * @copyright 2011 The Open University
3599  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3600  */
3601 class admin_settings_num_course_sections extends admin_setting_configselect {
3602     public function __construct($name, $visiblename, $description, $defaultsetting) {
3603         parent::__construct($name, $visiblename, $description, $defaultsetting, array());
3604     }
3606     /** Lazy-load the available choices for the select box */
3607     public function load_choices() {
3608         $max = get_config('moodlecourse', 'maxsections');
3609         if (empty($max)) {
3610             $max = 52;
3611         }
3612         for ($i = 0; $i <= $max; $i++) {
3613             $this->choices[$i] = "$i";
3614         }
3615         return true;
3616     }
3620 /**
3621  * Course category selection
3622  *
3623  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3624  */
3625 class admin_settings_coursecat_select extends admin_setting_configselect {
3626     /**
3627      * Calls parent::__construct with specific arguments
3628      */
3629     public function __construct($name, $visiblename, $description, $defaultsetting) {
3630         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
3631     }
3633     /**
3634      * Load the available choices for the select box
3635      *
3636      * @return bool
3637      */
3638     public function load_choices() {
3639         global $CFG;
3640         require_once($CFG->dirroot.'/course/lib.php');
3641         if (is_array($this->choices)) {
3642             return true;
3643         }
3644         $this->choices = make_categories_options();
3645         return true;
3646     }
3650 /**
3651  * Special control for selecting days to backup
3652  *
3653  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3654  */
3655 class admin_setting_special_backupdays extends admin_setting_configmulticheckbox2 {
3656     /**
3657      * Calls parent::__construct with specific arguments
3658      */
3659     public function __construct() {
3660         parent::__construct('backup_auto_weekdays', get_string('automatedbackupschedule','backup'), get_string('automatedbackupschedulehelp','backup'), array(), NULL);
3661         $this->plugin = 'backup';
3662     }
3664     /**
3665      * Load the available choices for the select box
3666      *
3667      * @return bool Always returns true
3668      */
3669     public function load_choices() {
3670         if (is_array($this->choices)) {
3671             return true;
3672         }
3673         $this->choices = array();
3674         $days = array('sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday');
3675         foreach ($days as $day) {
3676             $this->choices[$day] = get_string($day, 'calendar');
3677         }
3678         return true;