857d3d1dd21acd29217c02e3eecad5546a182647
[moodle.git] / lib / adminlib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Functions and classes used during installation, upgrades and for admin settings.
19  *
20  *  ADMIN SETTINGS TREE INTRODUCTION
21  *
22  *  This file performs the following tasks:
23  *   -it defines the necessary objects and interfaces to build the Moodle
24  *    admin hierarchy
25  *   -it defines the admin_externalpage_setup()
26  *
27  *  ADMIN_SETTING OBJECTS
28  *
29  *  Moodle settings are represented by objects that inherit from the admin_setting
30  *  class. These objects encapsulate how to read a setting, how to write a new value
31  *  to a setting, and how to appropriately display the HTML to modify the setting.
32  *
33  *  ADMIN_SETTINGPAGE OBJECTS
34  *
35  *  The admin_setting objects are then grouped into admin_settingpages. The latter
36  *  appear in the Moodle admin tree block. All interaction with admin_settingpage
37  *  objects is handled by the admin/settings.php file.
38  *
39  *  ADMIN_EXTERNALPAGE OBJECTS
40  *
41  *  There are some settings in Moodle that are too complex to (efficiently) handle
42  *  with admin_settingpages. (Consider, for example, user management and displaying
43  *  lists of users.) In this case, we use the admin_externalpage object. This object
44  *  places a link to an external PHP file in the admin tree block.
45  *
46  *  If you're using an admin_externalpage object for some settings, you can take
47  *  advantage of the admin_externalpage_* functions. For example, suppose you wanted
48  *  to add a foo.php file into admin. First off, you add the following line to
49  *  admin/settings/first.php (at the end of the file) or to some other file in
50  *  admin/settings:
51  * <code>
52  *     $ADMIN->add('userinterface', new admin_externalpage('foo', get_string('foo'),
53  *         $CFG->wwwdir . '/' . '$CFG->admin . '/foo.php', 'some_role_permission'));
54  * </code>
55  *
56  *  Next, in foo.php, your file structure would resemble the following:
57  * <code>
58  *         require(dirname(dirname(dirname(__FILE__))).'/config.php');
59  *         require_once($CFG->libdir.'/adminlib.php');
60  *         admin_externalpage_setup('foo');
61  *         // functionality like processing form submissions goes here
62  *         echo $OUTPUT->header();
63  *         // your HTML goes here
64  *         echo $OUTPUT->footer();
65  * </code>
66  *
67  *  The admin_externalpage_setup() function call ensures the user is logged in,
68  *  and makes sure that they have the proper role permission to access the page.
69  *  It also configures all $PAGE properties needed for navigation.
70  *
71  *  ADMIN_CATEGORY OBJECTS
72  *
73  *  Above and beyond all this, we have admin_category objects. These objects
74  *  appear as folders in the admin tree block. They contain admin_settingpage's,
75  *  admin_externalpage's, and other admin_category's.
76  *
77  *  OTHER NOTES
78  *
79  *  admin_settingpage's, admin_externalpage's, and admin_category's all inherit
80  *  from part_of_admin_tree (a pseudointerface). This interface insists that
81  *  a class has a check_access method for access permissions, a locate method
82  *  used to find a specific node in the admin tree and find parent path.
83  *
84  *  admin_category's inherit from parentable_part_of_admin_tree. This pseudo-
85  *  interface ensures that the class implements a recursive add function which
86  *  accepts a part_of_admin_tree object and searches for the proper place to
87  *  put it. parentable_part_of_admin_tree implies part_of_admin_tree.
88  *
89  *  Please note that the $this->name field of any part_of_admin_tree must be
90  *  UNIQUE throughout the ENTIRE admin tree.
91  *
92  *  The $this->name field of an admin_setting object (which is *not* part_of_
93  *  admin_tree) must be unique on the respective admin_settingpage where it is
94  *  used.
95  *
96  * Original author: Vincenzo K. Marcovecchio
97  * Maintainer:      Petr Skoda
98  *
99  * @package    core
100  * @subpackage admin
101  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
102  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
103  */
105 defined('MOODLE_INTERNAL') || die();
107 /// Add libraries
108 require_once($CFG->libdir.'/ddllib.php');
109 require_once($CFG->libdir.'/xmlize.php');
110 require_once($CFG->libdir.'/messagelib.php');
112 define('INSECURE_DATAROOT_WARNING', 1);
113 define('INSECURE_DATAROOT_ERROR', 2);
115 /**
116  * Automatically clean-up all plugin data and remove the plugin DB tables
117  *
118  * NOTE: do not call directly, use new /admin/plugins.php?uninstall=component instead!
119  *
120  * @param string $type The plugin type, eg. 'mod', 'qtype', 'workshopgrading' etc.
121  * @param string $name The plugin name, eg. 'forum', 'multichoice', 'accumulative' etc.
122  * @uses global $OUTPUT to produce notices and other messages
123  * @return void
124  */
125 function uninstall_plugin($type, $name) {
126     global $CFG, $DB, $OUTPUT;
127     require_once($CFG->libdir.'/pluginlib.php');
129     // This may take a long time.
130     @set_time_limit(0);
132     // Recursively uninstall all subplugins first.
133     $subplugintypes = core_component::get_plugin_types_with_subplugins();
134     if (isset($subplugintypes[$type])) {
135         $base = core_component::get_plugin_directory($type, $name);
136         if (file_exists("$base/db/subplugins.php")) {
137             $subplugins = array();
138             include("$base/db/subplugins.php");
139             foreach ($subplugins as $subplugintype=>$dir) {
140                 $instances = core_component::get_plugin_list($subplugintype);
141                 foreach ($instances as $subpluginname => $notusedpluginpath) {
142                     uninstall_plugin($subplugintype, $subpluginname);
143                 }
144             }
145         }
147     }
149     $component = $type . '_' . $name;  // eg. 'qtype_multichoice' or 'workshopgrading_accumulative' or 'mod_forum'
151     if ($type === 'mod') {
152         $pluginname = $name;  // eg. 'forum'
153         if (get_string_manager()->string_exists('modulename', $component)) {
154             $strpluginname = get_string('modulename', $component);
155         } else {
156             $strpluginname = $component;
157         }
159     } else {
160         $pluginname = $component;
161         if (get_string_manager()->string_exists('pluginname', $component)) {
162             $strpluginname = get_string('pluginname', $component);
163         } else {
164             $strpluginname = $component;
165         }
166     }
168     echo $OUTPUT->heading($pluginname);
170     // Custom plugin uninstall.
171     $plugindirectory = core_component::get_plugin_directory($type, $name);
172     $uninstalllib = $plugindirectory . '/db/uninstall.php';
173     if (file_exists($uninstalllib)) {
174         require_once($uninstalllib);
175         $uninstallfunction = 'xmldb_' . $pluginname . '_uninstall';    // eg. 'xmldb_workshop_uninstall()'
176         if (function_exists($uninstallfunction)) {
177             // Do not verify result, let plugin complain if necessary.
178             $uninstallfunction();
179         }
180     }
182     // Specific plugin type cleanup.
183     $plugininfo = plugin_manager::instance()->get_plugin_info($component);
184     if ($plugininfo) {
185         $plugininfo->uninstall_cleanup();
186         plugin_manager::reset_caches();
187     }
188     $plugininfo = null;
190     // perform clean-up task common for all the plugin/subplugin types
192     //delete the web service functions and pre-built services
193     require_once($CFG->dirroot.'/lib/externallib.php');
194     external_delete_descriptions($component);
196     // delete calendar events
197     $DB->delete_records('event', array('modulename' => $pluginname));
199     // delete all the logs
200     $DB->delete_records('log', array('module' => $pluginname));
202     // delete log_display information
203     $DB->delete_records('log_display', array('component' => $component));
205     // delete the module configuration records
206     unset_all_config_for_plugin($component);
207     if ($type === 'mod') {
208         unset_all_config_for_plugin($pluginname);
209     }
211     // delete message provider
212     message_provider_uninstall($component);
214     // delete the plugin tables
215     $xmldbfilepath = $plugindirectory . '/db/install.xml';
216     drop_plugin_tables($component, $xmldbfilepath, false);
217     if ($type === 'mod' or $type === 'block') {
218         // non-frankenstyle table prefixes
219         drop_plugin_tables($name, $xmldbfilepath, false);
220     }
222     // delete the capabilities that were defined by this module
223     capabilities_cleanup($component);
225     // remove event handlers and dequeue pending events
226     events_uninstall($component);
228     // Delete all remaining files in the filepool owned by the component.
229     $fs = get_file_storage();
230     $fs->delete_component_files($component);
232     // Finally purge all caches.
233     purge_all_caches();
235     // Invalidate the hash used for upgrade detections.
236     set_config('allversionshash', '');
238     echo $OUTPUT->notification(get_string('success'), 'notifysuccess');
241 /**
242  * Returns the version of installed component
243  *
244  * @param string $component component name
245  * @param string $source either 'disk' or 'installed' - where to get the version information from
246  * @return string|bool version number or false if the component is not found
247  */
248 function get_component_version($component, $source='installed') {
249     global $CFG, $DB;
251     list($type, $name) = core_component::normalize_component($component);
253     // moodle core or a core subsystem
254     if ($type === 'core') {
255         if ($source === 'installed') {
256             if (empty($CFG->version)) {
257                 return false;
258             } else {
259                 return $CFG->version;
260             }
261         } else {
262             if (!is_readable($CFG->dirroot.'/version.php')) {
263                 return false;
264             } else {
265                 $version = null; //initialize variable for IDEs
266                 include($CFG->dirroot.'/version.php');
267                 return $version;
268             }
269         }
270     }
272     // activity module
273     if ($type === 'mod') {
274         if ($source === 'installed') {
275             if ($CFG->version < 2013092001.02) {
276                 return $DB->get_field('modules', 'version', array('name'=>$name));
277             } else {
278                 return get_config('mod_'.$name, 'version');
279             }
281         } else {
282             $mods = core_component::get_plugin_list('mod');
283             if (empty($mods[$name]) or !is_readable($mods[$name].'/version.php')) {
284                 return false;
285             } else {
286                 $plugin = new stdClass();
287                 $plugin->version = null;
288                 $module = $plugin;
289                 include($mods[$name].'/version.php');
290                 return $plugin->version;
291             }
292         }
293     }
295     // block
296     if ($type === 'block') {
297         if ($source === 'installed') {
298             return $DB->get_field('block', 'version', array('name'=>$name));
299         } else {
300             $blocks = core_component::get_plugin_list('block');
301             if (empty($blocks[$name]) or !is_readable($blocks[$name].'/version.php')) {
302                 return false;
303             } else {
304                 $plugin = new stdclass();
305                 include($blocks[$name].'/version.php');
306                 return $plugin->version;
307             }
308         }
309     }
311     // all other plugin types
312     if ($source === 'installed') {
313         return get_config($type.'_'.$name, 'version');
314     } else {
315         $plugins = core_component::get_plugin_list($type);
316         if (empty($plugins[$name])) {
317             return false;
318         } else {
319             $plugin = new stdclass();
320             include($plugins[$name].'/version.php');
321             return $plugin->version;
322         }
323     }
326 /**
327  * Delete all plugin tables
328  *
329  * @param string $name Name of plugin, used as table prefix
330  * @param string $file Path to install.xml file
331  * @param bool $feedback defaults to true
332  * @return bool Always returns true
333  */
334 function drop_plugin_tables($name, $file, $feedback=true) {
335     global $CFG, $DB;
337     // first try normal delete
338     if (file_exists($file) and $DB->get_manager()->delete_tables_from_xmldb_file($file)) {
339         return true;
340     }
342     // then try to find all tables that start with name and are not in any xml file
343     $used_tables = get_used_table_names();
345     $tables = $DB->get_tables();
347     /// Iterate over, fixing id fields as necessary
348     foreach ($tables as $table) {
349         if (in_array($table, $used_tables)) {
350             continue;
351         }
353         if (strpos($table, $name) !== 0) {
354             continue;
355         }
357         // found orphan table --> delete it
358         if ($DB->get_manager()->table_exists($table)) {
359             $xmldb_table = new xmldb_table($table);
360             $DB->get_manager()->drop_table($xmldb_table);
361         }
362     }
364     return true;
367 /**
368  * Returns names of all known tables == tables that moodle knows about.
369  *
370  * @return array Array of lowercase table names
371  */
372 function get_used_table_names() {
373     $table_names = array();
374     $dbdirs = get_db_directories();
376     foreach ($dbdirs as $dbdir) {
377         $file = $dbdir.'/install.xml';
379         $xmldb_file = new xmldb_file($file);
381         if (!$xmldb_file->fileExists()) {
382             continue;
383         }
385         $loaded    = $xmldb_file->loadXMLStructure();
386         $structure = $xmldb_file->getStructure();
388         if ($loaded and $tables = $structure->getTables()) {
389             foreach($tables as $table) {
390                 $table_names[] = strtolower($table->getName());
391             }
392         }
393     }
395     return $table_names;
398 /**
399  * Returns list of all directories where we expect install.xml files
400  * @return array Array of paths
401  */
402 function get_db_directories() {
403     global $CFG;
405     $dbdirs = array();
407     /// First, the main one (lib/db)
408     $dbdirs[] = $CFG->libdir.'/db';
410     /// Then, all the ones defined by core_component::get_plugin_types()
411     $plugintypes = core_component::get_plugin_types();
412     foreach ($plugintypes as $plugintype => $pluginbasedir) {
413         if ($plugins = core_component::get_plugin_list($plugintype)) {
414             foreach ($plugins as $plugin => $plugindir) {
415                 $dbdirs[] = $plugindir.'/db';
416             }
417         }
418     }
420     return $dbdirs;
423 /**
424  * Try to obtain or release the cron lock.
425  * @param string  $name  name of lock
426  * @param int  $until timestamp when this lock considered stale, null means remove lock unconditionally
427  * @param bool $ignorecurrent ignore current lock state, usually extend previous lock, defaults to false
428  * @return bool true if lock obtained
429  */
430 function set_cron_lock($name, $until, $ignorecurrent=false) {
431     global $DB;
432     if (empty($name)) {
433         debugging("Tried to get a cron lock for a null fieldname");
434         return false;
435     }
437     // remove lock by force == remove from config table
438     if (is_null($until)) {
439         set_config($name, null);
440         return true;
441     }
443     if (!$ignorecurrent) {
444         // read value from db - other processes might have changed it
445         $value = $DB->get_field('config', 'value', array('name'=>$name));
447         if ($value and $value > time()) {
448             //lock active
449             return false;
450         }
451     }
453     set_config($name, $until);
454     return true;
457 /**
458  * Test if and critical warnings are present
459  * @return bool
460  */
461 function admin_critical_warnings_present() {
462     global $SESSION;
464     if (!has_capability('moodle/site:config', context_system::instance())) {
465         return 0;
466     }
468     if (!isset($SESSION->admin_critical_warning)) {
469         $SESSION->admin_critical_warning = 0;
470         if (is_dataroot_insecure(true) === INSECURE_DATAROOT_ERROR) {
471             $SESSION->admin_critical_warning = 1;
472         }
473     }
475     return $SESSION->admin_critical_warning;
478 /**
479  * Detects if float supports at least 10 decimal digits
480  *
481  * Detects if float supports at least 10 decimal digits
482  * and also if float-->string conversion works as expected.
483  *
484  * @return bool true if problem found
485  */
486 function is_float_problem() {
487     $num1 = 2009010200.01;
488     $num2 = 2009010200.02;
490     return ((string)$num1 === (string)$num2 or $num1 === $num2 or $num2 <= (string)$num1);
493 /**
494  * Try to verify that dataroot is not accessible from web.
495  *
496  * Try to verify that dataroot is not accessible from web.
497  * It is not 100% correct but might help to reduce number of vulnerable sites.
498  * Protection from httpd.conf and .htaccess is not detected properly.
499  *
500  * @uses INSECURE_DATAROOT_WARNING
501  * @uses INSECURE_DATAROOT_ERROR
502  * @param bool $fetchtest try to test public access by fetching file, default false
503  * @return mixed empty means secure, INSECURE_DATAROOT_ERROR found a critical problem, INSECURE_DATAROOT_WARNING might be problematic
504  */
505 function is_dataroot_insecure($fetchtest=false) {
506     global $CFG;
508     $siteroot = str_replace('\\', '/', strrev($CFG->dirroot.'/')); // win32 backslash workaround
510     $rp = preg_replace('|https?://[^/]+|i', '', $CFG->wwwroot, 1);
511     $rp = strrev(trim($rp, '/'));
512     $rp = explode('/', $rp);
513     foreach($rp as $r) {
514         if (strpos($siteroot, '/'.$r.'/') === 0) {
515             $siteroot = substr($siteroot, strlen($r)+1); // moodle web in subdirectory
516         } else {
517             break; // probably alias root
518         }
519     }
521     $siteroot = strrev($siteroot);
522     $dataroot = str_replace('\\', '/', $CFG->dataroot.'/');
524     if (strpos($dataroot, $siteroot) !== 0) {
525         return false;
526     }
528     if (!$fetchtest) {
529         return INSECURE_DATAROOT_WARNING;
530     }
532     // now try all methods to fetch a test file using http protocol
534     $httpdocroot = str_replace('\\', '/', strrev($CFG->dirroot.'/'));
535     preg_match('|(https?://[^/]+)|i', $CFG->wwwroot, $matches);
536     $httpdocroot = $matches[1];
537     $datarooturl = $httpdocroot.'/'. substr($dataroot, strlen($siteroot));
538     make_upload_directory('diag');
539     $testfile = $CFG->dataroot.'/diag/public.txt';
540     if (!file_exists($testfile)) {
541         file_put_contents($testfile, 'test file, do not delete');
542         @chmod($testfile, $CFG->filepermissions);
543     }
544     $teststr = trim(file_get_contents($testfile));
545     if (empty($teststr)) {
546     // hmm, strange
547         return INSECURE_DATAROOT_WARNING;
548     }
550     $testurl = $datarooturl.'/diag/public.txt';
551     if (extension_loaded('curl') and
552         !(stripos(ini_get('disable_functions'), 'curl_init') !== FALSE) and
553         !(stripos(ini_get('disable_functions'), 'curl_setop') !== FALSE) and
554         ($ch = @curl_init($testurl)) !== false) {
555         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
556         curl_setopt($ch, CURLOPT_HEADER, false);
557         $data = curl_exec($ch);
558         if (!curl_errno($ch)) {
559             $data = trim($data);
560             if ($data === $teststr) {
561                 curl_close($ch);
562                 return INSECURE_DATAROOT_ERROR;
563             }
564         }
565         curl_close($ch);
566     }
568     if ($data = @file_get_contents($testurl)) {
569         $data = trim($data);
570         if ($data === $teststr) {
571             return INSECURE_DATAROOT_ERROR;
572         }
573     }
575     preg_match('|https?://([^/]+)|i', $testurl, $matches);
576     $sitename = $matches[1];
577     $error = 0;
578     if ($fp = @fsockopen($sitename, 80, $error)) {
579         preg_match('|https?://[^/]+(.*)|i', $testurl, $matches);
580         $localurl = $matches[1];
581         $out = "GET $localurl HTTP/1.1\r\n";
582         $out .= "Host: $sitename\r\n";
583         $out .= "Connection: Close\r\n\r\n";
584         fwrite($fp, $out);
585         $data = '';
586         $incoming = false;
587         while (!feof($fp)) {
588             if ($incoming) {
589                 $data .= fgets($fp, 1024);
590             } else if (@fgets($fp, 1024) === "\r\n") {
591                     $incoming = true;
592                 }
593         }
594         fclose($fp);
595         $data = trim($data);
596         if ($data === $teststr) {
597             return INSECURE_DATAROOT_ERROR;
598         }
599     }
601     return INSECURE_DATAROOT_WARNING;
604 /**
605  * Enables CLI maintenance mode by creating new dataroot/climaintenance.html file.
606  */
607 function enable_cli_maintenance_mode() {
608     global $CFG;
610     if (file_exists("$CFG->dataroot/climaintenance.html")) {
611         unlink("$CFG->dataroot/climaintenance.html");
612     }
614     if (isset($CFG->maintenance_message) and !html_is_blank($CFG->maintenance_message)) {
615         $data = $CFG->maintenance_message;
616         $data = bootstrap_renderer::early_error_content($data, null, null, null);
617         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
619     } else if (file_exists("$CFG->dataroot/climaintenance.template.html")) {
620         $data = file_get_contents("$CFG->dataroot/climaintenance.template.html");
622     } else {
623         $data = get_string('sitemaintenance', 'admin');
624         $data = bootstrap_renderer::early_error_content($data, null, null, null);
625         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
626     }
628     file_put_contents("$CFG->dataroot/climaintenance.html", $data);
629     chmod("$CFG->dataroot/climaintenance.html", $CFG->filepermissions);
632 /// CLASS DEFINITIONS /////////////////////////////////////////////////////////
635 /**
636  * Interface for anything appearing in the admin tree
637  *
638  * The interface that is implemented by anything that appears in the admin tree
639  * block. It forces inheriting classes to define a method for checking user permissions
640  * and methods for finding something in the admin tree.
641  *
642  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
643  */
644 interface part_of_admin_tree {
646 /**
647  * Finds a named part_of_admin_tree.
648  *
649  * Used to find a part_of_admin_tree. If a class only inherits part_of_admin_tree
650  * and not parentable_part_of_admin_tree, then this function should only check if
651  * $this->name matches $name. If it does, it should return a reference to $this,
652  * otherwise, it should return a reference to NULL.
653  *
654  * If a class inherits parentable_part_of_admin_tree, this method should be called
655  * recursively on all child objects (assuming, of course, the parent object's name
656  * doesn't match the search criterion).
657  *
658  * @param string $name The internal name of the part_of_admin_tree we're searching for.
659  * @return mixed An object reference or a NULL reference.
660  */
661     public function locate($name);
663     /**
664      * Removes named part_of_admin_tree.
665      *
666      * @param string $name The internal name of the part_of_admin_tree we want to remove.
667      * @return bool success.
668      */
669     public function prune($name);
671     /**
672      * Search using query
673      * @param string $query
674      * @return mixed array-object structure of found settings and pages
675      */
676     public function search($query);
678     /**
679      * Verifies current user's access to this part_of_admin_tree.
680      *
681      * Used to check if the current user has access to this part of the admin tree or
682      * not. If a class only inherits part_of_admin_tree and not parentable_part_of_admin_tree,
683      * then this method is usually just a call to has_capability() in the site context.
684      *
685      * If a class inherits parentable_part_of_admin_tree, this method should return the
686      * logical OR of the return of check_access() on all child objects.
687      *
688      * @return bool True if the user has access, false if she doesn't.
689      */
690     public function check_access();
692     /**
693      * Mostly useful for removing of some parts of the tree in admin tree block.
694      *
695      * @return True is hidden from normal list view
696      */
697     public function is_hidden();
699     /**
700      * Show we display Save button at the page bottom?
701      * @return bool
702      */
703     public function show_save();
707 /**
708  * Interface implemented by any part_of_admin_tree that has children.
709  *
710  * The interface implemented by any part_of_admin_tree that can be a parent
711  * to other part_of_admin_tree's. (For now, this only includes admin_category.) Apart
712  * from ensuring part_of_admin_tree compliancy, it also ensures inheriting methods
713  * include an add method for adding other part_of_admin_tree objects as children.
714  *
715  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
716  */
717 interface parentable_part_of_admin_tree extends part_of_admin_tree {
719 /**
720  * Adds a part_of_admin_tree object to the admin tree.
721  *
722  * Used to add a part_of_admin_tree object to this object or a child of this
723  * object. $something should only be added if $destinationname matches
724  * $this->name. If it doesn't, add should be called on child objects that are
725  * also parentable_part_of_admin_tree's.
726  *
727  * $something should be appended as the last child in the $destinationname. If the
728  * $beforesibling is specified, $something should be prepended to it. If the given
729  * sibling is not found, $something should be appended to the end of $destinationname
730  * and a developer debugging message should be displayed.
731  *
732  * @param string $destinationname The internal name of the new parent for $something.
733  * @param part_of_admin_tree $something The object to be added.
734  * @return bool True on success, false on failure.
735  */
736     public function add($destinationname, $something, $beforesibling = null);
741 /**
742  * The object used to represent folders (a.k.a. categories) in the admin tree block.
743  *
744  * Each admin_category object contains a number of part_of_admin_tree objects.
745  *
746  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
747  */
748 class admin_category implements parentable_part_of_admin_tree {
750     /** @var mixed An array of part_of_admin_tree objects that are this object's children */
751     public $children;
752     /** @var string An internal name for this category. Must be unique amongst ALL part_of_admin_tree objects */
753     public $name;
754     /** @var string The displayed name for this category. Usually obtained through get_string() */
755     public $visiblename;
756     /** @var bool Should this category be hidden in admin tree block? */
757     public $hidden;
758     /** @var mixed Either a string or an array or strings */
759     public $path;
760     /** @var mixed Either a string or an array or strings */
761     public $visiblepath;
763     /** @var array fast lookup category cache, all categories of one tree point to one cache */
764     protected $category_cache;
766     /**
767      * Constructor for an empty admin category
768      *
769      * @param string $name The internal name for this category. Must be unique amongst ALL part_of_admin_tree objects
770      * @param string $visiblename The displayed named for this category. Usually obtained through get_string()
771      * @param bool $hidden hide category in admin tree block, defaults to false
772      */
773     public function __construct($name, $visiblename, $hidden=false) {
774         $this->children    = array();
775         $this->name        = $name;
776         $this->visiblename = $visiblename;
777         $this->hidden      = $hidden;
778     }
780     /**
781      * Returns a reference to the part_of_admin_tree object with internal name $name.
782      *
783      * @param string $name The internal name of the object we want.
784      * @param bool $findpath initialize path and visiblepath arrays
785      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
786      *                  defaults to false
787      */
788     public function locate($name, $findpath=false) {
789         if (!isset($this->category_cache[$this->name])) {
790             // somebody much have purged the cache
791             $this->category_cache[$this->name] = $this;
792         }
794         if ($this->name == $name) {
795             if ($findpath) {
796                 $this->visiblepath[] = $this->visiblename;
797                 $this->path[]        = $this->name;
798             }
799             return $this;
800         }
802         // quick category lookup
803         if (!$findpath and isset($this->category_cache[$name])) {
804             return $this->category_cache[$name];
805         }
807         $return = NULL;
808         foreach($this->children as $childid=>$unused) {
809             if ($return = $this->children[$childid]->locate($name, $findpath)) {
810                 break;
811             }
812         }
814         if (!is_null($return) and $findpath) {
815             $return->visiblepath[] = $this->visiblename;
816             $return->path[]        = $this->name;
817         }
819         return $return;
820     }
822     /**
823      * Search using query
824      *
825      * @param string query
826      * @return mixed array-object structure of found settings and pages
827      */
828     public function search($query) {
829         $result = array();
830         foreach ($this->children as $child) {
831             $subsearch = $child->search($query);
832             if (!is_array($subsearch)) {
833                 debugging('Incorrect search result from '.$child->name);
834                 continue;
835             }
836             $result = array_merge($result, $subsearch);
837         }
838         return $result;
839     }
841     /**
842      * Removes part_of_admin_tree object with internal name $name.
843      *
844      * @param string $name The internal name of the object we want to remove.
845      * @return bool success
846      */
847     public function prune($name) {
849         if ($this->name == $name) {
850             return false;  //can not remove itself
851         }
853         foreach($this->children as $precedence => $child) {
854             if ($child->name == $name) {
855                 // clear cache and delete self
856                 while($this->category_cache) {
857                     // delete the cache, but keep the original array address
858                     array_pop($this->category_cache);
859                 }
860                 unset($this->children[$precedence]);
861                 return true;
862             } else if ($this->children[$precedence]->prune($name)) {
863                 return true;
864             }
865         }
866         return false;
867     }
869     /**
870      * Adds a part_of_admin_tree to a child or grandchild (or great-grandchild, and so forth) of this object.
871      *
872      * By default the new part of the tree is appended as the last child of the parent. You
873      * can specify a sibling node that the new part should be prepended to. If the given
874      * sibling is not found, the part is appended to the end (as it would be by default) and
875      * a developer debugging message is displayed.
876      *
877      * @throws coding_exception if the $beforesibling is empty string or is not string at all.
878      * @param string $destinationame The internal name of the immediate parent that we want for $something.
879      * @param mixed $something A part_of_admin_tree or setting instance to be added.
880      * @param string $beforesibling The name of the parent's child the $something should be prepended to.
881      * @return bool True if successfully added, false if $something can not be added.
882      */
883     public function add($parentname, $something, $beforesibling = null) {
884         global $CFG;
886         $parent = $this->locate($parentname);
887         if (is_null($parent)) {
888             debugging('parent does not exist!');
889             return false;
890         }
892         if ($something instanceof part_of_admin_tree) {
893             if (!($parent instanceof parentable_part_of_admin_tree)) {
894                 debugging('error - parts of tree can be inserted only into parentable parts');
895                 return false;
896             }
897             if ($CFG->debugdeveloper && !is_null($this->locate($something->name))) {
898                 // The name of the node is already used, simply warn the developer that this should not happen.
899                 // It is intentional to check for the debug level before performing the check.
900                 debugging('Duplicate admin page name: ' . $something->name, DEBUG_DEVELOPER);
901             }
902             if (is_null($beforesibling)) {
903                 // Append $something as the parent's last child.
904                 $parent->children[] = $something;
905             } else {
906                 if (!is_string($beforesibling) or trim($beforesibling) === '') {
907                     throw new coding_exception('Unexpected value of the beforesibling parameter');
908                 }
909                 // Try to find the position of the sibling.
910                 $siblingposition = null;
911                 foreach ($parent->children as $childposition => $child) {
912                     if ($child->name === $beforesibling) {
913                         $siblingposition = $childposition;
914                         break;
915                     }
916                 }
917                 if (is_null($siblingposition)) {
918                     debugging('Sibling '.$beforesibling.' not found', DEBUG_DEVELOPER);
919                     $parent->children[] = $something;
920                 } else {
921                     $parent->children = array_merge(
922                         array_slice($parent->children, 0, $siblingposition),
923                         array($something),
924                         array_slice($parent->children, $siblingposition)
925                     );
926                 }
927             }
928             if ($something instanceof admin_category) {
929                 if (isset($this->category_cache[$something->name])) {
930                     debugging('Duplicate admin category name: '.$something->name);
931                 } else {
932                     $this->category_cache[$something->name] = $something;
933                     $something->category_cache =& $this->category_cache;
934                     foreach ($something->children as $child) {
935                         // just in case somebody already added subcategories
936                         if ($child instanceof admin_category) {
937                             if (isset($this->category_cache[$child->name])) {
938                                 debugging('Duplicate admin category name: '.$child->name);
939                             } else {
940                                 $this->category_cache[$child->name] = $child;
941                                 $child->category_cache =& $this->category_cache;
942                             }
943                         }
944                     }
945                 }
946             }
947             return true;
949         } else {
950             debugging('error - can not add this element');
951             return false;
952         }
954     }
956     /**
957      * Checks if the user has access to anything in this category.
958      *
959      * @return bool True if the user has access to at least one child in this category, false otherwise.
960      */
961     public function check_access() {
962         foreach ($this->children as $child) {
963             if ($child->check_access()) {
964                 return true;
965             }
966         }
967         return false;
968     }
970     /**
971      * Is this category hidden in admin tree block?
972      *
973      * @return bool True if hidden
974      */
975     public function is_hidden() {
976         return $this->hidden;
977     }
979     /**
980      * Show we display Save button at the page bottom?
981      * @return bool
982      */
983     public function show_save() {
984         foreach ($this->children as $child) {
985             if ($child->show_save()) {
986                 return true;
987             }
988         }
989         return false;
990     }
994 /**
995  * Root of admin settings tree, does not have any parent.
996  *
997  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
998  */
999 class admin_root extends admin_category {
1000 /** @var array List of errors */
1001     public $errors;
1002     /** @var string search query */
1003     public $search;
1004     /** @var bool full tree flag - true means all settings required, false only pages required */
1005     public $fulltree;
1006     /** @var bool flag indicating loaded tree */
1007     public $loaded;
1008     /** @var mixed site custom defaults overriding defaults in settings files*/
1009     public $custom_defaults;
1011     /**
1012      * @param bool $fulltree true means all settings required,
1013      *                            false only pages required
1014      */
1015     public function __construct($fulltree) {
1016         global $CFG;
1018         parent::__construct('root', get_string('administration'), false);
1019         $this->errors   = array();
1020         $this->search   = '';
1021         $this->fulltree = $fulltree;
1022         $this->loaded   = false;
1024         $this->category_cache = array();
1026         // load custom defaults if found
1027         $this->custom_defaults = null;
1028         $defaultsfile = "$CFG->dirroot/local/defaults.php";
1029         if (is_readable($defaultsfile)) {
1030             $defaults = array();
1031             include($defaultsfile);
1032             if (is_array($defaults) and count($defaults)) {
1033                 $this->custom_defaults = $defaults;
1034             }
1035         }
1036     }
1038     /**
1039      * Empties children array, and sets loaded to false
1040      *
1041      * @param bool $requirefulltree
1042      */
1043     public function purge_children($requirefulltree) {
1044         $this->children = array();
1045         $this->fulltree = ($requirefulltree || $this->fulltree);
1046         $this->loaded   = false;
1047         //break circular dependencies - this helps PHP 5.2
1048         while($this->category_cache) {
1049             array_pop($this->category_cache);
1050         }
1051         $this->category_cache = array();
1052     }
1056 /**
1057  * Links external PHP pages into the admin tree.
1058  *
1059  * See detailed usage example at the top of this document (adminlib.php)
1060  *
1061  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1062  */
1063 class admin_externalpage implements part_of_admin_tree {
1065     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1066     public $name;
1068     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1069     public $visiblename;
1071     /** @var string The external URL that we should link to when someone requests this external page. */
1072     public $url;
1074     /** @var string The role capability/permission a user must have to access this external page. */
1075     public $req_capability;
1077     /** @var object The context in which capability/permission should be checked, default is site context. */
1078     public $context;
1080     /** @var bool hidden in admin tree block. */
1081     public $hidden;
1083     /** @var mixed either string or array of string */
1084     public $path;
1086     /** @var array list of visible names of page parents */
1087     public $visiblepath;
1089     /**
1090      * Constructor for adding an external page into the admin tree.
1091      *
1092      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1093      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1094      * @param string $url The external URL that we should link to when someone requests this external page.
1095      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1096      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1097      * @param stdClass $context The context the page relates to. Not sure what happens
1098      *      if you specify something other than system or front page. Defaults to system.
1099      */
1100     public function __construct($name, $visiblename, $url, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1101         $this->name        = $name;
1102         $this->visiblename = $visiblename;
1103         $this->url         = $url;
1104         if (is_array($req_capability)) {
1105             $this->req_capability = $req_capability;
1106         } else {
1107             $this->req_capability = array($req_capability);
1108         }
1109         $this->hidden = $hidden;
1110         $this->context = $context;
1111     }
1113     /**
1114      * Returns a reference to the part_of_admin_tree object with internal name $name.
1115      *
1116      * @param string $name The internal name of the object we want.
1117      * @param bool $findpath defaults to false
1118      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
1119      */
1120     public function locate($name, $findpath=false) {
1121         if ($this->name == $name) {
1122             if ($findpath) {
1123                 $this->visiblepath = array($this->visiblename);
1124                 $this->path        = array($this->name);
1125             }
1126             return $this;
1127         } else {
1128             $return = NULL;
1129             return $return;
1130         }
1131     }
1133     /**
1134      * This function always returns false, required function by interface
1135      *
1136      * @param string $name
1137      * @return false
1138      */
1139     public function prune($name) {
1140         return false;
1141     }
1143     /**
1144      * Search using query
1145      *
1146      * @param string $query
1147      * @return mixed array-object structure of found settings and pages
1148      */
1149     public function search($query) {
1150         $found = false;
1151         if (strpos(strtolower($this->name), $query) !== false) {
1152             $found = true;
1153         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1154                 $found = true;
1155             }
1156         if ($found) {
1157             $result = new stdClass();
1158             $result->page     = $this;
1159             $result->settings = array();
1160             return array($this->name => $result);
1161         } else {
1162             return array();
1163         }
1164     }
1166     /**
1167      * Determines if the current user has access to this external page based on $this->req_capability.
1168      *
1169      * @return bool True if user has access, false otherwise.
1170      */
1171     public function check_access() {
1172         global $CFG;
1173         $context = empty($this->context) ? context_system::instance() : $this->context;
1174         foreach($this->req_capability as $cap) {
1175             if (has_capability($cap, $context)) {
1176                 return true;
1177             }
1178         }
1179         return false;
1180     }
1182     /**
1183      * Is this external page hidden in admin tree block?
1184      *
1185      * @return bool True if hidden
1186      */
1187     public function is_hidden() {
1188         return $this->hidden;
1189     }
1191     /**
1192      * Show we display Save button at the page bottom?
1193      * @return bool
1194      */
1195     public function show_save() {
1196         return false;
1197     }
1201 /**
1202  * Used to group a number of admin_setting objects into a page and add them to the admin tree.
1203  *
1204  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1205  */
1206 class admin_settingpage implements part_of_admin_tree {
1208     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1209     public $name;
1211     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1212     public $visiblename;
1214     /** @var mixed An array of admin_setting objects that are part of this setting page. */
1215     public $settings;
1217     /** @var string The role capability/permission a user must have to access this external page. */
1218     public $req_capability;
1220     /** @var object The context in which capability/permission should be checked, default is site context. */
1221     public $context;
1223     /** @var bool hidden in admin tree block. */
1224     public $hidden;
1226     /** @var mixed string of paths or array of strings of paths */
1227     public $path;
1229     /** @var array list of visible names of page parents */
1230     public $visiblepath;
1232     /**
1233      * see admin_settingpage for details of this function
1234      *
1235      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1236      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1237      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1238      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1239      * @param stdClass $context The context the page relates to. Not sure what happens
1240      *      if you specify something other than system or front page. Defaults to system.
1241      */
1242     public function __construct($name, $visiblename, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1243         $this->settings    = new stdClass();
1244         $this->name        = $name;
1245         $this->visiblename = $visiblename;
1246         if (is_array($req_capability)) {
1247             $this->req_capability = $req_capability;
1248         } else {
1249             $this->req_capability = array($req_capability);
1250         }
1251         $this->hidden      = $hidden;
1252         $this->context     = $context;
1253     }
1255     /**
1256      * see admin_category
1257      *
1258      * @param string $name
1259      * @param bool $findpath
1260      * @return mixed Object (this) if name ==  this->name, else returns null
1261      */
1262     public function locate($name, $findpath=false) {
1263         if ($this->name == $name) {
1264             if ($findpath) {
1265                 $this->visiblepath = array($this->visiblename);
1266                 $this->path        = array($this->name);
1267             }
1268             return $this;
1269         } else {
1270             $return = NULL;
1271             return $return;
1272         }
1273     }
1275     /**
1276      * Search string in settings page.
1277      *
1278      * @param string $query
1279      * @return array
1280      */
1281     public function search($query) {
1282         $found = array();
1284         foreach ($this->settings as $setting) {
1285             if ($setting->is_related($query)) {
1286                 $found[] = $setting;
1287             }
1288         }
1290         if ($found) {
1291             $result = new stdClass();
1292             $result->page     = $this;
1293             $result->settings = $found;
1294             return array($this->name => $result);
1295         }
1297         $found = false;
1298         if (strpos(strtolower($this->name), $query) !== false) {
1299             $found = true;
1300         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1301                 $found = true;
1302             }
1303         if ($found) {
1304             $result = new stdClass();
1305             $result->page     = $this;
1306             $result->settings = array();
1307             return array($this->name => $result);
1308         } else {
1309             return array();
1310         }
1311     }
1313     /**
1314      * This function always returns false, required by interface
1315      *
1316      * @param string $name
1317      * @return bool Always false
1318      */
1319     public function prune($name) {
1320         return false;
1321     }
1323     /**
1324      * adds an admin_setting to this admin_settingpage
1325      *
1326      * 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
1327      * n.b. each admin_setting in an admin_settingpage must have a unique internal name
1328      *
1329      * @param object $setting is the admin_setting object you want to add
1330      * @return bool true if successful, false if not
1331      */
1332     public function add($setting) {
1333         if (!($setting instanceof admin_setting)) {
1334             debugging('error - not a setting instance');
1335             return false;
1336         }
1338         $this->settings->{$setting->name} = $setting;
1339         return true;
1340     }
1342     /**
1343      * see admin_externalpage
1344      *
1345      * @return bool Returns true for yes false for no
1346      */
1347     public function check_access() {
1348         global $CFG;
1349         $context = empty($this->context) ? context_system::instance() : $this->context;
1350         foreach($this->req_capability as $cap) {
1351             if (has_capability($cap, $context)) {
1352                 return true;
1353             }
1354         }
1355         return false;
1356     }
1358     /**
1359      * outputs this page as html in a table (suitable for inclusion in an admin pagetype)
1360      * @return string Returns an XHTML string
1361      */
1362     public function output_html() {
1363         $adminroot = admin_get_root();
1364         $return = '<fieldset>'."\n".'<div class="clearer"><!-- --></div>'."\n";
1365         foreach($this->settings as $setting) {
1366             $fullname = $setting->get_full_name();
1367             if (array_key_exists($fullname, $adminroot->errors)) {
1368                 $data = $adminroot->errors[$fullname]->data;
1369             } else {
1370                 $data = $setting->get_setting();
1371                 // do not use defaults if settings not available - upgrade settings handles the defaults!
1372             }
1373             $return .= $setting->output_html($data);
1374         }
1375         $return .= '</fieldset>';
1376         return $return;
1377     }
1379     /**
1380      * Is this settings page hidden in admin tree block?
1381      *
1382      * @return bool True if hidden
1383      */
1384     public function is_hidden() {
1385         return $this->hidden;
1386     }
1388     /**
1389      * Show we display Save button at the page bottom?
1390      * @return bool
1391      */
1392     public function show_save() {
1393         foreach($this->settings as $setting) {
1394             if (empty($setting->nosave)) {
1395                 return true;
1396             }
1397         }
1398         return false;
1399     }
1403 /**
1404  * Admin settings class. Only exists on setting pages.
1405  * Read & write happens at this level; no authentication.
1406  *
1407  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1408  */
1409 abstract class admin_setting {
1410     /** @var string unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins. */
1411     public $name;
1412     /** @var string localised name */
1413     public $visiblename;
1414     /** @var string localised long description in Markdown format */
1415     public $description;
1416     /** @var mixed Can be string or array of string */
1417     public $defaultsetting;
1418     /** @var string */
1419     public $updatedcallback;
1420     /** @var mixed can be String or Null.  Null means main config table */
1421     public $plugin; // null means main config table
1422     /** @var bool true indicates this setting does not actually save anything, just information */
1423     public $nosave = false;
1424     /** @var bool if set, indicates that a change to this setting requires rebuild course cache */
1425     public $affectsmodinfo = false;
1426     /** @var array of admin_setting_flag - These are extra checkboxes attached to a setting. */
1427     private $flags = array();
1429     /**
1430      * Constructor
1431      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
1432      *                     or 'myplugin/mysetting' for ones in config_plugins.
1433      * @param string $visiblename localised name
1434      * @param string $description localised long description
1435      * @param mixed $defaultsetting string or array depending on implementation
1436      */
1437     public function __construct($name, $visiblename, $description, $defaultsetting) {
1438         $this->parse_setting_name($name);
1439         $this->visiblename    = $visiblename;
1440         $this->description    = $description;
1441         $this->defaultsetting = $defaultsetting;
1442     }
1444     /**
1445      * Generic function to add a flag to this admin setting.
1446      *
1447      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1448      * @param bool $default - The default for the flag
1449      * @param string $shortname - The shortname for this flag. Used as a suffix for the setting name.
1450      * @param string $displayname - The display name for this flag. Used as a label next to the checkbox.
1451      */
1452     protected function set_flag_options($enabled, $default, $shortname, $displayname) {
1453         if (empty($this->flags[$shortname])) {
1454             $this->flags[$shortname] = new admin_setting_flag($enabled, $default, $shortname, $displayname);
1455         } else {
1456             $this->flags[$shortname]->set_options($enabled, $default);
1457         }
1458     }
1460     /**
1461      * Set the enabled options flag on this admin setting.
1462      *
1463      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1464      * @param bool $default - The default for the flag
1465      */
1466     public function set_enabled_flag_options($enabled, $default) {
1467         $this->set_flag_options($enabled, $default, 'enabled', new lang_string('enabled', 'core_admin'));
1468     }
1470     /**
1471      * Set the advanced options flag on this admin setting.
1472      *
1473      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1474      * @param bool $default - The default for the flag
1475      */
1476     public function set_advanced_flag_options($enabled, $default) {
1477         $this->set_flag_options($enabled, $default, 'adv', new lang_string('advanced'));
1478     }
1481     /**
1482      * Set the locked options flag on this admin setting.
1483      *
1484      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1485      * @param bool $default - The default for the flag
1486      */
1487     public function set_locked_flag_options($enabled, $default) {
1488         $this->set_flag_options($enabled, $default, 'locked', new lang_string('locked', 'core_admin'));
1489     }
1491     /**
1492      * Get the currently saved value for a setting flag
1493      *
1494      * @param admin_setting_flag $flag - One of the admin_setting_flag for this admin_setting.
1495      * @return bool
1496      */
1497     public function get_setting_flag_value(admin_setting_flag $flag) {
1498         $value = $this->config_read($this->name . '_' . $flag->get_shortname());
1499         if (!isset($value)) {
1500             $value = $flag->get_default();
1501         }
1503         return !empty($value);
1504     }
1506     /**
1507      * Get the list of defaults for the flags on this setting.
1508      *
1509      * @param array of strings describing the defaults for this setting. This is appended to by this function.
1510      */
1511     public function get_setting_flag_defaults(& $defaults) {
1512         foreach ($this->flags as $flag) {
1513             if ($flag->is_enabled() && $flag->get_default()) {
1514                 $defaults[] = $flag->get_displayname();
1515             }
1516         }
1517     }
1519     /**
1520      * Output the input fields for the advanced and locked flags on this setting.
1521      *
1522      * @param bool $adv - The current value of the advanced flag.
1523      * @param bool $locked - The current value of the locked flag.
1524      * @return string $output - The html for the flags.
1525      */
1526     public function output_setting_flags() {
1527         $output = '';
1529         foreach ($this->flags as $flag) {
1530             if ($flag->is_enabled()) {
1531                 $output .= $flag->output_setting_flag($this);
1532             }
1533         }
1535         if (!empty($output)) {
1536             return html_writer::tag('span', $output, array('class' => 'adminsettingsflags'));
1537         }
1538         return $output;
1539     }
1541     /**
1542      * Write the values of the flags for this admin setting.
1543      *
1544      * @param array $data - The data submitted from the form or null to set the default value for new installs.
1545      * @return bool - true if successful.
1546      */
1547     public function write_setting_flags($data) {
1548         $result = true;
1549         foreach ($this->flags as $flag) {
1550             $result = $result && $flag->write_setting_flag($this, $data);
1551         }
1552         return $result;
1553     }
1555     /**
1556      * Set up $this->name and potentially $this->plugin
1557      *
1558      * Set up $this->name and possibly $this->plugin based on whether $name looks
1559      * like 'settingname' or 'plugin/settingname'. Also, do some sanity checking
1560      * on the names, that is, output a developer debug warning if the name
1561      * contains anything other than [a-zA-Z0-9_]+.
1562      *
1563      * @param string $name the setting name passed in to the constructor.
1564      */
1565     private function parse_setting_name($name) {
1566         $bits = explode('/', $name);
1567         if (count($bits) > 2) {
1568             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1569         }
1570         $this->name = array_pop($bits);
1571         if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->name)) {
1572             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1573         }
1574         if (!empty($bits)) {
1575             $this->plugin = array_pop($bits);
1576             if ($this->plugin === 'moodle') {
1577                 $this->plugin = null;
1578             } else if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->plugin)) {
1579                     throw new moodle_exception('invalidadminsettingname', '', '', $name);
1580                 }
1581         }
1582     }
1584     /**
1585      * Returns the fullname prefixed by the plugin
1586      * @return string
1587      */
1588     public function get_full_name() {
1589         return 's_'.$this->plugin.'_'.$this->name;
1590     }
1592     /**
1593      * Returns the ID string based on plugin and name
1594      * @return string
1595      */
1596     public function get_id() {
1597         return 'id_s_'.$this->plugin.'_'.$this->name;
1598     }
1600     /**
1601      * @param bool $affectsmodinfo If true, changes to this setting will
1602      *   cause the course cache to be rebuilt
1603      */
1604     public function set_affects_modinfo($affectsmodinfo) {
1605         $this->affectsmodinfo = $affectsmodinfo;
1606     }
1608     /**
1609      * Returns the config if possible
1610      *
1611      * @return mixed returns config if successful else null
1612      */
1613     public function config_read($name) {
1614         global $CFG;
1615         if (!empty($this->plugin)) {
1616             $value = get_config($this->plugin, $name);
1617             return $value === false ? NULL : $value;
1619         } else {
1620             if (isset($CFG->$name)) {
1621                 return $CFG->$name;
1622             } else {
1623                 return NULL;
1624             }
1625         }
1626     }
1628     /**
1629      * Used to set a config pair and log change
1630      *
1631      * @param string $name
1632      * @param mixed $value Gets converted to string if not null
1633      * @return bool Write setting to config table
1634      */
1635     public function config_write($name, $value) {
1636         global $DB, $USER, $CFG;
1638         if ($this->nosave) {
1639             return true;
1640         }
1642         // make sure it is a real change
1643         $oldvalue = get_config($this->plugin, $name);
1644         $oldvalue = ($oldvalue === false) ? null : $oldvalue; // normalise
1645         $value = is_null($value) ? null : (string)$value;
1647         if ($oldvalue === $value) {
1648             return true;
1649         }
1651         // store change
1652         set_config($name, $value, $this->plugin);
1654         // Some admin settings affect course modinfo
1655         if ($this->affectsmodinfo) {
1656             // Clear course cache for all courses
1657             rebuild_course_cache(0, true);
1658         }
1660         add_to_config_log($name, $oldvalue, $value, $this->plugin);
1662         return true; // BC only
1663     }
1665     /**
1666      * Returns current value of this setting
1667      * @return mixed array or string depending on instance, NULL means not set yet
1668      */
1669     public abstract function get_setting();
1671     /**
1672      * Returns default setting if exists
1673      * @return mixed array or string depending on instance; NULL means no default, user must supply
1674      */
1675     public function get_defaultsetting() {
1676         $adminroot =  admin_get_root(false, false);
1677         if (!empty($adminroot->custom_defaults)) {
1678             $plugin = is_null($this->plugin) ? 'moodle' : $this->plugin;
1679             if (isset($adminroot->custom_defaults[$plugin])) {
1680                 if (array_key_exists($this->name, $adminroot->custom_defaults[$plugin])) { // null is valid value here ;-)
1681                     return $adminroot->custom_defaults[$plugin][$this->name];
1682                 }
1683             }
1684         }
1685         return $this->defaultsetting;
1686     }
1688     /**
1689      * Store new setting
1690      *
1691      * @param mixed $data string or array, must not be NULL
1692      * @return string empty string if ok, string error message otherwise
1693      */
1694     public abstract function write_setting($data);
1696     /**
1697      * Return part of form with setting
1698      * This function should always be overwritten
1699      *
1700      * @param mixed $data array or string depending on setting
1701      * @param string $query
1702      * @return string
1703      */
1704     public function output_html($data, $query='') {
1705     // should be overridden
1706         return;
1707     }
1709     /**
1710      * Function called if setting updated - cleanup, cache reset, etc.
1711      * @param string $functionname Sets the function name
1712      * @return void
1713      */
1714     public function set_updatedcallback($functionname) {
1715         $this->updatedcallback = $functionname;
1716     }
1718     /**
1719      * Execute postupdatecallback if necessary.
1720      * @param mixed $original original value before write_setting()
1721      * @return bool true if changed, false if not.
1722      */
1723     public function post_write_settings($original) {
1724         // Comparison must work for arrays too.
1725         if (serialize($original) === serialize($this->get_setting())) {
1726             return false;
1727         }
1729         $callbackfunction = $this->updatedcallback;
1730         if (!empty($callbackfunction) and function_exists($callbackfunction)) {
1731             $callbackfunction($this->get_full_name());
1732         }
1733         return true;
1734     }
1736     /**
1737      * Is setting related to query text - used when searching
1738      * @param string $query
1739      * @return bool
1740      */
1741     public function is_related($query) {
1742         if (strpos(strtolower($this->name), $query) !== false) {
1743             return true;
1744         }
1745         if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1746             return true;
1747         }
1748         if (strpos(core_text::strtolower($this->description), $query) !== false) {
1749             return true;
1750         }
1751         $current = $this->get_setting();
1752         if (!is_null($current)) {
1753             if (is_string($current)) {
1754                 if (strpos(core_text::strtolower($current), $query) !== false) {
1755                     return true;
1756                 }
1757             }
1758         }
1759         $default = $this->get_defaultsetting();
1760         if (!is_null($default)) {
1761             if (is_string($default)) {
1762                 if (strpos(core_text::strtolower($default), $query) !== false) {
1763                     return true;
1764                 }
1765             }
1766         }
1767         return false;
1768     }
1771 /**
1772  * An additional option that can be applied to an admin setting.
1773  * The currently supported options are 'ADVANCED' and 'LOCKED'.
1774  *
1775  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1776  */
1777 class admin_setting_flag {
1778     /** @var bool Flag to indicate if this option can be toggled for this setting */
1779     private $enabled = false;
1780     /** @var bool Flag to indicate if this option defaults to true or false */
1781     private $default = false;
1782     /** @var string Short string used to create setting name - e.g. 'adv' */
1783     private $shortname = '';
1784     /** @var string String used as the label for this flag */
1785     private $displayname = '';
1786     /** @const Checkbox for this flag is displayed in admin page */
1787     const ENABLED = true;
1788     /** @const Checkbox for this flag is not displayed in admin page */
1789     const DISABLED = false;
1791     /**
1792      * Constructor
1793      *
1794      * @param bool $enabled Can this option can be toggled.
1795      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
1796      * @param bool $default The default checked state for this setting option.
1797      * @param string $shortname The shortname of this flag. Currently supported flags are 'locked' and 'adv'
1798      * @param string $displayname The displayname of this flag. Used as a label for the flag.
1799      */
1800     public function __construct($enabled, $default, $shortname, $displayname) {
1801         $this->shortname = $shortname;
1802         $this->displayname = $displayname;
1803         $this->set_options($enabled, $default);
1804     }
1806     /**
1807      * Update the values of this setting options class
1808      *
1809      * @param bool $enabled Can this option can be toggled.
1810      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
1811      * @param bool $default The default checked state for this setting option.
1812      */
1813     public function set_options($enabled, $default) {
1814         $this->enabled = $enabled;
1815         $this->default = $default;
1816     }
1818     /**
1819      * Should this option appear in the interface and be toggleable?
1820      *
1821      * @return bool Is it enabled?
1822      */
1823     public function is_enabled() {
1824         return $this->enabled;
1825     }
1827     /**
1828      * Should this option be checked by default?
1829      *
1830      * @return bool Is it on by default?
1831      */
1832     public function get_default() {
1833         return $this->default;
1834     }
1836     /**
1837      * Return the short name for this flag. e.g. 'adv' or 'locked'
1838      *
1839      * @return string
1840      */
1841     public function get_shortname() {
1842         return $this->shortname;
1843     }
1845     /**
1846      * Return the display name for this flag. e.g. 'Advanced' or 'Locked'
1847      *
1848      * @return string
1849      */
1850     public function get_displayname() {
1851         return $this->displayname;
1852     }
1854     /**
1855      * Save the submitted data for this flag - or set it to the default if $data is null.
1856      *
1857      * @param admin_setting $setting - The admin setting for this flag
1858      * @param array $data - The data submitted from the form or null to set the default value for new installs.
1859      * @return bool
1860      */
1861     public function write_setting_flag(admin_setting $setting, $data) {
1862         $result = true;
1863         if ($this->is_enabled()) {
1864             if (!isset($data)) {
1865                 $value = $this->get_default();
1866             } else {
1867                 $value = !empty($data[$setting->get_full_name() . '_' . $this->get_shortname()]);
1868             }
1869             $result = $setting->config_write($setting->name . '_' . $this->get_shortname(), $value);
1870         }
1872         return $result;
1874     }
1876     /**
1877      * Output the checkbox for this setting flag. Should only be called if the flag is enabled.
1878      *
1879      * @param admin_setting $setting - The admin setting for this flag
1880      * @return string - The html for the checkbox.
1881      */
1882     public function output_setting_flag(admin_setting $setting) {
1883         $value = $setting->get_setting_flag_value($this);
1884         $output = ' <input type="checkbox" class="form-checkbox" ' .
1885                         ' id="' .  $setting->get_id() . '_' . $this->get_shortname() . '" ' .
1886                         ' name="' . $setting->get_full_name() .  '_' . $this->get_shortname() . '" ' .
1887                         ' value="1" ' . ($value ? 'checked="checked"' : '') . ' />' .
1888                         ' <label for="' . $setting->get_id() . '_' . $this->get_shortname() . '">' .
1889                         $this->get_displayname() .
1890                         ' </label> ';
1891         return $output;
1892     }
1896 /**
1897  * No setting - just heading and text.
1898  *
1899  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1900  */
1901 class admin_setting_heading extends admin_setting {
1903     /**
1904      * not a setting, just text
1905      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1906      * @param string $heading heading
1907      * @param string $information text in box
1908      */
1909     public function __construct($name, $heading, $information) {
1910         $this->nosave = true;
1911         parent::__construct($name, $heading, $information, '');
1912     }
1914     /**
1915      * Always returns true
1916      * @return bool Always returns true
1917      */
1918     public function get_setting() {
1919         return true;
1920     }
1922     /**
1923      * Always returns true
1924      * @return bool Always returns true
1925      */
1926     public function get_defaultsetting() {
1927         return true;
1928     }
1930     /**
1931      * Never write settings
1932      * @return string Always returns an empty string
1933      */
1934     public function write_setting($data) {
1935     // do not write any setting
1936         return '';
1937     }
1939     /**
1940      * Returns an HTML string
1941      * @return string Returns an HTML string
1942      */
1943     public function output_html($data, $query='') {
1944         global $OUTPUT;
1945         $return = '';
1946         if ($this->visiblename != '') {
1947             $return .= $OUTPUT->heading($this->visiblename, 3, 'main');
1948         }
1949         if ($this->description != '') {
1950             $return .= $OUTPUT->box(highlight($query, markdown_to_html($this->description)), 'generalbox formsettingheading');
1951         }
1952         return $return;
1953     }
1957 /**
1958  * The most flexibly setting, user is typing text
1959  *
1960  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1961  */
1962 class admin_setting_configtext extends admin_setting {
1964     /** @var mixed int means PARAM_XXX type, string is a allowed format in regex */
1965     public $paramtype;
1966     /** @var int default field size */
1967     public $size;
1969     /**
1970      * Config text constructor
1971      *
1972      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1973      * @param string $visiblename localised
1974      * @param string $description long localised info
1975      * @param string $defaultsetting
1976      * @param mixed $paramtype int means PARAM_XXX type, string is a allowed format in regex
1977      * @param int $size default field size
1978      */
1979     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $size=null) {
1980         $this->paramtype = $paramtype;
1981         if (!is_null($size)) {
1982             $this->size  = $size;
1983         } else {
1984             $this->size  = ($paramtype === PARAM_INT) ? 5 : 30;
1985         }
1986         parent::__construct($name, $visiblename, $description, $defaultsetting);
1987     }
1989     /**
1990      * Return the setting
1991      *
1992      * @return mixed returns config if successful else null
1993      */
1994     public function get_setting() {
1995         return $this->config_read($this->name);
1996     }
1998     public function write_setting($data) {
1999         if ($this->paramtype === PARAM_INT and $data === '') {
2000         // do not complain if '' used instead of 0
2001             $data = 0;
2002         }
2003         // $data is a string
2004         $validated = $this->validate($data);
2005         if ($validated !== true) {
2006             return $validated;
2007         }
2008         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2009     }
2011     /**
2012      * Validate data before storage
2013      * @param string data
2014      * @return mixed true if ok string if error found
2015      */
2016     public function validate($data) {
2017         // allow paramtype to be a custom regex if it is the form of /pattern/
2018         if (preg_match('#^/.*/$#', $this->paramtype)) {
2019             if (preg_match($this->paramtype, $data)) {
2020                 return true;
2021             } else {
2022                 return get_string('validateerror', 'admin');
2023             }
2025         } else if ($this->paramtype === PARAM_RAW) {
2026             return true;
2028         } else {
2029             $cleaned = clean_param($data, $this->paramtype);
2030             if ("$data" === "$cleaned") { // implicit conversion to string is needed to do exact comparison
2031                 return true;
2032             } else {
2033                 return get_string('validateerror', 'admin');
2034             }
2035         }
2036     }
2038     /**
2039      * Return an XHTML string for the setting
2040      * @return string Returns an XHTML string
2041      */
2042     public function output_html($data, $query='') {
2043         $default = $this->get_defaultsetting();
2045         return format_admin_setting($this, $this->visiblename,
2046         '<div class="form-text defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" /></div>',
2047         $this->description, true, '', $default, $query);
2048     }
2052 /**
2053  * General text area without html editor.
2054  *
2055  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2056  */
2057 class admin_setting_configtextarea extends admin_setting_configtext {
2058     private $rows;
2059     private $cols;
2061     /**
2062      * @param string $name
2063      * @param string $visiblename
2064      * @param string $description
2065      * @param mixed $defaultsetting string or array
2066      * @param mixed $paramtype
2067      * @param string $cols The number of columns to make the editor
2068      * @param string $rows The number of rows to make the editor
2069      */
2070     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2071         $this->rows = $rows;
2072         $this->cols = $cols;
2073         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
2074     }
2076     /**
2077      * Returns an XHTML string for the editor
2078      *
2079      * @param string $data
2080      * @param string $query
2081      * @return string XHTML string for the editor
2082      */
2083     public function output_html($data, $query='') {
2084         $default = $this->get_defaultsetting();
2086         $defaultinfo = $default;
2087         if (!is_null($default) and $default !== '') {
2088             $defaultinfo = "\n".$default;
2089         }
2091         return format_admin_setting($this, $this->visiblename,
2092         '<div class="form-textarea" ><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'" spellcheck="true">'. s($data) .'</textarea></div>',
2093         $this->description, true, '', $defaultinfo, $query);
2094     }
2098 /**
2099  * General text area with html editor.
2100  */
2101 class admin_setting_confightmleditor extends admin_setting_configtext {
2102     private $rows;
2103     private $cols;
2105     /**
2106      * @param string $name
2107      * @param string $visiblename
2108      * @param string $description
2109      * @param mixed $defaultsetting string or array
2110      * @param mixed $paramtype
2111      */
2112     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2113         $this->rows = $rows;
2114         $this->cols = $cols;
2115         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
2116         editors_head_setup();
2117     }
2119     /**
2120      * Returns an XHTML string for the editor
2121      *
2122      * @param string $data
2123      * @param string $query
2124      * @return string XHTML string for the editor
2125      */
2126     public function output_html($data, $query='') {
2127         $default = $this->get_defaultsetting();
2129         $defaultinfo = $default;
2130         if (!is_null($default) and $default !== '') {
2131             $defaultinfo = "\n".$default;
2132         }
2134         $editor = editors_get_preferred_editor(FORMAT_HTML);
2135         $editor->use_editor($this->get_id(), array('noclean'=>true));
2137         return format_admin_setting($this, $this->visiblename,
2138         '<div class="form-textarea"><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'" spellcheck="true">'. s($data) .'</textarea></div>',
2139         $this->description, true, '', $defaultinfo, $query);
2140     }
2144 /**
2145  * Password field, allows unmasking of password
2146  *
2147  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2148  */
2149 class admin_setting_configpasswordunmask extends admin_setting_configtext {
2150     /**
2151      * Constructor
2152      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2153      * @param string $visiblename localised
2154      * @param string $description long localised info
2155      * @param string $defaultsetting default password
2156      */
2157     public function __construct($name, $visiblename, $description, $defaultsetting) {
2158         parent::__construct($name, $visiblename, $description, $defaultsetting, PARAM_RAW, 30);
2159     }
2161     /**
2162      * Returns XHTML for the field
2163      * Writes Javascript into the HTML below right before the last div
2164      *
2165      * @todo Make javascript available through newer methods if possible
2166      * @param string $data Value for the field
2167      * @param string $query Passed as final argument for format_admin_setting
2168      * @return string XHTML field
2169      */
2170     public function output_html($data, $query='') {
2171         $id = $this->get_id();
2172         $unmask = get_string('unmaskpassword', 'form');
2173         $unmaskjs = '<script type="text/javascript">
2174 //<![CDATA[
2175 var is_ie = (navigator.userAgent.toLowerCase().indexOf("msie") != -1);
2177 document.getElementById("'.$id.'").setAttribute("autocomplete", "off");
2179 var unmaskdiv = document.getElementById("'.$id.'unmaskdiv");
2181 var unmaskchb = document.createElement("input");
2182 unmaskchb.setAttribute("type", "checkbox");
2183 unmaskchb.setAttribute("id", "'.$id.'unmask");
2184 unmaskchb.onchange = function() {unmaskPassword("'.$id.'");};
2185 unmaskdiv.appendChild(unmaskchb);
2187 var unmasklbl = document.createElement("label");
2188 unmasklbl.innerHTML = "'.addslashes_js($unmask).'";
2189 if (is_ie) {
2190   unmasklbl.setAttribute("htmlFor", "'.$id.'unmask");
2191 } else {
2192   unmasklbl.setAttribute("for", "'.$id.'unmask");
2194 unmaskdiv.appendChild(unmasklbl);
2196 if (is_ie) {
2197   // ugly hack to work around the famous onchange IE bug
2198   unmaskchb.onclick = function() {this.blur();};
2199   unmaskdiv.onclick = function() {this.blur();};
2201 //]]>
2202 </script>';
2203         return format_admin_setting($this, $this->visiblename,
2204         '<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>',
2205         $this->description, true, '', NULL, $query);
2206     }
2209 /**
2210  * Empty setting used to allow flags (advanced) on settings that can have no sensible default.
2211  * Note: Only advanced makes sense right now - locked does not.
2212  *
2213  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2214  */
2215 class admin_setting_configempty extends admin_setting_configtext {
2217     /**
2218      * @param string $name
2219      * @param string $visiblename
2220      * @param string $description
2221      */
2222     public function __construct($name, $visiblename, $description) {
2223         parent::__construct($name, $visiblename, $description, '', PARAM_RAW);
2224     }
2226     /**
2227      * Returns an XHTML string for the hidden field
2228      *
2229      * @param string $data
2230      * @param string $query
2231      * @return string XHTML string for the editor
2232      */
2233     public function output_html($data, $query='') {
2234         return format_admin_setting($this,
2235                                     $this->visiblename,
2236                                     '<div class="form-empty" >' .
2237                                     '<input type="hidden"' .
2238                                         ' id="'. $this->get_id() .'"' .
2239                                         ' name="'. $this->get_full_name() .'"' .
2240                                         ' value=""/></div>',
2241                                     $this->description,
2242                                     true,
2243                                     '',
2244                                     get_string('none'),
2245                                     $query);
2246     }
2250 /**
2251  * Path to directory
2252  *
2253  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2254  */
2255 class admin_setting_configfile extends admin_setting_configtext {
2256     /**
2257      * Constructor
2258      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2259      * @param string $visiblename localised
2260      * @param string $description long localised info
2261      * @param string $defaultdirectory default directory location
2262      */
2263     public function __construct($name, $visiblename, $description, $defaultdirectory) {
2264         parent::__construct($name, $visiblename, $description, $defaultdirectory, PARAM_RAW, 50);
2265     }
2267     /**
2268      * Returns XHTML for the field
2269      *
2270      * Returns XHTML for the field and also checks whether the file
2271      * specified in $data exists using file_exists()
2272      *
2273      * @param string $data File name and path to use in value attr
2274      * @param string $query
2275      * @return string XHTML field
2276      */
2277     public function output_html($data, $query='') {
2278         $default = $this->get_defaultsetting();
2280         if ($data) {
2281             if (file_exists($data)) {
2282                 $executable = '<span class="pathok">&#x2714;</span>';
2283             } else {
2284                 $executable = '<span class="patherror">&#x2718;</span>';
2285             }
2286         } else {
2287             $executable = '';
2288         }
2290         return format_admin_setting($this, $this->visiblename,
2291         '<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>',
2292         $this->description, true, '', $default, $query);
2293     }
2294     /**
2295      * checks if execpatch has been disabled in config.php
2296      */
2297     public function write_setting($data) {
2298         global $CFG;
2299         if (!empty($CFG->preventexecpath)) {
2300             return '';
2301         }
2302         return parent::write_setting($data);
2303     }
2307 /**
2308  * Path to executable file
2309  *
2310  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2311  */
2312 class admin_setting_configexecutable extends admin_setting_configfile {
2314     /**
2315      * Returns an XHTML field
2316      *
2317      * @param string $data This is the value for the field
2318      * @param string $query
2319      * @return string XHTML field
2320      */
2321     public function output_html($data, $query='') {
2322         global $CFG;
2323         $default = $this->get_defaultsetting();
2325         if ($data) {
2326             if (file_exists($data) and is_executable($data)) {
2327                 $executable = '<span class="pathok">&#x2714;</span>';
2328             } else {
2329                 $executable = '<span class="patherror">&#x2718;</span>';
2330             }
2331         } else {
2332             $executable = '';
2333         }
2334         if (!empty($CFG->preventexecpath)) {
2335             $this->visiblename .= '<div class="form-overridden">'.get_string('execpathnotallowed', 'admin').'</div>';
2336         }
2338         return format_admin_setting($this, $this->visiblename,
2339         '<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>',
2340         $this->description, true, '', $default, $query);
2341     }
2345 /**
2346  * Path to directory
2347  *
2348  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2349  */
2350 class admin_setting_configdirectory extends admin_setting_configfile {
2352     /**
2353      * Returns an XHTML field
2354      *
2355      * @param string $data This is the value for the field
2356      * @param string $query
2357      * @return string XHTML
2358      */
2359     public function output_html($data, $query='') {
2360         $default = $this->get_defaultsetting();
2362         if ($data) {
2363             if (file_exists($data) and is_dir($data)) {
2364                 $executable = '<span class="pathok">&#x2714;</span>';
2365             } else {
2366                 $executable = '<span class="patherror">&#x2718;</span>';
2367             }
2368         } else {
2369             $executable = '';
2370         }
2372         return format_admin_setting($this, $this->visiblename,
2373         '<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>',
2374         $this->description, true, '', $default, $query);
2375     }
2379 /**
2380  * Checkbox
2381  *
2382  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2383  */
2384 class admin_setting_configcheckbox extends admin_setting {
2385     /** @var string Value used when checked */
2386     public $yes;
2387     /** @var string Value used when not checked */
2388     public $no;
2390     /**
2391      * Constructor
2392      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2393      * @param string $visiblename localised
2394      * @param string $description long localised info
2395      * @param string $defaultsetting
2396      * @param string $yes value used when checked
2397      * @param string $no value used when not checked
2398      */
2399     public function __construct($name, $visiblename, $description, $defaultsetting, $yes='1', $no='0') {
2400         parent::__construct($name, $visiblename, $description, $defaultsetting);
2401         $this->yes = (string)$yes;
2402         $this->no  = (string)$no;
2403     }
2405     /**
2406      * Retrieves the current setting using the objects name
2407      *
2408      * @return string
2409      */
2410     public function get_setting() {
2411         return $this->config_read($this->name);
2412     }
2414     /**
2415      * Sets the value for the setting
2416      *
2417      * Sets the value for the setting to either the yes or no values
2418      * of the object by comparing $data to yes
2419      *
2420      * @param mixed $data Gets converted to str for comparison against yes value
2421      * @return string empty string or error
2422      */
2423     public function write_setting($data) {
2424         if ((string)$data === $this->yes) { // convert to strings before comparison
2425             $data = $this->yes;
2426         } else {
2427             $data = $this->no;
2428         }
2429         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2430     }
2432     /**
2433      * Returns an XHTML checkbox field
2434      *
2435      * @param string $data If $data matches yes then checkbox is checked
2436      * @param string $query
2437      * @return string XHTML field
2438      */
2439     public function output_html($data, $query='') {
2440         $default = $this->get_defaultsetting();
2442         if (!is_null($default)) {
2443             if ((string)$default === $this->yes) {
2444                 $defaultinfo = get_string('checkboxyes', 'admin');
2445             } else {
2446                 $defaultinfo = get_string('checkboxno', 'admin');
2447             }
2448         } else {
2449             $defaultinfo = NULL;
2450         }
2452         if ((string)$data === $this->yes) { // convert to strings before comparison
2453             $checked = 'checked="checked"';
2454         } else {
2455             $checked = '';
2456         }
2458         return format_admin_setting($this, $this->visiblename,
2459         '<div class="form-checkbox defaultsnext" ><input type="hidden" name="'.$this->get_full_name().'" value="'.s($this->no).'" /> '
2460             .'<input type="checkbox" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($this->yes).'" '.$checked.' /></div>',
2461         $this->description, true, '', $defaultinfo, $query);
2462     }
2466 /**
2467  * Multiple checkboxes, each represents different value, stored in csv format
2468  *
2469  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2470  */
2471 class admin_setting_configmulticheckbox extends admin_setting {
2472     /** @var array Array of choices value=>label */
2473     public $choices;
2475     /**
2476      * Constructor: uses parent::__construct
2477      *
2478      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2479      * @param string $visiblename localised
2480      * @param string $description long localised info
2481      * @param array $defaultsetting array of selected
2482      * @param array $choices array of $value=>$label for each checkbox
2483      */
2484     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2485         $this->choices = $choices;
2486         parent::__construct($name, $visiblename, $description, $defaultsetting);
2487     }
2489     /**
2490      * This public function may be used in ancestors for lazy loading of choices
2491      *
2492      * @todo Check if this function is still required content commented out only returns true
2493      * @return bool true if loaded, false if error
2494      */
2495     public function load_choices() {
2496         /*
2497         if (is_array($this->choices)) {
2498             return true;
2499         }
2500         .... load choices here
2501         */
2502         return true;
2503     }
2505     /**
2506      * Is setting related to query text - used when searching
2507      *
2508      * @param string $query
2509      * @return bool true on related, false on not or failure
2510      */
2511     public function is_related($query) {
2512         if (!$this->load_choices() or empty($this->choices)) {
2513             return false;
2514         }
2515         if (parent::is_related($query)) {
2516             return true;
2517         }
2519         foreach ($this->choices as $desc) {
2520             if (strpos(core_text::strtolower($desc), $query) !== false) {
2521                 return true;
2522             }
2523         }
2524         return false;
2525     }
2527     /**
2528      * Returns the current setting if it is set
2529      *
2530      * @return mixed null if null, else an array
2531      */
2532     public function get_setting() {
2533         $result = $this->config_read($this->name);
2535         if (is_null($result)) {
2536             return NULL;
2537         }
2538         if ($result === '') {
2539             return array();
2540         }
2541         $enabled = explode(',', $result);
2542         $setting = array();
2543         foreach ($enabled as $option) {
2544             $setting[$option] = 1;
2545         }
2546         return $setting;
2547     }
2549     /**
2550      * Saves the setting(s) provided in $data
2551      *
2552      * @param array $data An array of data, if not array returns empty str
2553      * @return mixed empty string on useless data or bool true=success, false=failed
2554      */
2555     public function write_setting($data) {
2556         if (!is_array($data)) {
2557             return ''; // ignore it
2558         }
2559         if (!$this->load_choices() or empty($this->choices)) {
2560             return '';
2561         }
2562         unset($data['xxxxx']);
2563         $result = array();
2564         foreach ($data as $key => $value) {
2565             if ($value and array_key_exists($key, $this->choices)) {
2566                 $result[] = $key;
2567             }
2568         }
2569         return $this->config_write($this->name, implode(',', $result)) ? '' : get_string('errorsetting', 'admin');
2570     }
2572     /**
2573      * Returns XHTML field(s) as required by choices
2574      *
2575      * Relies on data being an array should data ever be another valid vartype with
2576      * acceptable value this may cause a warning/error
2577      * if (!is_array($data)) would fix the problem
2578      *
2579      * @todo Add vartype handling to ensure $data is an array
2580      *
2581      * @param array $data An array of checked values
2582      * @param string $query
2583      * @return string XHTML field
2584      */
2585     public function output_html($data, $query='') {
2586         if (!$this->load_choices() or empty($this->choices)) {
2587             return '';
2588         }
2589         $default = $this->get_defaultsetting();
2590         if (is_null($default)) {
2591             $default = array();
2592         }
2593         if (is_null($data)) {
2594             $data = array();
2595         }
2596         $options = array();
2597         $defaults = array();
2598         foreach ($this->choices as $key=>$description) {
2599             if (!empty($data[$key])) {
2600                 $checked = 'checked="checked"';
2601             } else {
2602                 $checked = '';
2603             }
2604             if (!empty($default[$key])) {
2605                 $defaults[] = $description;
2606             }
2608             $options[] = '<input type="checkbox" id="'.$this->get_id().'_'.$key.'" name="'.$this->get_full_name().'['.$key.']" value="1" '.$checked.' />'
2609                 .'<label for="'.$this->get_id().'_'.$key.'">'.highlightfast($query, $description).'</label>';
2610         }
2612         if (is_null($default)) {
2613             $defaultinfo = NULL;
2614         } else if (!empty($defaults)) {
2615                 $defaultinfo = implode(', ', $defaults);
2616             } else {
2617                 $defaultinfo = get_string('none');
2618             }
2620         $return = '<div class="form-multicheckbox">';
2621         $return .= '<input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2622         if ($options) {
2623             $return .= '<ul>';
2624             foreach ($options as $option) {
2625                 $return .= '<li>'.$option.'</li>';
2626             }
2627             $return .= '</ul>';
2628         }
2629         $return .= '</div>';
2631         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
2633     }
2637 /**
2638  * Multiple checkboxes 2, value stored as string 00101011
2639  *
2640  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2641  */
2642 class admin_setting_configmulticheckbox2 extends admin_setting_configmulticheckbox {
2644     /**
2645      * Returns the setting if set
2646      *
2647      * @return mixed null if not set, else an array of set settings
2648      */
2649     public function get_setting() {
2650         $result = $this->config_read($this->name);
2651         if (is_null($result)) {
2652             return NULL;
2653         }
2654         if (!$this->load_choices()) {
2655             return NULL;
2656         }
2657         $result = str_pad($result, count($this->choices), '0');
2658         $result = preg_split('//', $result, -1, PREG_SPLIT_NO_EMPTY);
2659         $setting = array();
2660         foreach ($this->choices as $key=>$unused) {
2661             $value = array_shift($result);
2662             if ($value) {
2663                 $setting[$key] = 1;
2664             }
2665         }
2666         return $setting;
2667     }
2669     /**
2670      * Save setting(s) provided in $data param
2671      *
2672      * @param array $data An array of settings to save
2673      * @return mixed empty string for bad data or bool true=>success, false=>error
2674      */
2675     public function write_setting($data) {
2676         if (!is_array($data)) {
2677             return ''; // ignore it
2678         }
2679         if (!$this->load_choices() or empty($this->choices)) {
2680             return '';
2681         }
2682         $result = '';
2683         foreach ($this->choices as $key=>$unused) {
2684             if (!empty($data[$key])) {
2685                 $result .= '1';
2686             } else {
2687                 $result .= '0';
2688             }
2689         }
2690         return $this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin');
2691     }
2695 /**
2696  * Select one value from list
2697  *
2698  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2699  */
2700 class admin_setting_configselect extends admin_setting {
2701     /** @var array Array of choices value=>label */
2702     public $choices;
2704     /**
2705      * Constructor
2706      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2707      * @param string $visiblename localised
2708      * @param string $description long localised info
2709      * @param string|int $defaultsetting
2710      * @param array $choices array of $value=>$label for each selection
2711      */
2712     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2713         $this->choices = $choices;
2714         parent::__construct($name, $visiblename, $description, $defaultsetting);
2715     }
2717     /**
2718      * This function may be used in ancestors for lazy loading of choices
2719      *
2720      * Override this method if loading of choices is expensive, such
2721      * as when it requires multiple db requests.
2722      *
2723      * @return bool true if loaded, false if error
2724      */
2725     public function load_choices() {
2726         /*
2727         if (is_array($this->choices)) {
2728             return true;
2729         }
2730         .... load choices here
2731         */
2732         return true;
2733     }
2735     /**
2736      * Check if this is $query is related to a choice
2737      *
2738      * @param string $query
2739      * @return bool true if related, false if not
2740      */
2741     public function is_related($query) {
2742         if (parent::is_related($query)) {
2743             return true;
2744         }
2745         if (!$this->load_choices()) {
2746             return false;
2747         }
2748         foreach ($this->choices as $key=>$value) {
2749             if (strpos(core_text::strtolower($key), $query) !== false) {
2750                 return true;
2751             }
2752             if (strpos(core_text::strtolower($value), $query) !== false) {
2753                 return true;
2754             }
2755         }
2756         return false;
2757     }
2759     /**
2760      * Return the setting
2761      *
2762      * @return mixed returns config if successful else null
2763      */
2764     public function get_setting() {
2765         return $this->config_read($this->name);
2766     }
2768     /**
2769      * Save a setting
2770      *
2771      * @param string $data
2772      * @return string empty of error string
2773      */
2774     public function write_setting($data) {
2775         if (!$this->load_choices() or empty($this->choices)) {
2776             return '';
2777         }
2778         if (!array_key_exists($data, $this->choices)) {
2779             return ''; // ignore it
2780         }
2782         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2783     }
2785     /**
2786      * Returns XHTML select field
2787      *
2788      * Ensure the options are loaded, and generate the XHTML for the select
2789      * element and any warning message. Separating this out from output_html
2790      * makes it easier to subclass this class.
2791      *
2792      * @param string $data the option to show as selected.
2793      * @param string $current the currently selected option in the database, null if none.
2794      * @param string $default the default selected option.
2795      * @return array the HTML for the select element, and a warning message.
2796      */
2797     public function output_select_html($data, $current, $default, $extraname = '') {
2798         if (!$this->load_choices() or empty($this->choices)) {
2799             return array('', '');
2800         }
2802         $warning = '';
2803         if (is_null($current)) {
2804         // first run
2805         } else if (empty($current) and (array_key_exists('', $this->choices) or array_key_exists(0, $this->choices))) {
2806             // no warning
2807             } else if (!array_key_exists($current, $this->choices)) {
2808                     $warning = get_string('warningcurrentsetting', 'admin', s($current));
2809                     if (!is_null($default) and $data == $current) {
2810                         $data = $default; // use default instead of first value when showing the form
2811                     }
2812                 }
2814         $selecthtml = '<select id="'.$this->get_id().'" name="'.$this->get_full_name().$extraname.'">';
2815         foreach ($this->choices as $key => $value) {
2816         // the string cast is needed because key may be integer - 0 is equal to most strings!
2817             $selecthtml .= '<option value="'.$key.'"'.((string)$key==$data ? ' selected="selected"' : '').'>'.$value.'</option>';
2818         }
2819         $selecthtml .= '</select>';
2820         return array($selecthtml, $warning);
2821     }
2823     /**
2824      * Returns XHTML select field and wrapping div(s)
2825      *
2826      * @see output_select_html()
2827      *
2828      * @param string $data the option to show as selected
2829      * @param string $query
2830      * @return string XHTML field and wrapping div
2831      */
2832     public function output_html($data, $query='') {
2833         $default = $this->get_defaultsetting();
2834         $current = $this->get_setting();
2836         list($selecthtml, $warning) = $this->output_select_html($data, $current, $default);
2837         if (!$selecthtml) {
2838             return '';
2839         }
2841         if (!is_null($default) and array_key_exists($default, $this->choices)) {
2842             $defaultinfo = $this->choices[$default];
2843         } else {
2844             $defaultinfo = NULL;
2845         }
2847         $return = '<div class="form-select defaultsnext">' . $selecthtml . '</div>';
2849         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, $warning, $defaultinfo, $query);
2850     }
2854 /**
2855  * Select multiple items from list
2856  *
2857  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2858  */
2859 class admin_setting_configmultiselect extends admin_setting_configselect {
2860     /**
2861      * Constructor
2862      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2863      * @param string $visiblename localised
2864      * @param string $description long localised info
2865      * @param array $defaultsetting array of selected items
2866      * @param array $choices array of $value=>$label for each list item
2867      */
2868     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2869         parent::__construct($name, $visiblename, $description, $defaultsetting, $choices);
2870     }
2872     /**
2873      * Returns the select setting(s)
2874      *
2875      * @return mixed null or array. Null if no settings else array of setting(s)
2876      */
2877     public function get_setting() {
2878         $result = $this->config_read($this->name);
2879         if (is_null($result)) {
2880             return NULL;
2881         }
2882         if ($result === '') {
2883             return array();
2884         }
2885         return explode(',', $result);
2886     }
2888     /**
2889      * Saves setting(s) provided through $data
2890      *
2891      * Potential bug in the works should anyone call with this function
2892      * using a vartype that is not an array
2893      *
2894      * @param array $data
2895      */
2896     public function write_setting($data) {
2897         if (!is_array($data)) {
2898             return ''; //ignore it
2899         }
2900         if (!$this->load_choices() or empty($this->choices)) {
2901             return '';
2902         }
2904         unset($data['xxxxx']);
2906         $save = array();
2907         foreach ($data as $value) {
2908             if (!array_key_exists($value, $this->choices)) {
2909                 continue; // ignore it
2910             }
2911             $save[] = $value;
2912         }
2914         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
2915     }
2917     /**
2918      * Is setting related to query text - used when searching
2919      *
2920      * @param string $query
2921      * @return bool true if related, false if not
2922      */
2923     public function is_related($query) {
2924         if (!$this->load_choices() or empty($this->choices)) {
2925             return false;
2926         }
2927         if (parent::is_related($query)) {
2928             return true;
2929         }
2931         foreach ($this->choices as $desc) {
2932             if (strpos(core_text::strtolower($desc), $query) !== false) {
2933                 return true;
2934             }
2935         }
2936         return false;
2937     }
2939     /**
2940      * Returns XHTML multi-select field
2941      *
2942      * @todo Add vartype handling to ensure $data is an array
2943      * @param array $data Array of values to select by default
2944      * @param string $query
2945      * @return string XHTML multi-select field
2946      */
2947     public function output_html($data, $query='') {
2948         if (!$this->load_choices() or empty($this->choices)) {
2949             return '';
2950         }
2951         $choices = $this->choices;
2952         $default = $this->get_defaultsetting();
2953         if (is_null($default)) {
2954             $default = array();
2955         }
2956         if (is_null($data)) {
2957             $data = array();
2958         }
2960         $defaults = array();
2961         $size = min(10, count($this->choices));
2962         $return = '<div class="form-select"><input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2963         $return .= '<select id="'.$this->get_id().'" name="'.$this->get_full_name().'[]" size="'.$size.'" multiple="multiple">';
2964         foreach ($this->choices as $key => $description) {
2965             if (in_array($key, $data)) {
2966                 $selected = 'selected="selected"';
2967             } else {
2968                 $selected = '';
2969             }
2970             if (in_array($key, $default)) {
2971                 $defaults[] = $description;
2972             }
2974             $return .= '<option value="'.s($key).'" '.$selected.'>'.$description.'</option>';
2975         }
2977         if (is_null($default)) {
2978             $defaultinfo = NULL;
2979         } if (!empty($defaults)) {
2980             $defaultinfo = implode(', ', $defaults);
2981         } else {
2982             $defaultinfo = get_string('none');
2983         }
2985         $return .= '</select></div>';
2986         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, '', $defaultinfo, $query);
2987     }
2990 /**
2991  * Time selector
2992  *
2993  * This is a liiitle bit messy. we're using two selects, but we're returning
2994  * them as an array named after $name (so we only use $name2 internally for the setting)
2995  *
2996  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2997  */
2998 class admin_setting_configtime extends admin_setting {
2999     /** @var string Used for setting second select (minutes) */
3000     public $name2;
3002     /**
3003      * Constructor
3004      * @param string $hoursname setting for hours
3005      * @param string $minutesname setting for hours
3006      * @param string $visiblename localised
3007      * @param string $description long localised info
3008      * @param array $defaultsetting array representing default time 'h'=>hours, 'm'=>minutes
3009      */
3010     public function __construct($hoursname, $minutesname, $visiblename, $description, $defaultsetting) {
3011         $this->name2 = $minutesname;
3012         parent::__construct($hoursname, $visiblename, $description, $defaultsetting);
3013     }
3015     /**
3016      * Get the selected time
3017      *
3018      * @return mixed An array containing 'h'=>xx, 'm'=>xx, or null if not set
3019      */
3020     public function get_setting() {
3021         $result1 = $this->config_read($this->name);
3022         $result2 = $this->config_read($this->name2);
3023         if (is_null($result1) or is_null($result2)) {
3024             return NULL;
3025         }
3027         return array('h' => $result1, 'm' => $result2);
3028     }
3030     /**
3031      * Store the time (hours and minutes)
3032      *
3033      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3034      * @return bool true if success, false if not
3035      */
3036     public function write_setting($data) {
3037         if (!is_array($data)) {
3038             return '';
3039         }
3041         $result = $this->config_write($this->name, (int)$data['h']) && $this->config_write($this->name2, (int)$data['m']);
3042         return ($result ? '' : get_string('errorsetting', 'admin'));
3043     }
3045     /**
3046      * Returns XHTML time select fields
3047      *
3048      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3049      * @param string $query
3050      * @return string XHTML time select fields and wrapping div(s)
3051      */
3052     public function output_html($data, $query='') {
3053         $default = $this->get_defaultsetting();
3055         if (is_array($default)) {
3056             $defaultinfo = $default['h'].':'.$default['m'];
3057         } else {
3058             $defaultinfo = NULL;
3059         }
3061         $return = '<div class="form-time defaultsnext">'.
3062             '<select id="'.$this->get_id().'h" name="'.$this->get_full_name().'[h]">';
3063         for ($i = 0; $i < 24; $i++) {
3064             $return .= '<option value="'.$i.'"'.($i == $data['h'] ? ' selected="selected"' : '').'>'.$i.'</option>';
3065         }
3066         $return .= '</select>:<select id="'.$this->get_id().'m" name="'.$this->get_full_name().'[m]">';
3067         for ($i = 0; $i < 60; $i += 5) {
3068             $return .= '<option value="'.$i.'"'.($i == $data['m'] ? ' selected="selected"' : '').'>'.$i.'</option>';
3069         }
3070         $return .= '</select></div>';
3071         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
3072     }
3077 /**
3078  * Seconds duration setting.
3079  *
3080  * @copyright 2012 Petr Skoda (http://skodak.org)
3081  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3082  */
3083 class admin_setting_configduration extends admin_setting {
3085     /** @var int default duration unit */
3086     protected $defaultunit;
3088     /**
3089      * Constructor
3090      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
3091      *                     or 'myplugin/mysetting' for ones in config_plugins.
3092      * @param string $visiblename localised name
3093      * @param string $description localised long description
3094      * @param mixed $defaultsetting string or array depending on implementation
3095      * @param int $defaultunit - day, week, etc. (in seconds)
3096      */
3097     public function __construct($name, $visiblename, $description, $defaultsetting, $defaultunit = 86400) {
3098         if (is_number($defaultsetting)) {
3099             $defaultsetting = self::parse_seconds($defaultsetting);
3100         }
3101         $units = self::get_units();
3102         if (isset($units[$defaultunit])) {
3103             $this->defaultunit = $defaultunit;
3104         } else {
3105             $this->defaultunit = 86400;
3106         }
3107         parent::__construct($name, $visiblename, $description, $defaultsetting);
3108     }
3110     /**
3111      * Returns selectable units.
3112      * @static
3113      * @return array
3114      */
3115     protected static function get_units() {
3116         return array(
3117             604800 => get_string('weeks'),
3118             86400 => get_string('days'),
3119             3600 => get_string('hours'),
3120             60 => get_string('minutes'),
3121             1 => get_string('seconds'),
3122         );
3123     }
3125     /**
3126      * Converts seconds to some more user friendly string.
3127      * @static
3128      * @param int $seconds
3129      * @return string
3130      */
3131     protected static function get_duration_text($seconds) {
3132         if (empty($seconds)) {
3133             return get_string('none');
3134         }
3135         $data = self::parse_seconds($seconds);
3136         switch ($data['u']) {
3137             case (60*60*24*7):
3138                 return get_string('numweeks', '', $data['v']);
3139             case (60*60*24):
3140                 return get_string('numdays', '', $data['v']);
3141             case (60*60):
3142                 return get_string('numhours', '', $data['v']);
3143             case (60):
3144                 return get_string('numminutes', '', $data['v']);
3145             default:
3146                 return get_string('numseconds', '', $data['v']*$data['u']);
3147         }
3148     }
3150     /**
3151      * Finds suitable units for given duration.
3152      * @static
3153      * @param int $seconds
3154      * @return array
3155      */
3156     protected static function parse_seconds($seconds) {
3157         foreach (self::get_units() as $unit => $unused) {
3158             if ($seconds % $unit === 0) {
3159                 return array('v'=>(int)($seconds/$unit), 'u'=>$unit);
3160             }
3161         }
3162         return array('v'=>(int)$seconds, 'u'=>1);
3163     }
3165     /**
3166      * Get the selected duration as array.
3167      *
3168      * @return mixed An array containing 'v'=>xx, 'u'=>xx, or null if not set
3169      */
3170     public function get_setting() {
3171         $seconds = $this->config_read($this->name);
3172         if (is_null($seconds)) {
3173             return null;
3174         }
3176         return self::parse_seconds($seconds);
3177     }
3179     /**
3180      * Store the duration as seconds.
3181      *
3182      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3183      * @return bool true if success, false if not
3184      */
3185     public function write_setting($data) {
3186         if (!is_array($data)) {
3187             return '';
3188         }
3190         $seconds = (int)($data['v']*$data['u']);
3191         if ($seconds < 0) {
3192             return get_string('errorsetting', 'admin');
3193         }
3195         $result = $this->config_write($this->name, $seconds);
3196         return ($result ? '' : get_string('errorsetting', 'admin'));
3197     }
3199     /**
3200      * Returns duration text+select fields.
3201      *
3202      * @param array $data Must be form 'v'=>xx, 'u'=>xx
3203      * @param string $query
3204      * @return string duration text+select fields and wrapping div(s)
3205      */
3206     public function output_html($data, $query='') {
3207         $default = $this->get_defaultsetting();
3209         if (is_number($default)) {
3210             $defaultinfo = self::get_duration_text($default);
3211         } else if (is_array($default)) {
3212             $defaultinfo = self::get_duration_text($default['v']*$default['u']);
3213         } else {
3214             $defaultinfo = null;
3215         }
3217         $units = self::get_units();
3219         $return = '<div class="form-duration defaultsnext">';
3220         $return .= '<input type="text" size="5" id="'.$this->get_id().'v" name="'.$this->get_full_name().'[v]" value="'.s($data['v']).'" />';
3221         $return .= '<select id="'.$this->get_id().'u" name="'.$this->get_full_name().'[u]">';
3222         foreach ($units as $val => $text) {
3223             $selected = '';
3224             if ($data['v'] == 0) {
3225                 if ($val == $this->defaultunit) {
3226                     $selected = ' selected="selected"';
3227                 }
3228             } else if ($val == $data['u']) {
3229                 $selected = ' selected="selected"';
3230             }
3231             $return .= '<option value="'.$val.'"'.$selected.'>'.$text.'</option>';
3232         }
3233         $return .= '</select></div>';
3234         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
3235     }
3239 /**
3240  * Used to validate a textarea used for ip addresses
3241  *
3242  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3243  */
3244 class admin_setting_configiplist extends admin_setting_configtextarea {
3246     /**
3247      * Validate the contents of the textarea as IP addresses
3248      *
3249      * Used to validate a new line separated list of IP addresses collected from
3250      * a textarea control
3251      *
3252      * @param string $data A list of IP Addresses separated by new lines
3253      * @return mixed bool true for success or string:error on failure
3254      */
3255     public function validate($data) {
3256         if(!empty($data)) {
3257             $ips = explode("\n", $data);
3258         } else {
3259             return true;
3260         }
3261         $result = true;
3262         foreach($ips as $ip) {
3263             $ip = trim($ip);
3264             if (preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}$#', $ip, $match) ||
3265                 preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}(\/\d{1,2})$#', $ip, $match) ||
3266                 preg_match('#^(\d{1,3})(\.\d{1,3}){3}(-\d{1,3})$#', $ip, $match)) {
3267                 $result = true;
3268             } else {
3269                 $result = false;
3270                 break;
3271             }
3272         }
3273         if($result) {
3274             return true;
3275         } else {
3276             return get_string('validateerror', 'admin');
3277         }
3278     }
3282 /**
3283  * An admin setting for selecting one or more users who have a capability
3284  * in the system context
3285  *
3286  * An admin setting for selecting one or more users, who have a particular capability
3287  * in the system context. Warning, make sure the list will never be too long. There is
3288  * no paging or searching of this list.
3289  *
3290  * To correctly get a list of users from this config setting, you need to call the
3291  * get_users_from_config($CFG->mysetting, $capability); function in moodlelib.php.
3292  *
3293  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3294  */
3295 class admin_setting_users_with_capability extends admin_setting_configmultiselect {
3296     /** @var string The capabilities name */
3297     protected $capability;
3298     /** @var int include admin users too */
3299     protected $includeadmins;
3301     /**
3302      * Constructor.
3303      *
3304      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
3305      * @param string $visiblename localised name
3306      * @param string $description localised long description
3307      * @param array $defaultsetting array of usernames
3308      * @param string $capability string capability name.
3309      * @param bool $includeadmins include administrators
3310      */
3311     function __construct($name, $visiblename, $description, $defaultsetting, $capability, $includeadmins = true) {
3312         $this->capability    = $capability;
3313         $this->includeadmins = $includeadmins;
3314         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
3315     }
3317     /**
3318      * Load all of the uses who have the capability into choice array
3319      *
3320      * @return bool Always returns true
3321      */
3322     function load_choices() {
3323         if (is_array($this->choices)) {
3324             return true;
3325         }
3326         list($sort, $sortparams) = users_order_by_sql('u');
3327         if (!empty($sortparams)) {
3328             throw new coding_exception('users_order_by_sql returned some query parameters. ' .
3329                     'This is unexpected, and a problem because there is no way to pass these ' .
3330                     'parameters to get_users_by_capability. See MDL-34657.');
3331         }
3332         $users = get_users_by_capability(context_system::instance(),
3333                 $this->capability, 'u.id,u.username,u.firstname,u.lastname', $sort);
3334         $this->choices = array(
3335             '$@NONE@$' => get_string('nobody'),
3336             '$@ALL@$' => get_string('everyonewhocan', 'admin', get_capability_string($this->capability)),
3337         );
3338         if ($this->includeadmins) {
3339             $admins = get_admins();
3340             foreach ($admins as $user) {
3341                 $this->choices[$user->id] = fullname($user);
3342             }
3343         }
3344         if (is_array($users)) {
3345             foreach ($users as $user) {
3346                 $this->choices[$user->id] = fullname($user);
3347             }
3348         }
3349         return true;
3350     }
3352     /**
3353      * Returns the default setting for class
3354      *
3355      * @return mixed Array, or string. Empty string if no default
3356      */
3357     public function get_defaultsetting() {
3358         $this->load_choices();
3359         $defaultsetting = parent::get_defaultsetting();
3360         if (empty($defaultsetting)) {
3361             return array('$@NONE@$');
3362         } else if (array_key_exists($defaultsetting, $this->choices)) {
3363                 return $defaultsetting;
3364             } else {
3365                 return '';
3366             }
3367     }
3369     /**
3370      * Returns the current setting
3371      *
3372      * @return mixed array or string
3373      */
3374     public function get_setting() {
3375         $result = parent::get_setting();
3376         if ($result === null) {
3377             // this is necessary for settings upgrade
3378             return null;
3379         }
3380         if (empty($result)) {
3381             $result = array('$@NONE@$');
3382         }
3383         return $result;
3384     }
3386     /**
3387      * Save the chosen setting provided as $data
3388      *
3389      * @param array $data
3390      * @return mixed string or array
3391      */
3392     public function write_setting($data) {
3393     // If all is selected, remove any explicit options.
3394         if (in_array('$@ALL@$', $data)) {
3395             $data = array('$@ALL@$');
3396         }
3397         // None never needs to be written to the DB.
3398         if (in_array('$@NONE@$', $data)) {
3399             unset($data[array_search('$@NONE@$', $data)]);
3400         }
3401         return parent::write_setting($data);
3402     }
3406 /**
3407  * Special checkbox for calendar - resets SESSION vars.
3408  *
3409  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3410  */
3411 class admin_setting_special_adminseesall extends admin_setting_configcheckbox {
3412     /**
3413      * Calls the parent::__construct with default values
3414      *
3415      * name =>  calendar_adminseesall
3416      * visiblename => get_string('adminseesall', 'admin')
3417      * description => get_string('helpadminseesall', 'admin')
3418      * defaultsetting => 0
3419      */
3420     public function __construct() {
3421         parent::__construct('calendar_adminseesall', get_string('adminseesall', 'admin'),
3422             get_string('helpadminseesall', 'admin'), '0');
3423     }
3425     /**
3426      * Stores the setting passed in $data
3427      *
3428      * @param mixed gets converted to string for comparison
3429      * @return string empty string or error message
3430      */
3431     public function write_setting($data) {
3432         global $SESSION;
3433         return parent::write_setting($data);
3434     }
3437 /**
3438  * Special select for settings that are altered in setup.php and can not be altered on the fly
3439  *
3440  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3441  */
3442 class admin_setting_special_selectsetup extends admin_setting_configselect {
3443     /**
3444      * Reads the setting directly from the database
3445      *
3446      * @return mixed
3447      */
3448     public function get_setting() {
3449     // read directly from db!
3450         return get_config(NULL, $this->name);
3451     }
3453     /**
3454      * Save the setting passed in $data
3455      *
3456      * @param string $data The setting to save
3457      * @return string empty or error message
3458      */
3459     public function write_setting($data) {
3460         global $CFG;
3461         // do not change active CFG setting!
3462         $current = $CFG->{$this->name};
3463         $result = parent::write_setting($data);
3464         $CFG->{$this->name} = $current;
3465         return $result;
3466     }
3470 /**
3471  * Special select for frontpage - stores data in course table
3472  *
3473  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3474  */
3475 class admin_setting_sitesetselect extends admin_setting_configselect {
3476     /**
3477      * Returns the site name for the selected site
3478      *
3479      * @see get_site()
3480      * @return string The site name of the selected site
3481      */
3482     public function get_setting() {
3483         $site = course_get_format(get_site())->get_course();
3484         return $site->{$this->name};
3485     }
3487     /**
3488      * Updates the database and save the setting
3489      *
3490      * @param string data
3491      * @return string empty or error message
3492      */
3493     public function write_setting($data) {
3494         global $DB, $SITE, $COURSE;
3495         if (!in_array($data, array_keys($this->choices))) {
3496             return get_string('errorsetting', 'admin');
3497         }
3498         $record = new stdClass();
3499         $record->id           = SITEID;
3500         $temp                 = $this->name;
3501         $record->$temp        = $data;
3502         $record->timemodified = time();
3504         course_get_format($SITE)->update_course_format_options($record);
3505         $DB->update_record('course', $record);
3507         // Reset caches.
3508         $SITE = $DB->get_record('course', array('id'=>$SITE->id), '*', MUST_EXIST);
3509         if ($SITE->id == $COURSE->id) {
3510             $COURSE = $SITE;
3511         }
3512         format_base::reset_course_cache($SITE->id);
3514         return '';
3516     }
3520 /**
3521  * Select for blog's bloglevel setting: if set to 0, will set blog_menu
3522  * block to hidden.
3523  *
3524  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3525  */
3526 class admin_setting_bloglevel extends admin_setting_configselect {
3527     /**
3528      * Updates the database and save the setting
3529      *
3530      * @param string data
3531      * @return string empty or error message
3532      */
3533     public function write_setting($data) {
3534         global $DB, $CFG;
3535         if ($data == 0) {
3536             $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 1");
3537             foreach ($blogblocks as $block) {
3538                 $DB->set_field('block', 'visible', 0, array('id' => $block->id));
3539             }
3540         } else {
3541             // reenable all blocks only when switching from disabled blogs
3542             if (isset($CFG->bloglevel) and $CFG->bloglevel == 0) {
3543                 $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 0");
3544                 foreach ($blogblocks as $block) {
3545                     $DB->set_field('block', 'visible', 1, array('id' => $block->id));
3546                 }
3547             }
3548         }
3549         return parent::write_setting($data);
3550     }
3554 /**
3555  * Special select - lists on the frontpage - hacky
3556  *
3557  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3558  */
3559 class admin_setting_courselist_frontpage extends admin_setting {
3560     /** @var array Array of choices value=>label */
3561     public $choices;
3563     /**
3564      * Construct override, requires one param
3565      *
3566      * @param bool $loggedin Is the user logged in
3567      */
3568     public function __construct($loggedin) {
3569         global $CFG;
3570         require_once($CFG->dirroot.'/course/lib.php');
3571         $name        = 'frontpage'.($loggedin ? 'loggedin' : '');
3572         $visiblename = get_string('frontpage'.($loggedin ? 'loggedin' : ''),'admin');
3573         $description = get_string('configfrontpage'.($loggedin ? 'loggedin' : ''),'admin');
3574         $defaults    = array(FRONTPAGEALLCOURSELIST);
3575         parent::__construct($name, $visiblename, $description, $defaults);
3576     }
3578     /**
3579      * Loads the choices available
3580      *
3581      * @return bool always returns true
3582      */
3583     public function load_choices() {
3584         if (is_array($this->choices)) {
3585             return true;
3586         }
3587         $this->choices = array(FRONTPAGENEWS          => get_string('frontpagenews'),
3588             FRONTPAGEALLCOURSELIST => get_string('frontpagecourselist'),
3589             FRONTPAGEENROLLEDCOURSELIST => get_string('frontpageenrolledcourselist'),
3590             FRONTPAGECATEGORYNAMES => get_string('frontpagecategorynames'),
3591             FRONTPAGECATEGORYCOMBO => get_string('frontpagecategorycombo'),
3592             FRONTPAGECOURSESEARCH  => get_string('frontpagecoursesearch'),
3593             'none'                 => get_string('none'));
3594         if ($this->name === 'frontpage') {
3595             unset($this->choices[FRONTPAGEENROLLEDCOURSELIST]);
3596         }
3597         return true;
3598     }
3600     /**
3601      * Returns the selected settings
3602      *
3603      * @param mixed array or setting or null
3604      */
3605     public function get_setting() {
3606         $result = $this->config_read($this->name);
3607         if (is_null($result)) {
3608             return NULL;
3609         }
3610         if ($result === '') {
3611             return array();
3612         }
3613         return explode(',', $result);
3614     }
3616     /**
3617      * Save the selected options
3618      *
3619      * @param array $data
3620      * @return mixed empty string (data is not an array) or bool true=success false=failure
3621      */
3622     public function write_setting($data) {
3623         if (!is_array($data)) {
3624             return '';
3625         }
3626         $this->load_choices();
3627         $save = array();
3628         foreach($data as $datum) {
3629             if ($datum == 'none' or !array_key_exists($datum, $this->choices)) {
3630                 continue;
3631             }
3632             $save[$datum] = $datum; // no duplicates
3633         }
3634         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
3635     }
3637     /**
3638      * Return XHTML select field and wrapping div
3639      *
3640      * @todo Add vartype handling to make sure $data is an array
3641      * @param array $data Array of elements to select by default
3642      * @return string XHTML select field and wrapping div
3643      */
3644     public function output_html($data, $query='') {
3645         $this->load_choices();
3646         $currentsetting = array();
3647         foreach ($data as $key) {
3648             if ($key != 'none' and array_key_exists($key, $this->choices)) {
3649                 $currentsetting[] = $key; // already selected first
3650             }
3651         }
3653         $return = '<div class="form-group">';
3654         for ($i = 0; $i < count($this->choices) - 1; $i++) {
3655             if (!array_key_exists($i, $currentsetting)) {
3656                 $currentsetting[$i] = 'none'; //none
3657             }
3658             $return .='<select class="form-select" id="'.$this->get_id().$i.'" name="'.$this->get_full_name().'[]">';
3659             foreach ($this->choices as $key => $value) {
3660                 $return .= '<option value="'.$key.'"'.("$key" == $currentsetting[$i] ? ' selected="selected"' : '').'>'.$value.'</option>';
3661             }
3662             $return .= '</select>';
3663             if ($i !== count($this->choices) - 2) {
3664                 $return .= '<br />';
3665             }
3666         }
3667         $return .= '</div>';
3669         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
3670     }
3674 /**
3675  * Special checkbox for frontpage - stores data in course table
3676  *
3677  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3678  */
3679 class admin_setting_sitesetcheckbox extends admin_setting_configcheckbox {
3680     /**
3681      * Returns the current sites name
3682      *
3683      * @return string
3684      */
3685     public function get_setting() {
3686         $site = course_get_format(get_site())->get_course();
3687         return $site->{$this->name};
3688     }
3690     /**
3691      * Save the selected setting
3692      *
3693      * @param string $data The selected site
3694      * @return string empty string or error message
3695      */
3696     public function write_setting($data) {
3697         global $DB, $SITE, $COURSE;
3698         $record = new stdClass();
3699         $record->id            = $SITE->id;
3700         $record->{$this->name} = ($data == '1' ? 1 : 0);
3701         $record->timemodified  = time();
3703         course_get_format($SITE)->update_course_format_options($record);
3704         $DB->update_record('course', $record);
3706         // Reset caches.
3707         $SITE = $DB->get_record('course', array('id'=>$SITE->id), '*', MUST_EXIST);
3708         if ($SITE->id == $COURSE->id) {
3709             $COURSE = $SITE;
3710         }
3711         format_base::reset_course_cache($SITE->id);
3713         return '';
3714     }
3717 /**
3718  * Special text for frontpage - stores data in course table.
3719  * Empty string means not set here. Manual setting is required.
3720  *
3721  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3722  */
3723 class admin_setting_sitesettext extends admin_setting_configtext {
3724     /**
3725      * Return the current setting
3726      *
3727      * @return mixed string or null
3728      */
3729     public function get_setting() {
3730         $site = course_get_format(get_site())->get_course();
3731         return $site->{$this->name} != '' ? $site->{$this->name} : NULL;
3732     }
3734     /**
3735      * Validate the selected data
3736      *
3737      * @param string $data The selected value to validate
3738      * @return mixed true or message string
3739      */
3740     public function validate($data) {
3741         $cleaned = clean_param($data, PARAM_TEXT);
3742         if ($cleaned === '') {
3743             return get_string('required');
3744         }
3745         if ("$data" == "$cleaned") { // implicit conversion to string is needed to do exact comparison
3746             return true;
3747         } else {
3748             return get_string('validateerror', 'admin');
3749         }
3750     }
3752     /**
3753      * Save the selected setting
3754      *
3755      * @param string $data The selected value
3756      * @return string empty or error message
3757      */
3758     public function write_setting($data) {
3759         global $DB, $SITE, $COURSE;
3760         $data = trim($data);
3761         $validated = $this->validate($data);
3762         if ($validated !== true) {
3763             return $validated;
3764         }
3766         $record = new stdClass();
3767         $record->id            = $SITE->id;
3768         $record->{$this->name} = $data;
3769         $record->timemodified  = time();
3771         course_get_format($SITE)->update_course_format_options($record);
3772         $DB->update_record('course', $record);
3774         // Reset caches.
3775         $SITE = $DB->get_record('course', array('id'=>$SITE->id), '*', MUST_EXIST);
3776         if ($SITE->id == $COURSE->id) {
3777             $COURSE = $SITE;
3778         }
3779         format_base::reset_course_cache($SITE->id);
3781         return '';
3782     }
3786 /**
3787  * Special text editor for site description.
3788  *
3789  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3790  */
3791 class admin_setting_special_frontpagedesc extends admin_setting {
3792     /**
3793      * Calls parent::__construct with specific arguments
3794      */
3795     public function __construct() {
3796         parent::__construct('summary', get_string('frontpagedescription'), get_string('frontpagedescriptionhelp'), NULL);
3797         editors_head_setup();
3798     }
3800     /**
3801      * Return the current setting
3802      * @return string The current setting
3803      */
3804     public function get_setting() {
3805         $site = course_get_format(get_site())->get_course();
3806         return $site->{$this->name};
3807     }
3809     /**
3810      * Save the new setting
3811      *
3812      * @param string $data The new value to save
3813      * @return string empty or error message
3814      */
3815     public function write_setting($data) {
3816         global $DB, $SITE, $COURSE;
3817         $record = new stdClass();
3818         $record->id            = $SITE->id;
3819         $record->{$this->name} = $data;
3820         $record->timemodified  = time();
3822         course_get_format($SITE)->update_course_format_options($record);
3823         $DB->update_record('course', $record);
3825         // Reset caches.
3826         $SITE = $DB->get_record('course', array('id'=>$SITE->id), '*', MUST_EXIST);
3827         if ($SITE->id == $COURSE->id) {
3828             $COURSE = $SITE;
3829         }
3830         format_base::reset_course_cache($SITE->id);
3832         return '';
3833     }
3835     /**
3836      * Returns XHTML for the field plus wrapping div
3837      *
3838      * @param string $data The current value
3839      * @param string $query
3840      * @return string The XHTML output
3841      */
3842     public function output_html($data, $query='') {
3843         global $CFG;
3845         $CFG->adminusehtmleditor = can_use_html_editor();
3846         $return = '<div class="form-htmlarea">'.print_textarea($CFG->adminusehtmleditor, 15, 60, 0, 0, $this->get_full_name(), $data, 0, true, 'summary') .'</div>';
3848         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
3849     }
3853 /**
3854  * Administration interface for emoticon_manager settings.
3855  *
3856  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3857  */
3858 class admin_setting_emoticons extends admin_setting {
3860     /**
3861      * Calls parent::__construct with specific args
3862      */
3863     public function __construct() {
3864         global $CFG;
3866         $manager = get_emoticon_manager();
3867         $defaults = $this->prepare_form_data($manager->default_emoticons());
3868         parent::__construct('emoticons', get_string('emoticons', 'admin'), get_string('emoticons_desc', 'admin'), $defaults);
3869     }
3871     /**
3872      * Return the current setting(s)
3873      *
3874      * @return array Current settings array
3875      */
3876     public function get_setting() {
3877         global $CFG;
3879         $manager = get_emoticon_manager();
3881         $config = $this->config_read($this->name);
3882         if (is_null($config)) {
3883             return null;
3884         }
3886         $config = $manager->decode_stored_config($config);
3887         if (is_null($config)) {
3888             return null;
3889         }
3891         return $this->prepare_form_data($config);
3892     }
3894     /**
3895      * Save selected settings
3896      *
3897      * @param array $data Array of settings to save
3898      * @return bool
3899      */
3900     public function write_setting($data) {
3902         $manager = get_emoticon_manager();
3903         $emoticons = $this->process_form_data($data);
3905         if ($emoticons === false) {
3906             return false;
3907         }
3909         if ($this->config_write($this->name, $manager->encode_stored_config($emoticons))) {
3910             return ''; // success
3911         } else {
3912             return get_string('errorsetting', 'admin') . $this->visiblename . html_writer::empty_tag('br');
3913         }
3914     }
3916     /**
3917      * Return XHTML field(s) for options
3918      *
3919      * @param array $data Array of options to set in HTML
3920      * @return string XHTML string for the fields and wrapping div(s)
3921      */
3922     public function output_html($data, $query='') {
3923         global $OUTPUT;
3925         $out  = html_writer::start_tag('table', array('id' => 'emoticonsetting', 'class' => 'admintable generaltable'));
3926         $out .= html_writer::start_tag('thead');
3927         $out .= html_writer::start_tag('tr');
3928         $out .= html_writer::tag('th', get_string('emoticontext', 'admin'));
3929         $out .= html_writer::tag('th', get_string('emoticonimagename', 'admin'));
3930         $out .= html_writer::tag('th', get_string('emoticoncomponent', 'admin'));
3931         $out .= html_writer::tag('th', get_string('emoticonalt', 'admin'), array('colspan' => 2));
3932         $out .= html_writer::tag('th', '');
3933         $out .= html_writer::end_tag('tr');
3934         $out .= html_writer::end_tag('thead');
3935         $out .= html_writer::start_tag('tbody');
3936         $i = 0;
3937         foreach($data as $field => $value) {
3938             switch ($i) {
3939             case 0:
3940                 $out .= html_writer::start_tag('tr');
3941                 $current_text = $value;
3942                 $current_filename = '';
3943                 $current_imagecomponent = '';
3944                 $current_altidentifier = '';
3945                 $current_altcomponent = '';
3946             case 1:
3947                 $current_filename = $value;
3948             case 2:
3949                 $current_imagecomponent = $value;
3950             case 3:
3951                 $current_altidentifier = $value;
3952             case 4:
3953                 $current_altcomponent = $value;
3954             }
3956             $out .= html_writer::tag('td',
3957                 html_writer::empty_tag('input',
3958                     array(
3959                         'type'  => 'text',
3960                         'class' => 'form-text',
3961                         'name'  => $this->get_full_name().'['.$field.']',
3962                         'value' => $value,
3963                     )
3964                 ), array('class' => 'c'.$i)
3965             );
3967             if ($i == 4) {
3968                 if (get_string_manager()->string_exists($current_altidentifier, $current_altcomponent)) {
3969                     $alt = get_string($current_altidentifier, $current_altcomponent);
3970                 } else {
3971                     $alt = $current_text;
3972                 }
3973                 if ($current_filename) {
3974                     $out .= html_writer::tag('td', $OUTPUT->render(new pix_emoticon($current_filename, $alt, $current_imagecomponent)));
3975                 } else {
3976                     $out .= html_writer::tag('td', '');
3977                 }
3978                 $out .= html_writer::end_tag('tr');
3979                 $i = 0;
3980             } else {
3981                 $i++;
3982             }
3984         }
3985         $out .= html_writer::end_tag('tbody');
3986         $out .= html_writer::end_tag('table');
3987         $out  = html_writer::tag('div', $out, array('class' => 'form-group'));
3988         $out .= html_writer::tag('div', html_writer::link(new moodle_url('/admin/resetemoticons.php'), get_string('emoticonsreset', 'admin')));
3990         return format_admin_setting($this, $this->visiblename, $out, $this->description, false, '', NULL, $query);
3991     }
3993     /**
3994      * Converts the array of emoticon objects provided by {@see emoticon_manager} into admin settings form data
3995      *
3996      * @see self::process_form_data()
3997      * @param array $emoticons array of emoticon objects as returned by {@see emoticon_manager}
3998      * @return array of form fields and their values
3999      */
4000     protected function prepare_form_data(array $emoticons) {
4002         $form = array();
4003         $i = 0;
4004         foreach ($emoticons as $emoticon) {
4005             $form['text'.$i]            = $emoticon->text;
4006             $form['imagename'.$i]       = $emoticon->imagename;
4007             $form['imagecomponent'.$i]  = $emoticon->imagecomponent;
4008             $form['altidentifier'.$i]   = $emoticon->altidentifier;
4009             $form['altcomponent'.$i]    = $emoticon->altcomponent;
4010             $i++;
4011         }
4012         // add one more blank field set for new object
4013         $form['text'.$i]            = '';
4014         $form['imagename'.$i]       = '';
4015         $form['imagecomponent'.$i]  = '';
4016         $form['altidentifier'.$i]   = '';
4017         $form['altcomponent'.$i]    = '';
4019         return $form;
4020     }
4022     /**
4023      * Converts the data from admin settings form into an array of emoticon objects
4024      *
4025      * @see self::prepare_form_data()
4026      * @param array $data array of admin form fields and values
4027      * @return false|array of emoticon objects
4028      */
4029     protected function process_form_data(array $form) {
4031         $count = count($form); // number of form field values
4033         if ($count % 5) {
4034             // we must get five fields per emoticon object
4035             return false;
4036         }
4038         $emoticons = array();
4039         for ($i = 0; $i < $count / 5; $i++) {
4040             $emoticon                   = new stdClass();
4041             $emoticon->text             = clean_param(trim($form['text'.$i]), PARAM_NOTAGS);
4042             $emoticon->imagename        = clean_param(trim($form['imagename'.$i]), PARAM_PATH);
4043             $emoticon->imagecomponent   = clean_param(trim($form['imagecomponent'.$i]), PARAM_COMPONENT);
4044             $emoticon->altidentifier    = clean_param(trim($form['altidentifier'.$i]), PARAM_STRINGID);
4045             $emoticon->altcomponent     = clean_param(trim($form['altcomponent'.$i]), PARAM_COMPONENT);
4047             if (strpos($emoticon->text, ':/') !== false or strpos($emoticon->text, '//') !== false) {
4048                 // prevent from breaking http://url.addresses by accident
4049                 $emoticon->text = '';
4050             }
4052             if (strlen($emoticon->text) < 2) {
4053                 // do not allow single character emoticons
4054                 $emoticon->text = '';
4055             }
4057             if (preg_match('/^[a-zA-Z]+[a-zA-Z0-9]*$/', $emoticon->text)) {
4058                 // emoticon text must contain some non-alphanumeric character to prevent
4059                 // breaking HTML tags
4060                 $emoticon->text = '';
4061             }
4063             if ($emoticon->text !== '' and $emoticon->imagename !== '' and $emoticon->imagecomponent !== '') {
4064                 $emoticons[] = $emoticon;
4065             }
4066         }
4067         return $emoticons;
4068     }
4072 /**
4073  * Special setting for limiting of the list of available languages.
4074  *
4075  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4076  */
4077 class admin_setting_langlist extends admin_setting_configtext {
4078     /**
4079      * Calls parent::__construct with specific arguments
4080      */
4081     public function __construct() {
4082         parent::__construct('langlist', get_string('langlist', 'admin'), get_string('configlanglist', 'admin'), '', PARAM_NOTAGS);
4083     }
4085     /**
4086      * Save the new setting
4087      *
4088      * @param string $data The new setting
4089      * @return bool
4090      */
4091     public function write_setting($data) {
4092         $return = parent::write_setting($data);
4093         get_string_manager()->reset_caches();
4094         return $return;
4095     }
4099 /**
4100  * Selection of one of the recognised countries using the list
4101  * returned by {@link get_list_of_countries()}.
4102  *
4103  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4104  */
4105 class admin_settings_country_select extends admin_setting_configselect {
4106     protected $includeall;
4107     public function __construct($name, $visiblename, $description, $defaultsetting, $includeall=false) {
4108         $this->includeall = $includeall;
4109         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
4110     }
4112     /**
4113      * Lazy-load the available choices for the select box
4114      */
4115     public function load_choices() {
4116         global $CFG;
4117         if (is_array($this->choices)) {
4118             return true;
4119         }
4120         $this->choices = array_merge(
4121                 array('0' => get_string('choosedots')),
4122                 get_string_manager()->get_list_of_countries($this->includeall));
4123         return true;
4124     }
4128 /**
4129  * admin_setting_configselect for the default number of sections in a course,
4130  * simply so we can lazy-load the choices.
4131  *
4132  * @copyright 2011 The Open University
4133  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4134  */
4135 class admin_settings_num_course_sections extends admin_setting_configselect {
4136     public function __construct($name, $visiblename, $description, $defaultsetting) {
4137         parent::__construct($name, $visiblename, $description, $defaultsetting, array());
4138     }
4140     /** Lazy-load the available choices for the select box */
4141     public function load_choices() {
4142         $max = get_config('moodlecourse', 'maxsections');
4143         if (!isset($max) || !is_numeric($max)) {
4144             $max = 52;
4145         }
4146         for ($i = 0; $i <= $max; $i++) {
4147             $this->choices[$i] = "$i";
4148         }
4149         return true;
4150     }
4154 /**
4155  * Course category selection
4156  *
4157  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4158  */
4159 class admin_settings_coursecat_select extends admin_setting_configselect {
4160     /**
4161      * Calls parent::__construct with specific arguments
4162      */
4163     public function __construct($name, $visiblename, $description, $defaultsetting) {
4164         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
4165     }
4167     /**
4168      * Load the available choices for the select box
4169      *
4170      * @return bool
4171      */
4172     public function load_choices() {
4173         global $CFG;
4174         require_once($CFG->dirroot.'/course/lib.php');
4175         if (is_array($this->choices)) {
4176             return true;
4177         }
4178         $this->choices = make_categories_options();
4179         return true;
4180     }
4184 /**
4185  * Special control for selecting days to backup
4186  *
4187  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4188  */
4189 class admin_setting_special_backupdays extends admin_setting_configmulticheckbox2 {
4190     /**
4191      * Calls parent::__construct with specific arguments
4192      */
4193     public function __construct() {
4194         parent::__construct('backup_auto_weekdays', get_string('automatedbackupschedule','backup'), get_string('automatedbackupschedulehelp','backup'), array(), NULL);
4195         $this->plugin = 'backup';
4196     }
4198     /**
4199      * Load the available choices for the select box
4200      *
4201      * @return bool Always returns true
4202      */
4203     public function load_choices() {
4204         if (is_array($this->choices)) {
4205             return true;
4206         }
4207         $this->choices = array();
4208         $days = array('sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday');
4209         foreach ($days as $day) {
4210             $this->choices[$day] = get_string($day, 'calendar');
4211         }
4212         return true;
4213     }
4217 /**
4218  * Special debug setting
4219  *
4220  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4221  */
4222 class admin_setting_special_debug extends admin_setting_configselect {
4223     /**
4224      * Calls parent::__construct with specific arguments
4225      */
4226     public function __construct() {
4227         parent::__construct('debug', get_string('debug', 'admin'), get_string('configdebug', 'admin'), DEBUG_NONE, NULL);
4228     }
4230     /**
4231      * Load the available choices for the select box
4232      *
4233      * @return bool
4234      */
4235     public function load_choices() {
4236         if (is_array($this->choices)) {
4237             return true;
4238         }
4239         $this->choices = array(DEBUG_NONE      => get_string('debugnone', 'admin'),
4240             DEBUG_MINIMAL   => get_string('debugminimal', 'admin'),
4241             DEBUG_NORMAL    => get_string('debugnormal', 'admin'),
4242             DEBUG_ALL       => get_string('debugall', 'admin'),
4243             DEBUG_DEVELOPER => get_string('debugdeveloper', 'admin'));
4244         return true;
4245     }
4249 /**
4250  * Special admin control
4251  *
4252  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4253  */
4254 class admin_setting_special_calendar_weekend extends admin_setting {
4255     /**
4256      * Calls parent::__construct with specific arguments
4257      */
4258     public function __construct() {
4259         $name = 'calendar_weekend';
4260         $visiblename = get_string('calendar_weekend', 'admin');
4261         $description = get_string('helpweekenddays', 'admin');
4262         $default = array ('0', '6'); // Saturdays and Sundays
4263         parent::__construct($name, $visiblename, $description, $default);
4264     }
4266     /**
4267      * Gets the current settings as an array
4268      *
4269      * @return mixed Null if none, else array of settings
4270      */
4271     public function get_setting() {
4272         $result = $this->config_read($this->name);
4273         if (is_null($result)) {
4274             return NULL;
4275         }
4276         if ($result === '') {
4277             return array();
4278         }
4279         $settings = array();
4280         for ($i=0; $i<7; $i++) {
4281             if ($result & (1 << $i)) {
4282                 $settings[] = $i;
4283             }
4284         }
4285         return $settings;
4286     }
4288     /**
4289      * Save the new settings
4290      *
4291      * @param array $data Array of new settings
4292      * @return bool
4293      */
4294     public function write_setting($data) {
4295         if (!is_array($data)) {
4296             return '';
4297         }
4298         unset($data['xxxxx']);
4299         $result = 0;
4300         foreach($data as $index) {
4301             $result |= 1 << $index;
4302         }
4303         return ($this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin'));
4304     }
4306     /**
4307      * Return XHTML to display the control
4308      *
4309      * @param array $data array of selected days
4310      * @param string $query
4311      * @return string XHTML for display (field + wrapping div(s)
4312      */
4313     public function output_html($data, $query='') {
4314     // The order matters very much because of the implied numeric keys
4315         $days = array('sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday');
4316         $return = '<table><thead><tr>';
4317         $return .= '<input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
4318         foreach($days as $index => $day) {
4319             $return .= '<td><label for="'.$this->get_id().$index.'">'.get_string($day, 'calendar').'</label></td>';
4320         }
4321         $return .= '</tr></thead><tbody><tr>';
4322         foreach($days as $index => $day) {
4323             $return .= '<td><input type="checkbox" class="form-checkbox" id="'.$this->get_id().$index.'" name="'.$this->get_full_name().'[]" value="'.$index.'" '.(in_array("$index", $data) ? 'checked="checked"' : '').' /></td>';
4324         }
4325         $return .= '</tr></tbody></table>';
4327         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
4329     }
4333 /**
4334  * Admin setting that allows a user to pick a behaviour.
4335  *
4336  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4337  */
4338 class admin_setting_question_behaviour extends admin_setting_configselect {
4339     /**
4340      * @param string $name name of config variable
4341      * @param string $visiblename display name
4342      * @param string $description description
4343      * @param string $default default.
4344      */
4345     public function __construct($name, $visiblename, $description, $default) {