MDL-42078 multiple uninstall improvements and cleanup
[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;
128     // This may take a long time.
129     @set_time_limit(0);
131     // Recursively uninstall all subplugins first.
132     $subplugintypes = core_component::get_plugin_types_with_subplugins();
133     if (isset($subplugintypes[$type])) {
134         $base = core_component::get_plugin_directory($type, $name);
135         if (file_exists("$base/db/subplugins.php")) {
136             $subplugins = array();
137             include("$base/db/subplugins.php");
138             foreach ($subplugins as $subplugintype=>$dir) {
139                 $instances = core_component::get_plugin_list($subplugintype);
140                 foreach ($instances as $subpluginname => $notusedpluginpath) {
141                     uninstall_plugin($subplugintype, $subpluginname);
142                 }
143             }
144         }
146     }
148     $component = $type . '_' . $name;  // eg. 'qtype_multichoice' or 'workshopgrading_accumulative' or 'mod_forum'
150     if ($type === 'mod') {
151         $pluginname = $name;  // eg. 'forum'
152         if (get_string_manager()->string_exists('modulename', $component)) {
153             $strpluginname = get_string('modulename', $component);
154         } else {
155             $strpluginname = $component;
156         }
158     } else {
159         $pluginname = $component;
160         if (get_string_manager()->string_exists('pluginname', $component)) {
161             $strpluginname = get_string('pluginname', $component);
162         } else {
163             $strpluginname = $component;
164         }
165     }
167     echo $OUTPUT->heading($pluginname);
169     // Custom plugin uninstall.
170     $plugindirectory = core_component::get_plugin_directory($type, $name);
171     $uninstalllib = $plugindirectory . '/db/uninstall.php';
172     if (file_exists($uninstalllib)) {
173         require_once($uninstalllib);
174         $uninstallfunction = 'xmldb_' . $pluginname . '_uninstall';    // eg. 'xmldb_workshop_uninstall()'
175         if (function_exists($uninstallfunction)) {
176             // Do not verify result, let plugin complain if necessary.
177             $uninstallfunction();
178         }
179     }
181     // Specific plugin type cleanup.
182     $plugininfo = core_plugin_manager::instance()->get_plugin_info($component);
183     if ($plugininfo) {
184         $plugininfo->uninstall_cleanup();
185         core_plugin_manager::reset_caches();
186     }
187     $plugininfo = null;
189     // perform clean-up task common for all the plugin/subplugin types
191     //delete the web service functions and pre-built services
192     require_once($CFG->dirroot.'/lib/externallib.php');
193     external_delete_descriptions($component);
195     // delete calendar events
196     $DB->delete_records('event', array('modulename' => $pluginname));
198     // delete all the logs
199     $DB->delete_records('log', array('module' => $pluginname));
201     // delete log_display information
202     $DB->delete_records('log_display', array('component' => $component));
204     // delete the module configuration records
205     unset_all_config_for_plugin($component);
206     if ($type === 'mod') {
207         unset_all_config_for_plugin($pluginname);
208     }
210     // delete message provider
211     message_provider_uninstall($component);
213     // delete the plugin tables
214     $xmldbfilepath = $plugindirectory . '/db/install.xml';
215     drop_plugin_tables($component, $xmldbfilepath, false);
216     if ($type === 'mod' or $type === 'block') {
217         // non-frankenstyle table prefixes
218         drop_plugin_tables($name, $xmldbfilepath, false);
219     }
221     // delete the capabilities that were defined by this module
222     capabilities_cleanup($component);
224     // remove event handlers and dequeue pending events
225     events_uninstall($component);
227     // Delete all remaining files in the filepool owned by the component.
228     $fs = get_file_storage();
229     $fs->delete_component_files($component);
231     // Finally purge all caches.
232     purge_all_caches();
234     // Invalidate the hash used for upgrade detections.
235     set_config('allversionshash', '');
237     echo $OUTPUT->notification(get_string('success'), 'notifysuccess');
240 /**
241  * Returns the version of installed component
242  *
243  * @param string $component component name
244  * @param string $source either 'disk' or 'installed' - where to get the version information from
245  * @return string|bool version number or false if the component is not found
246  */
247 function get_component_version($component, $source='installed') {
248     global $CFG, $DB;
250     list($type, $name) = core_component::normalize_component($component);
252     // moodle core or a core subsystem
253     if ($type === 'core') {
254         if ($source === 'installed') {
255             if (empty($CFG->version)) {
256                 return false;
257             } else {
258                 return $CFG->version;
259             }
260         } else {
261             if (!is_readable($CFG->dirroot.'/version.php')) {
262                 return false;
263             } else {
264                 $version = null; //initialize variable for IDEs
265                 include($CFG->dirroot.'/version.php');
266                 return $version;
267             }
268         }
269     }
271     // activity module
272     if ($type === 'mod') {
273         if ($source === 'installed') {
274             if ($CFG->version < 2013092001.02) {
275                 return $DB->get_field('modules', 'version', array('name'=>$name));
276             } else {
277                 return get_config('mod_'.$name, 'version');
278             }
280         } else {
281             $mods = core_component::get_plugin_list('mod');
282             if (empty($mods[$name]) or !is_readable($mods[$name].'/version.php')) {
283                 return false;
284             } else {
285                 $plugin = new stdClass();
286                 $plugin->version = null;
287                 $module = $plugin;
288                 include($mods[$name].'/version.php');
289                 return $plugin->version;
290             }
291         }
292     }
294     // block
295     if ($type === 'block') {
296         if ($source === 'installed') {
297             return $DB->get_field('block', 'version', array('name'=>$name));
298         } else {
299             $blocks = core_component::get_plugin_list('block');
300             if (empty($blocks[$name]) or !is_readable($blocks[$name].'/version.php')) {
301                 return false;
302             } else {
303                 $plugin = new stdclass();
304                 include($blocks[$name].'/version.php');
305                 return $plugin->version;
306             }
307         }
308     }
310     // all other plugin types
311     if ($source === 'installed') {
312         return get_config($type.'_'.$name, 'version');
313     } else {
314         $plugins = core_component::get_plugin_list($type);
315         if (empty($plugins[$name])) {
316             return false;
317         } else {
318             $plugin = new stdclass();
319             include($plugins[$name].'/version.php');
320             return $plugin->version;
321         }
322     }
325 /**
326  * Delete all plugin tables
327  *
328  * @param string $name Name of plugin, used as table prefix
329  * @param string $file Path to install.xml file
330  * @param bool $feedback defaults to true
331  * @return bool Always returns true
332  */
333 function drop_plugin_tables($name, $file, $feedback=true) {
334     global $CFG, $DB;
336     // first try normal delete
337     if (file_exists($file) and $DB->get_manager()->delete_tables_from_xmldb_file($file)) {
338         return true;
339     }
341     // then try to find all tables that start with name and are not in any xml file
342     $used_tables = get_used_table_names();
344     $tables = $DB->get_tables();
346     /// Iterate over, fixing id fields as necessary
347     foreach ($tables as $table) {
348         if (in_array($table, $used_tables)) {
349             continue;
350         }
352         if (strpos($table, $name) !== 0) {
353             continue;
354         }
356         // found orphan table --> delete it
357         if ($DB->get_manager()->table_exists($table)) {
358             $xmldb_table = new xmldb_table($table);
359             $DB->get_manager()->drop_table($xmldb_table);
360         }
361     }
363     return true;
366 /**
367  * Returns names of all known tables == tables that moodle knows about.
368  *
369  * @return array Array of lowercase table names
370  */
371 function get_used_table_names() {
372     $table_names = array();
373     $dbdirs = get_db_directories();
375     foreach ($dbdirs as $dbdir) {
376         $file = $dbdir.'/install.xml';
378         $xmldb_file = new xmldb_file($file);
380         if (!$xmldb_file->fileExists()) {
381             continue;
382         }
384         $loaded    = $xmldb_file->loadXMLStructure();
385         $structure = $xmldb_file->getStructure();
387         if ($loaded and $tables = $structure->getTables()) {
388             foreach($tables as $table) {
389                 $table_names[] = strtolower($table->getName());
390             }
391         }
392     }
394     return $table_names;
397 /**
398  * Returns list of all directories where we expect install.xml files
399  * @return array Array of paths
400  */
401 function get_db_directories() {
402     global $CFG;
404     $dbdirs = array();
406     /// First, the main one (lib/db)
407     $dbdirs[] = $CFG->libdir.'/db';
409     /// Then, all the ones defined by core_component::get_plugin_types()
410     $plugintypes = core_component::get_plugin_types();
411     foreach ($plugintypes as $plugintype => $pluginbasedir) {
412         if ($plugins = core_component::get_plugin_list($plugintype)) {
413             foreach ($plugins as $plugin => $plugindir) {
414                 $dbdirs[] = $plugindir.'/db';
415             }
416         }
417     }
419     return $dbdirs;
422 /**
423  * Try to obtain or release the cron lock.
424  * @param string  $name  name of lock
425  * @param int  $until timestamp when this lock considered stale, null means remove lock unconditionally
426  * @param bool $ignorecurrent ignore current lock state, usually extend previous lock, defaults to false
427  * @return bool true if lock obtained
428  */
429 function set_cron_lock($name, $until, $ignorecurrent=false) {
430     global $DB;
431     if (empty($name)) {
432         debugging("Tried to get a cron lock for a null fieldname");
433         return false;
434     }
436     // remove lock by force == remove from config table
437     if (is_null($until)) {
438         set_config($name, null);
439         return true;
440     }
442     if (!$ignorecurrent) {
443         // read value from db - other processes might have changed it
444         $value = $DB->get_field('config', 'value', array('name'=>$name));
446         if ($value and $value > time()) {
447             //lock active
448             return false;
449         }
450     }
452     set_config($name, $until);
453     return true;
456 /**
457  * Test if and critical warnings are present
458  * @return bool
459  */
460 function admin_critical_warnings_present() {
461     global $SESSION;
463     if (!has_capability('moodle/site:config', context_system::instance())) {
464         return 0;
465     }
467     if (!isset($SESSION->admin_critical_warning)) {
468         $SESSION->admin_critical_warning = 0;
469         if (is_dataroot_insecure(true) === INSECURE_DATAROOT_ERROR) {
470             $SESSION->admin_critical_warning = 1;
471         }
472     }
474     return $SESSION->admin_critical_warning;
477 /**
478  * Detects if float supports at least 10 decimal digits
479  *
480  * Detects if float supports at least 10 decimal digits
481  * and also if float-->string conversion works as expected.
482  *
483  * @return bool true if problem found
484  */
485 function is_float_problem() {
486     $num1 = 2009010200.01;
487     $num2 = 2009010200.02;
489     return ((string)$num1 === (string)$num2 or $num1 === $num2 or $num2 <= (string)$num1);
492 /**
493  * Try to verify that dataroot is not accessible from web.
494  *
495  * Try to verify that dataroot is not accessible from web.
496  * It is not 100% correct but might help to reduce number of vulnerable sites.
497  * Protection from httpd.conf and .htaccess is not detected properly.
498  *
499  * @uses INSECURE_DATAROOT_WARNING
500  * @uses INSECURE_DATAROOT_ERROR
501  * @param bool $fetchtest try to test public access by fetching file, default false
502  * @return mixed empty means secure, INSECURE_DATAROOT_ERROR found a critical problem, INSECURE_DATAROOT_WARNING might be problematic
503  */
504 function is_dataroot_insecure($fetchtest=false) {
505     global $CFG;
507     $siteroot = str_replace('\\', '/', strrev($CFG->dirroot.'/')); // win32 backslash workaround
509     $rp = preg_replace('|https?://[^/]+|i', '', $CFG->wwwroot, 1);
510     $rp = strrev(trim($rp, '/'));
511     $rp = explode('/', $rp);
512     foreach($rp as $r) {
513         if (strpos($siteroot, '/'.$r.'/') === 0) {
514             $siteroot = substr($siteroot, strlen($r)+1); // moodle web in subdirectory
515         } else {
516             break; // probably alias root
517         }
518     }
520     $siteroot = strrev($siteroot);
521     $dataroot = str_replace('\\', '/', $CFG->dataroot.'/');
523     if (strpos($dataroot, $siteroot) !== 0) {
524         return false;
525     }
527     if (!$fetchtest) {
528         return INSECURE_DATAROOT_WARNING;
529     }
531     // now try all methods to fetch a test file using http protocol
533     $httpdocroot = str_replace('\\', '/', strrev($CFG->dirroot.'/'));
534     preg_match('|(https?://[^/]+)|i', $CFG->wwwroot, $matches);
535     $httpdocroot = $matches[1];
536     $datarooturl = $httpdocroot.'/'. substr($dataroot, strlen($siteroot));
537     make_upload_directory('diag');
538     $testfile = $CFG->dataroot.'/diag/public.txt';
539     if (!file_exists($testfile)) {
540         file_put_contents($testfile, 'test file, do not delete');
541         @chmod($testfile, $CFG->filepermissions);
542     }
543     $teststr = trim(file_get_contents($testfile));
544     if (empty($teststr)) {
545     // hmm, strange
546         return INSECURE_DATAROOT_WARNING;
547     }
549     $testurl = $datarooturl.'/diag/public.txt';
550     if (extension_loaded('curl') and
551         !(stripos(ini_get('disable_functions'), 'curl_init') !== FALSE) and
552         !(stripos(ini_get('disable_functions'), 'curl_setop') !== FALSE) and
553         ($ch = @curl_init($testurl)) !== false) {
554         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
555         curl_setopt($ch, CURLOPT_HEADER, false);
556         $data = curl_exec($ch);
557         if (!curl_errno($ch)) {
558             $data = trim($data);
559             if ($data === $teststr) {
560                 curl_close($ch);
561                 return INSECURE_DATAROOT_ERROR;
562             }
563         }
564         curl_close($ch);
565     }
567     if ($data = @file_get_contents($testurl)) {
568         $data = trim($data);
569         if ($data === $teststr) {
570             return INSECURE_DATAROOT_ERROR;
571         }
572     }
574     preg_match('|https?://([^/]+)|i', $testurl, $matches);
575     $sitename = $matches[1];
576     $error = 0;
577     if ($fp = @fsockopen($sitename, 80, $error)) {
578         preg_match('|https?://[^/]+(.*)|i', $testurl, $matches);
579         $localurl = $matches[1];
580         $out = "GET $localurl HTTP/1.1\r\n";
581         $out .= "Host: $sitename\r\n";
582         $out .= "Connection: Close\r\n\r\n";
583         fwrite($fp, $out);
584         $data = '';
585         $incoming = false;
586         while (!feof($fp)) {
587             if ($incoming) {
588                 $data .= fgets($fp, 1024);
589             } else if (@fgets($fp, 1024) === "\r\n") {
590                     $incoming = true;
591                 }
592         }
593         fclose($fp);
594         $data = trim($data);
595         if ($data === $teststr) {
596             return INSECURE_DATAROOT_ERROR;
597         }
598     }
600     return INSECURE_DATAROOT_WARNING;
603 /**
604  * Enables CLI maintenance mode by creating new dataroot/climaintenance.html file.
605  */
606 function enable_cli_maintenance_mode() {
607     global $CFG;
609     if (file_exists("$CFG->dataroot/climaintenance.html")) {
610         unlink("$CFG->dataroot/climaintenance.html");
611     }
613     if (isset($CFG->maintenance_message) and !html_is_blank($CFG->maintenance_message)) {
614         $data = $CFG->maintenance_message;
615         $data = bootstrap_renderer::early_error_content($data, null, null, null);
616         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
618     } else if (file_exists("$CFG->dataroot/climaintenance.template.html")) {
619         $data = file_get_contents("$CFG->dataroot/climaintenance.template.html");
621     } else {
622         $data = get_string('sitemaintenance', 'admin');
623         $data = bootstrap_renderer::early_error_content($data, null, null, null);
624         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
625     }
627     file_put_contents("$CFG->dataroot/climaintenance.html", $data);
628     chmod("$CFG->dataroot/climaintenance.html", $CFG->filepermissions);
631 /// CLASS DEFINITIONS /////////////////////////////////////////////////////////
634 /**
635  * Interface for anything appearing in the admin tree
636  *
637  * The interface that is implemented by anything that appears in the admin tree
638  * block. It forces inheriting classes to define a method for checking user permissions
639  * and methods for finding something in the admin tree.
640  *
641  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
642  */
643 interface part_of_admin_tree {
645 /**
646  * Finds a named part_of_admin_tree.
647  *
648  * Used to find a part_of_admin_tree. If a class only inherits part_of_admin_tree
649  * and not parentable_part_of_admin_tree, then this function should only check if
650  * $this->name matches $name. If it does, it should return a reference to $this,
651  * otherwise, it should return a reference to NULL.
652  *
653  * If a class inherits parentable_part_of_admin_tree, this method should be called
654  * recursively on all child objects (assuming, of course, the parent object's name
655  * doesn't match the search criterion).
656  *
657  * @param string $name The internal name of the part_of_admin_tree we're searching for.
658  * @return mixed An object reference or a NULL reference.
659  */
660     public function locate($name);
662     /**
663      * Removes named part_of_admin_tree.
664      *
665      * @param string $name The internal name of the part_of_admin_tree we want to remove.
666      * @return bool success.
667      */
668     public function prune($name);
670     /**
671      * Search using query
672      * @param string $query
673      * @return mixed array-object structure of found settings and pages
674      */
675     public function search($query);
677     /**
678      * Verifies current user's access to this part_of_admin_tree.
679      *
680      * Used to check if the current user has access to this part of the admin tree or
681      * not. If a class only inherits part_of_admin_tree and not parentable_part_of_admin_tree,
682      * then this method is usually just a call to has_capability() in the site context.
683      *
684      * If a class inherits parentable_part_of_admin_tree, this method should return the
685      * logical OR of the return of check_access() on all child objects.
686      *
687      * @return bool True if the user has access, false if she doesn't.
688      */
689     public function check_access();
691     /**
692      * Mostly useful for removing of some parts of the tree in admin tree block.
693      *
694      * @return True is hidden from normal list view
695      */
696     public function is_hidden();
698     /**
699      * Show we display Save button at the page bottom?
700      * @return bool
701      */
702     public function show_save();
706 /**
707  * Interface implemented by any part_of_admin_tree that has children.
708  *
709  * The interface implemented by any part_of_admin_tree that can be a parent
710  * to other part_of_admin_tree's. (For now, this only includes admin_category.) Apart
711  * from ensuring part_of_admin_tree compliancy, it also ensures inheriting methods
712  * include an add method for adding other part_of_admin_tree objects as children.
713  *
714  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
715  */
716 interface parentable_part_of_admin_tree extends part_of_admin_tree {
718 /**
719  * Adds a part_of_admin_tree object to the admin tree.
720  *
721  * Used to add a part_of_admin_tree object to this object or a child of this
722  * object. $something should only be added if $destinationname matches
723  * $this->name. If it doesn't, add should be called on child objects that are
724  * also parentable_part_of_admin_tree's.
725  *
726  * $something should be appended as the last child in the $destinationname. If the
727  * $beforesibling is specified, $something should be prepended to it. If the given
728  * sibling is not found, $something should be appended to the end of $destinationname
729  * and a developer debugging message should be displayed.
730  *
731  * @param string $destinationname The internal name of the new parent for $something.
732  * @param part_of_admin_tree $something The object to be added.
733  * @return bool True on success, false on failure.
734  */
735     public function add($destinationname, $something, $beforesibling = null);
740 /**
741  * The object used to represent folders (a.k.a. categories) in the admin tree block.
742  *
743  * Each admin_category object contains a number of part_of_admin_tree objects.
744  *
745  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
746  */
747 class admin_category implements parentable_part_of_admin_tree {
749     /** @var mixed An array of part_of_admin_tree objects that are this object's children */
750     public $children;
751     /** @var string An internal name for this category. Must be unique amongst ALL part_of_admin_tree objects */
752     public $name;
753     /** @var string The displayed name for this category. Usually obtained through get_string() */
754     public $visiblename;
755     /** @var bool Should this category be hidden in admin tree block? */
756     public $hidden;
757     /** @var mixed Either a string or an array or strings */
758     public $path;
759     /** @var mixed Either a string or an array or strings */
760     public $visiblepath;
762     /** @var array fast lookup category cache, all categories of one tree point to one cache */
763     protected $category_cache;
765     /**
766      * Constructor for an empty admin category
767      *
768      * @param string $name The internal name for this category. Must be unique amongst ALL part_of_admin_tree objects
769      * @param string $visiblename The displayed named for this category. Usually obtained through get_string()
770      * @param bool $hidden hide category in admin tree block, defaults to false
771      */
772     public function __construct($name, $visiblename, $hidden=false) {
773         $this->children    = array();
774         $this->name        = $name;
775         $this->visiblename = $visiblename;
776         $this->hidden      = $hidden;
777     }
779     /**
780      * Returns a reference to the part_of_admin_tree object with internal name $name.
781      *
782      * @param string $name The internal name of the object we want.
783      * @param bool $findpath initialize path and visiblepath arrays
784      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
785      *                  defaults to false
786      */
787     public function locate($name, $findpath=false) {
788         if (!isset($this->category_cache[$this->name])) {
789             // somebody much have purged the cache
790             $this->category_cache[$this->name] = $this;
791         }
793         if ($this->name == $name) {
794             if ($findpath) {
795                 $this->visiblepath[] = $this->visiblename;
796                 $this->path[]        = $this->name;
797             }
798             return $this;
799         }
801         // quick category lookup
802         if (!$findpath and isset($this->category_cache[$name])) {
803             return $this->category_cache[$name];
804         }
806         $return = NULL;
807         foreach($this->children as $childid=>$unused) {
808             if ($return = $this->children[$childid]->locate($name, $findpath)) {
809                 break;
810             }
811         }
813         if (!is_null($return) and $findpath) {
814             $return->visiblepath[] = $this->visiblename;
815             $return->path[]        = $this->name;
816         }
818         return $return;
819     }
821     /**
822      * Search using query
823      *
824      * @param string query
825      * @return mixed array-object structure of found settings and pages
826      */
827     public function search($query) {
828         $result = array();
829         foreach ($this->children as $child) {
830             $subsearch = $child->search($query);
831             if (!is_array($subsearch)) {
832                 debugging('Incorrect search result from '.$child->name);
833                 continue;
834             }
835             $result = array_merge($result, $subsearch);
836         }
837         return $result;
838     }
840     /**
841      * Removes part_of_admin_tree object with internal name $name.
842      *
843      * @param string $name The internal name of the object we want to remove.
844      * @return bool success
845      */
846     public function prune($name) {
848         if ($this->name == $name) {
849             return false;  //can not remove itself
850         }
852         foreach($this->children as $precedence => $child) {
853             if ($child->name == $name) {
854                 // clear cache and delete self
855                 while($this->category_cache) {
856                     // delete the cache, but keep the original array address
857                     array_pop($this->category_cache);
858                 }
859                 unset($this->children[$precedence]);
860                 return true;
861             } else if ($this->children[$precedence]->prune($name)) {
862                 return true;
863             }
864         }
865         return false;
866     }
868     /**
869      * Adds a part_of_admin_tree to a child or grandchild (or great-grandchild, and so forth) of this object.
870      *
871      * By default the new part of the tree is appended as the last child of the parent. You
872      * can specify a sibling node that the new part should be prepended to. If the given
873      * sibling is not found, the part is appended to the end (as it would be by default) and
874      * a developer debugging message is displayed.
875      *
876      * @throws coding_exception if the $beforesibling is empty string or is not string at all.
877      * @param string $destinationame The internal name of the immediate parent that we want for $something.
878      * @param mixed $something A part_of_admin_tree or setting instance to be added.
879      * @param string $beforesibling The name of the parent's child the $something should be prepended to.
880      * @return bool True if successfully added, false if $something can not be added.
881      */
882     public function add($parentname, $something, $beforesibling = null) {
883         global $CFG;
885         $parent = $this->locate($parentname);
886         if (is_null($parent)) {
887             debugging('parent does not exist!');
888             return false;
889         }
891         if ($something instanceof part_of_admin_tree) {
892             if (!($parent instanceof parentable_part_of_admin_tree)) {
893                 debugging('error - parts of tree can be inserted only into parentable parts');
894                 return false;
895             }
896             if ($CFG->debugdeveloper && !is_null($this->locate($something->name))) {
897                 // The name of the node is already used, simply warn the developer that this should not happen.
898                 // It is intentional to check for the debug level before performing the check.
899                 debugging('Duplicate admin page name: ' . $something->name, DEBUG_DEVELOPER);
900             }
901             if (is_null($beforesibling)) {
902                 // Append $something as the parent's last child.
903                 $parent->children[] = $something;
904             } else {
905                 if (!is_string($beforesibling) or trim($beforesibling) === '') {
906                     throw new coding_exception('Unexpected value of the beforesibling parameter');
907                 }
908                 // Try to find the position of the sibling.
909                 $siblingposition = null;
910                 foreach ($parent->children as $childposition => $child) {
911                     if ($child->name === $beforesibling) {
912                         $siblingposition = $childposition;
913                         break;
914                     }
915                 }
916                 if (is_null($siblingposition)) {
917                     debugging('Sibling '.$beforesibling.' not found', DEBUG_DEVELOPER);
918                     $parent->children[] = $something;
919                 } else {
920                     $parent->children = array_merge(
921                         array_slice($parent->children, 0, $siblingposition),
922                         array($something),
923                         array_slice($parent->children, $siblingposition)
924                     );
925                 }
926             }
927             if ($something instanceof admin_category) {
928                 if (isset($this->category_cache[$something->name])) {
929                     debugging('Duplicate admin category name: '.$something->name);
930                 } else {
931                     $this->category_cache[$something->name] = $something;
932                     $something->category_cache =& $this->category_cache;
933                     foreach ($something->children as $child) {
934                         // just in case somebody already added subcategories
935                         if ($child instanceof admin_category) {
936                             if (isset($this->category_cache[$child->name])) {
937                                 debugging('Duplicate admin category name: '.$child->name);
938                             } else {
939                                 $this->category_cache[$child->name] = $child;
940                                 $child->category_cache =& $this->category_cache;
941                             }
942                         }
943                     }
944                 }
945             }
946             return true;
948         } else {
949             debugging('error - can not add this element');
950             return false;
951         }
953     }
955     /**
956      * Checks if the user has access to anything in this category.
957      *
958      * @return bool True if the user has access to at least one child in this category, false otherwise.
959      */
960     public function check_access() {
961         foreach ($this->children as $child) {
962             if ($child->check_access()) {
963                 return true;
964             }
965         }
966         return false;
967     }
969     /**
970      * Is this category hidden in admin tree block?
971      *
972      * @return bool True if hidden
973      */
974     public function is_hidden() {
975         return $this->hidden;
976     }
978     /**
979      * Show we display Save button at the page bottom?
980      * @return bool
981      */
982     public function show_save() {
983         foreach ($this->children as $child) {
984             if ($child->show_save()) {
985                 return true;
986             }
987         }
988         return false;
989     }
993 /**
994  * Root of admin settings tree, does not have any parent.
995  *
996  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
997  */
998 class admin_root extends admin_category {
999 /** @var array List of errors */
1000     public $errors;
1001     /** @var string search query */
1002     public $search;
1003     /** @var bool full tree flag - true means all settings required, false only pages required */
1004     public $fulltree;
1005     /** @var bool flag indicating loaded tree */
1006     public $loaded;
1007     /** @var mixed site custom defaults overriding defaults in settings files*/
1008     public $custom_defaults;
1010     /**
1011      * @param bool $fulltree true means all settings required,
1012      *                            false only pages required
1013      */
1014     public function __construct($fulltree) {
1015         global $CFG;
1017         parent::__construct('root', get_string('administration'), false);
1018         $this->errors   = array();
1019         $this->search   = '';
1020         $this->fulltree = $fulltree;
1021         $this->loaded   = false;
1023         $this->category_cache = array();
1025         // load custom defaults if found
1026         $this->custom_defaults = null;
1027         $defaultsfile = "$CFG->dirroot/local/defaults.php";
1028         if (is_readable($defaultsfile)) {
1029             $defaults = array();
1030             include($defaultsfile);
1031             if (is_array($defaults) and count($defaults)) {
1032                 $this->custom_defaults = $defaults;
1033             }
1034         }
1035     }
1037     /**
1038      * Empties children array, and sets loaded to false
1039      *
1040      * @param bool $requirefulltree
1041      */
1042     public function purge_children($requirefulltree) {
1043         $this->children = array();
1044         $this->fulltree = ($requirefulltree || $this->fulltree);
1045         $this->loaded   = false;
1046         //break circular dependencies - this helps PHP 5.2
1047         while($this->category_cache) {
1048             array_pop($this->category_cache);
1049         }
1050         $this->category_cache = array();
1051     }
1055 /**
1056  * Links external PHP pages into the admin tree.
1057  *
1058  * See detailed usage example at the top of this document (adminlib.php)
1059  *
1060  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1061  */
1062 class admin_externalpage implements part_of_admin_tree {
1064     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1065     public $name;
1067     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1068     public $visiblename;
1070     /** @var string The external URL that we should link to when someone requests this external page. */
1071     public $url;
1073     /** @var string The role capability/permission a user must have to access this external page. */
1074     public $req_capability;
1076     /** @var object The context in which capability/permission should be checked, default is site context. */
1077     public $context;
1079     /** @var bool hidden in admin tree block. */
1080     public $hidden;
1082     /** @var mixed either string or array of string */
1083     public $path;
1085     /** @var array list of visible names of page parents */
1086     public $visiblepath;
1088     /**
1089      * Constructor for adding an external page into the admin tree.
1090      *
1091      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1092      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1093      * @param string $url The external URL that we should link to when someone requests this external page.
1094      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1095      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1096      * @param stdClass $context The context the page relates to. Not sure what happens
1097      *      if you specify something other than system or front page. Defaults to system.
1098      */
1099     public function __construct($name, $visiblename, $url, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1100         $this->name        = $name;
1101         $this->visiblename = $visiblename;
1102         $this->url         = $url;
1103         if (is_array($req_capability)) {
1104             $this->req_capability = $req_capability;
1105         } else {
1106             $this->req_capability = array($req_capability);
1107         }
1108         $this->hidden = $hidden;
1109         $this->context = $context;
1110     }
1112     /**
1113      * Returns a reference to the part_of_admin_tree object with internal name $name.
1114      *
1115      * @param string $name The internal name of the object we want.
1116      * @param bool $findpath defaults to false
1117      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
1118      */
1119     public function locate($name, $findpath=false) {
1120         if ($this->name == $name) {
1121             if ($findpath) {
1122                 $this->visiblepath = array($this->visiblename);
1123                 $this->path        = array($this->name);
1124             }
1125             return $this;
1126         } else {
1127             $return = NULL;
1128             return $return;
1129         }
1130     }
1132     /**
1133      * This function always returns false, required function by interface
1134      *
1135      * @param string $name
1136      * @return false
1137      */
1138     public function prune($name) {
1139         return false;
1140     }
1142     /**
1143      * Search using query
1144      *
1145      * @param string $query
1146      * @return mixed array-object structure of found settings and pages
1147      */
1148     public function search($query) {
1149         $found = false;
1150         if (strpos(strtolower($this->name), $query) !== false) {
1151             $found = true;
1152         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1153                 $found = true;
1154             }
1155         if ($found) {
1156             $result = new stdClass();
1157             $result->page     = $this;
1158             $result->settings = array();
1159             return array($this->name => $result);
1160         } else {
1161             return array();
1162         }
1163     }
1165     /**
1166      * Determines if the current user has access to this external page based on $this->req_capability.
1167      *
1168      * @return bool True if user has access, false otherwise.
1169      */
1170     public function check_access() {
1171         global $CFG;
1172         $context = empty($this->context) ? context_system::instance() : $this->context;
1173         foreach($this->req_capability as $cap) {
1174             if (has_capability($cap, $context)) {
1175                 return true;
1176             }
1177         }
1178         return false;
1179     }
1181     /**
1182      * Is this external page hidden in admin tree block?
1183      *
1184      * @return bool True if hidden
1185      */
1186     public function is_hidden() {
1187         return $this->hidden;
1188     }
1190     /**
1191      * Show we display Save button at the page bottom?
1192      * @return bool
1193      */
1194     public function show_save() {
1195         return false;
1196     }
1200 /**
1201  * Used to group a number of admin_setting objects into a page and add them to the admin tree.
1202  *
1203  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1204  */
1205 class admin_settingpage implements part_of_admin_tree {
1207     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1208     public $name;
1210     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1211     public $visiblename;
1213     /** @var mixed An array of admin_setting objects that are part of this setting page. */
1214     public $settings;
1216     /** @var string The role capability/permission a user must have to access this external page. */
1217     public $req_capability;
1219     /** @var object The context in which capability/permission should be checked, default is site context. */
1220     public $context;
1222     /** @var bool hidden in admin tree block. */
1223     public $hidden;
1225     /** @var mixed string of paths or array of strings of paths */
1226     public $path;
1228     /** @var array list of visible names of page parents */
1229     public $visiblepath;
1231     /**
1232      * see admin_settingpage for details of this function
1233      *
1234      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1235      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1236      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1237      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1238      * @param stdClass $context The context the page relates to. Not sure what happens
1239      *      if you specify something other than system or front page. Defaults to system.
1240      */
1241     public function __construct($name, $visiblename, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1242         $this->settings    = new stdClass();
1243         $this->name        = $name;
1244         $this->visiblename = $visiblename;
1245         if (is_array($req_capability)) {
1246             $this->req_capability = $req_capability;
1247         } else {
1248             $this->req_capability = array($req_capability);
1249         }
1250         $this->hidden      = $hidden;
1251         $this->context     = $context;
1252     }
1254     /**
1255      * see admin_category
1256      *
1257      * @param string $name
1258      * @param bool $findpath
1259      * @return mixed Object (this) if name ==  this->name, else returns null
1260      */
1261     public function locate($name, $findpath=false) {
1262         if ($this->name == $name) {
1263             if ($findpath) {
1264                 $this->visiblepath = array($this->visiblename);
1265                 $this->path        = array($this->name);
1266             }
1267             return $this;
1268         } else {
1269             $return = NULL;
1270             return $return;
1271         }
1272     }
1274     /**
1275      * Search string in settings page.
1276      *
1277      * @param string $query
1278      * @return array
1279      */
1280     public function search($query) {
1281         $found = array();
1283         foreach ($this->settings as $setting) {
1284             if ($setting->is_related($query)) {
1285                 $found[] = $setting;
1286             }
1287         }
1289         if ($found) {
1290             $result = new stdClass();
1291             $result->page     = $this;
1292             $result->settings = $found;
1293             return array($this->name => $result);
1294         }
1296         $found = false;
1297         if (strpos(strtolower($this->name), $query) !== false) {
1298             $found = true;
1299         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1300                 $found = true;
1301             }
1302         if ($found) {
1303             $result = new stdClass();
1304             $result->page     = $this;
1305             $result->settings = array();
1306             return array($this->name => $result);
1307         } else {
1308             return array();
1309         }
1310     }
1312     /**
1313      * This function always returns false, required by interface
1314      *
1315      * @param string $name
1316      * @return bool Always false
1317      */
1318     public function prune($name) {
1319         return false;
1320     }
1322     /**
1323      * adds an admin_setting to this admin_settingpage
1324      *
1325      * 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
1326      * n.b. each admin_setting in an admin_settingpage must have a unique internal name
1327      *
1328      * @param object $setting is the admin_setting object you want to add
1329      * @return bool true if successful, false if not
1330      */
1331     public function add($setting) {
1332         if (!($setting instanceof admin_setting)) {
1333             debugging('error - not a setting instance');
1334             return false;
1335         }
1337         $this->settings->{$setting->name} = $setting;
1338         return true;
1339     }
1341     /**
1342      * see admin_externalpage
1343      *
1344      * @return bool Returns true for yes false for no
1345      */
1346     public function check_access() {
1347         global $CFG;
1348         $context = empty($this->context) ? context_system::instance() : $this->context;
1349         foreach($this->req_capability as $cap) {
1350             if (has_capability($cap, $context)) {
1351                 return true;
1352             }
1353         }
1354         return false;
1355     }
1357     /**
1358      * outputs this page as html in a table (suitable for inclusion in an admin pagetype)
1359      * @return string Returns an XHTML string
1360      */
1361     public function output_html() {
1362         $adminroot = admin_get_root();
1363         $return = '<fieldset>'."\n".'<div class="clearer"><!-- --></div>'."\n";
1364         foreach($this->settings as $setting) {
1365             $fullname = $setting->get_full_name();
1366             if (array_key_exists($fullname, $adminroot->errors)) {
1367                 $data = $adminroot->errors[$fullname]->data;
1368             } else {
1369                 $data = $setting->get_setting();
1370                 // do not use defaults if settings not available - upgrade settings handles the defaults!
1371             }
1372             $return .= $setting->output_html($data);
1373         }
1374         $return .= '</fieldset>';
1375         return $return;
1376     }
1378     /**
1379      * Is this settings page hidden in admin tree block?
1380      *
1381      * @return bool True if hidden
1382      */
1383     public function is_hidden() {
1384         return $this->hidden;
1385     }
1387     /**
1388      * Show we display Save button at the page bottom?
1389      * @return bool
1390      */
1391     public function show_save() {
1392         foreach($this->settings as $setting) {
1393             if (empty($setting->nosave)) {
1394                 return true;
1395             }
1396         }
1397         return false;
1398     }
1402 /**
1403  * Admin settings class. Only exists on setting pages.
1404  * Read & write happens at this level; no authentication.
1405  *
1406  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1407  */
1408 abstract class admin_setting {
1409     /** @var string unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins. */
1410     public $name;
1411     /** @var string localised name */
1412     public $visiblename;
1413     /** @var string localised long description in Markdown format */
1414     public $description;
1415     /** @var mixed Can be string or array of string */
1416     public $defaultsetting;
1417     /** @var string */
1418     public $updatedcallback;
1419     /** @var mixed can be String or Null.  Null means main config table */
1420     public $plugin; // null means main config table
1421     /** @var bool true indicates this setting does not actually save anything, just information */
1422     public $nosave = false;
1423     /** @var bool if set, indicates that a change to this setting requires rebuild course cache */
1424     public $affectsmodinfo = false;
1425     /** @var array of admin_setting_flag - These are extra checkboxes attached to a setting. */
1426     private $flags = array();
1428     /**
1429      * Constructor
1430      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
1431      *                     or 'myplugin/mysetting' for ones in config_plugins.
1432      * @param string $visiblename localised name
1433      * @param string $description localised long description
1434      * @param mixed $defaultsetting string or array depending on implementation
1435      */
1436     public function __construct($name, $visiblename, $description, $defaultsetting) {
1437         $this->parse_setting_name($name);
1438         $this->visiblename    = $visiblename;
1439         $this->description    = $description;
1440         $this->defaultsetting = $defaultsetting;
1441     }
1443     /**
1444      * Generic function to add a flag to this admin setting.
1445      *
1446      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1447      * @param bool $default - The default for the flag
1448      * @param string $shortname - The shortname for this flag. Used as a suffix for the setting name.
1449      * @param string $displayname - The display name for this flag. Used as a label next to the checkbox.
1450      */
1451     protected function set_flag_options($enabled, $default, $shortname, $displayname) {
1452         if (empty($this->flags[$shortname])) {
1453             $this->flags[$shortname] = new admin_setting_flag($enabled, $default, $shortname, $displayname);
1454         } else {
1455             $this->flags[$shortname]->set_options($enabled, $default);
1456         }
1457     }
1459     /**
1460      * Set the enabled options flag on this admin setting.
1461      *
1462      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1463      * @param bool $default - The default for the flag
1464      */
1465     public function set_enabled_flag_options($enabled, $default) {
1466         $this->set_flag_options($enabled, $default, 'enabled', new lang_string('enabled', 'core_admin'));
1467     }
1469     /**
1470      * Set the advanced options flag on this admin setting.
1471      *
1472      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1473      * @param bool $default - The default for the flag
1474      */
1475     public function set_advanced_flag_options($enabled, $default) {
1476         $this->set_flag_options($enabled, $default, 'adv', new lang_string('advanced'));
1477     }
1480     /**
1481      * Set the locked options flag on this admin setting.
1482      *
1483      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1484      * @param bool $default - The default for the flag
1485      */
1486     public function set_locked_flag_options($enabled, $default) {
1487         $this->set_flag_options($enabled, $default, 'locked', new lang_string('locked', 'core_admin'));
1488     }
1490     /**
1491      * Get the currently saved value for a setting flag
1492      *
1493      * @param admin_setting_flag $flag - One of the admin_setting_flag for this admin_setting.
1494      * @return bool
1495      */
1496     public function get_setting_flag_value(admin_setting_flag $flag) {
1497         $value = $this->config_read($this->name . '_' . $flag->get_shortname());
1498         if (!isset($value)) {
1499             $value = $flag->get_default();
1500         }
1502         return !empty($value);
1503     }
1505     /**
1506      * Get the list of defaults for the flags on this setting.
1507      *
1508      * @param array of strings describing the defaults for this setting. This is appended to by this function.
1509      */
1510     public function get_setting_flag_defaults(& $defaults) {
1511         foreach ($this->flags as $flag) {
1512             if ($flag->is_enabled() && $flag->get_default()) {
1513                 $defaults[] = $flag->get_displayname();
1514             }
1515         }
1516     }
1518     /**
1519      * Output the input fields for the advanced and locked flags on this setting.
1520      *
1521      * @param bool $adv - The current value of the advanced flag.
1522      * @param bool $locked - The current value of the locked flag.
1523      * @return string $output - The html for the flags.
1524      */
1525     public function output_setting_flags() {
1526         $output = '';
1528         foreach ($this->flags as $flag) {
1529             if ($flag->is_enabled()) {
1530                 $output .= $flag->output_setting_flag($this);
1531             }
1532         }
1534         if (!empty($output)) {
1535             return html_writer::tag('span', $output, array('class' => 'adminsettingsflags'));
1536         }
1537         return $output;
1538     }
1540     /**
1541      * Write the values of the flags for this admin setting.
1542      *
1543      * @param array $data - The data submitted from the form or null to set the default value for new installs.
1544      * @return bool - true if successful.
1545      */
1546     public function write_setting_flags($data) {
1547         $result = true;
1548         foreach ($this->flags as $flag) {
1549             $result = $result && $flag->write_setting_flag($this, $data);
1550         }
1551         return $result;
1552     }
1554     /**
1555      * Set up $this->name and potentially $this->plugin
1556      *
1557      * Set up $this->name and possibly $this->plugin based on whether $name looks
1558      * like 'settingname' or 'plugin/settingname'. Also, do some sanity checking
1559      * on the names, that is, output a developer debug warning if the name
1560      * contains anything other than [a-zA-Z0-9_]+.
1561      *
1562      * @param string $name the setting name passed in to the constructor.
1563      */
1564     private function parse_setting_name($name) {
1565         $bits = explode('/', $name);
1566         if (count($bits) > 2) {
1567             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1568         }
1569         $this->name = array_pop($bits);
1570         if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->name)) {
1571             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1572         }
1573         if (!empty($bits)) {
1574             $this->plugin = array_pop($bits);
1575             if ($this->plugin === 'moodle') {
1576                 $this->plugin = null;
1577             } else if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->plugin)) {
1578                     throw new moodle_exception('invalidadminsettingname', '', '', $name);
1579                 }
1580         }
1581     }
1583     /**
1584      * Returns the fullname prefixed by the plugin
1585      * @return string
1586      */
1587     public function get_full_name() {
1588         return 's_'.$this->plugin.'_'.$this->name;
1589     }
1591     /**
1592      * Returns the ID string based on plugin and name
1593      * @return string
1594      */
1595     public function get_id() {
1596         return 'id_s_'.$this->plugin.'_'.$this->name;
1597     }
1599     /**
1600      * @param bool $affectsmodinfo If true, changes to this setting will
1601      *   cause the course cache to be rebuilt
1602      */
1603     public function set_affects_modinfo($affectsmodinfo) {
1604         $this->affectsmodinfo = $affectsmodinfo;
1605     }
1607     /**
1608      * Returns the config if possible
1609      *
1610      * @return mixed returns config if successful else null
1611      */
1612     public function config_read($name) {
1613         global $CFG;
1614         if (!empty($this->plugin)) {
1615             $value = get_config($this->plugin, $name);
1616             return $value === false ? NULL : $value;
1618         } else {
1619             if (isset($CFG->$name)) {
1620                 return $CFG->$name;
1621             } else {
1622                 return NULL;
1623             }
1624         }
1625     }
1627     /**
1628      * Used to set a config pair and log change
1629      *
1630      * @param string $name
1631      * @param mixed $value Gets converted to string if not null
1632      * @return bool Write setting to config table
1633      */
1634     public function config_write($name, $value) {
1635         global $DB, $USER, $CFG;
1637         if ($this->nosave) {
1638             return true;
1639         }
1641         // make sure it is a real change
1642         $oldvalue = get_config($this->plugin, $name);
1643         $oldvalue = ($oldvalue === false) ? null : $oldvalue; // normalise
1644         $value = is_null($value) ? null : (string)$value;
1646         if ($oldvalue === $value) {
1647             return true;
1648         }
1650         // store change
1651         set_config($name, $value, $this->plugin);
1653         // Some admin settings affect course modinfo
1654         if ($this->affectsmodinfo) {
1655             // Clear course cache for all courses
1656             rebuild_course_cache(0, true);
1657         }
1659         add_to_config_log($name, $oldvalue, $value, $this->plugin);
1661         return true; // BC only
1662     }
1664     /**
1665      * Returns current value of this setting
1666      * @return mixed array or string depending on instance, NULL means not set yet
1667      */
1668     public abstract function get_setting();
1670     /**
1671      * Returns default setting if exists
1672      * @return mixed array or string depending on instance; NULL means no default, user must supply
1673      */
1674     public function get_defaultsetting() {
1675         $adminroot =  admin_get_root(false, false);
1676         if (!empty($adminroot->custom_defaults)) {
1677             $plugin = is_null($this->plugin) ? 'moodle' : $this->plugin;
1678             if (isset($adminroot->custom_defaults[$plugin])) {
1679                 if (array_key_exists($this->name, $adminroot->custom_defaults[$plugin])) { // null is valid value here ;-)
1680                     return $adminroot->custom_defaults[$plugin][$this->name];
1681                 }
1682             }
1683         }
1684         return $this->defaultsetting;
1685     }
1687     /**
1688      * Store new setting
1689      *
1690      * @param mixed $data string or array, must not be NULL
1691      * @return string empty string if ok, string error message otherwise
1692      */
1693     public abstract function write_setting($data);
1695     /**
1696      * Return part of form with setting
1697      * This function should always be overwritten
1698      *
1699      * @param mixed $data array or string depending on setting
1700      * @param string $query
1701      * @return string
1702      */
1703     public function output_html($data, $query='') {
1704     // should be overridden
1705         return;
1706     }
1708     /**
1709      * Function called if setting updated - cleanup, cache reset, etc.
1710      * @param string $functionname Sets the function name
1711      * @return void
1712      */
1713     public function set_updatedcallback($functionname) {
1714         $this->updatedcallback = $functionname;
1715     }
1717     /**
1718      * Execute postupdatecallback if necessary.
1719      * @param mixed $original original value before write_setting()
1720      * @return bool true if changed, false if not.
1721      */
1722     public function post_write_settings($original) {
1723         // Comparison must work for arrays too.
1724         if (serialize($original) === serialize($this->get_setting())) {
1725             return false;
1726         }
1728         $callbackfunction = $this->updatedcallback;
1729         if (!empty($callbackfunction) and function_exists($callbackfunction)) {
1730             $callbackfunction($this->get_full_name());
1731         }
1732         return true;
1733     }
1735     /**
1736      * Is setting related to query text - used when searching
1737      * @param string $query
1738      * @return bool
1739      */
1740     public function is_related($query) {
1741         if (strpos(strtolower($this->name), $query) !== false) {
1742             return true;
1743         }
1744         if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1745             return true;
1746         }
1747         if (strpos(core_text::strtolower($this->description), $query) !== false) {
1748             return true;
1749         }
1750         $current = $this->get_setting();
1751         if (!is_null($current)) {
1752             if (is_string($current)) {
1753                 if (strpos(core_text::strtolower($current), $query) !== false) {
1754                     return true;
1755                 }
1756             }
1757         }
1758         $default = $this->get_defaultsetting();
1759         if (!is_null($default)) {
1760             if (is_string($default)) {
1761                 if (strpos(core_text::strtolower($default), $query) !== false) {
1762                     return true;
1763                 }
1764             }
1765         }
1766         return false;
1767     }
1770 /**
1771  * An additional option that can be applied to an admin setting.
1772  * The currently supported options are 'ADVANCED' and 'LOCKED'.
1773  *
1774  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1775  */
1776 class admin_setting_flag {
1777     /** @var bool Flag to indicate if this option can be toggled for this setting */
1778     private $enabled = false;
1779     /** @var bool Flag to indicate if this option defaults to true or false */
1780     private $default = false;
1781     /** @var string Short string used to create setting name - e.g. 'adv' */
1782     private $shortname = '';
1783     /** @var string String used as the label for this flag */
1784     private $displayname = '';
1785     /** @const Checkbox for this flag is displayed in admin page */
1786     const ENABLED = true;
1787     /** @const Checkbox for this flag is not displayed in admin page */
1788     const DISABLED = false;
1790     /**
1791      * Constructor
1792      *
1793      * @param bool $enabled Can this option can be toggled.
1794      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
1795      * @param bool $default The default checked state for this setting option.
1796      * @param string $shortname The shortname of this flag. Currently supported flags are 'locked' and 'adv'
1797      * @param string $displayname The displayname of this flag. Used as a label for the flag.
1798      */
1799     public function __construct($enabled, $default, $shortname, $displayname) {
1800         $this->shortname = $shortname;
1801         $this->displayname = $displayname;
1802         $this->set_options($enabled, $default);
1803     }
1805     /**
1806      * Update the values of this setting options class
1807      *
1808      * @param bool $enabled Can this option can be toggled.
1809      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
1810      * @param bool $default The default checked state for this setting option.
1811      */
1812     public function set_options($enabled, $default) {
1813         $this->enabled = $enabled;
1814         $this->default = $default;
1815     }
1817     /**
1818      * Should this option appear in the interface and be toggleable?
1819      *
1820      * @return bool Is it enabled?
1821      */
1822     public function is_enabled() {
1823         return $this->enabled;
1824     }
1826     /**
1827      * Should this option be checked by default?
1828      *
1829      * @return bool Is it on by default?
1830      */
1831     public function get_default() {
1832         return $this->default;
1833     }
1835     /**
1836      * Return the short name for this flag. e.g. 'adv' or 'locked'
1837      *
1838      * @return string
1839      */
1840     public function get_shortname() {
1841         return $this->shortname;
1842     }
1844     /**
1845      * Return the display name for this flag. e.g. 'Advanced' or 'Locked'
1846      *
1847      * @return string
1848      */
1849     public function get_displayname() {
1850         return $this->displayname;
1851     }
1853     /**
1854      * Save the submitted data for this flag - or set it to the default if $data is null.
1855      *
1856      * @param admin_setting $setting - The admin setting for this flag
1857      * @param array $data - The data submitted from the form or null to set the default value for new installs.
1858      * @return bool
1859      */
1860     public function write_setting_flag(admin_setting $setting, $data) {
1861         $result = true;
1862         if ($this->is_enabled()) {
1863             if (!isset($data)) {
1864                 $value = $this->get_default();
1865             } else {
1866                 $value = !empty($data[$setting->get_full_name() . '_' . $this->get_shortname()]);
1867             }
1868             $result = $setting->config_write($setting->name . '_' . $this->get_shortname(), $value);
1869         }
1871         return $result;
1873     }
1875     /**
1876      * Output the checkbox for this setting flag. Should only be called if the flag is enabled.
1877      *
1878      * @param admin_setting $setting - The admin setting for this flag
1879      * @return string - The html for the checkbox.
1880      */
1881     public function output_setting_flag(admin_setting $setting) {
1882         $value = $setting->get_setting_flag_value($this);
1883         $output = ' <input type="checkbox" class="form-checkbox" ' .
1884                         ' id="' .  $setting->get_id() . '_' . $this->get_shortname() . '" ' .
1885                         ' name="' . $setting->get_full_name() .  '_' . $this->get_shortname() . '" ' .
1886                         ' value="1" ' . ($value ? 'checked="checked"' : '') . ' />' .
1887                         ' <label for="' . $setting->get_id() . '_' . $this->get_shortname() . '">' .
1888                         $this->get_displayname() .
1889                         ' </label> ';
1890         return $output;
1891     }
1895 /**
1896  * No setting - just heading and text.
1897  *
1898  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1899  */
1900 class admin_setting_heading extends admin_setting {
1902     /**
1903      * not a setting, just text
1904      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1905      * @param string $heading heading
1906      * @param string $information text in box
1907      */
1908     public function __construct($name, $heading, $information) {
1909         $this->nosave = true;
1910         parent::__construct($name, $heading, $information, '');
1911     }
1913     /**
1914      * Always returns true
1915      * @return bool Always returns true
1916      */
1917     public function get_setting() {
1918         return true;
1919     }
1921     /**
1922      * Always returns true
1923      * @return bool Always returns true
1924      */
1925     public function get_defaultsetting() {
1926         return true;
1927     }
1929     /**
1930      * Never write settings
1931      * @return string Always returns an empty string
1932      */
1933     public function write_setting($data) {
1934     // do not write any setting
1935         return '';
1936     }
1938     /**
1939      * Returns an HTML string
1940      * @return string Returns an HTML string
1941      */
1942     public function output_html($data, $query='') {
1943         global $OUTPUT;
1944         $return = '';
1945         if ($this->visiblename != '') {
1946             $return .= $OUTPUT->heading($this->visiblename, 3, 'main');
1947         }
1948         if ($this->description != '') {
1949             $return .= $OUTPUT->box(highlight($query, markdown_to_html($this->description)), 'generalbox formsettingheading');
1950         }
1951         return $return;
1952     }
1956 /**
1957  * The most flexibly setting, user is typing text
1958  *
1959  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1960  */
1961 class admin_setting_configtext extends admin_setting {
1963     /** @var mixed int means PARAM_XXX type, string is a allowed format in regex */
1964     public $paramtype;
1965     /** @var int default field size */
1966     public $size;
1968     /**
1969      * Config text constructor
1970      *
1971      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1972      * @param string $visiblename localised
1973      * @param string $description long localised info
1974      * @param string $defaultsetting
1975      * @param mixed $paramtype int means PARAM_XXX type, string is a allowed format in regex
1976      * @param int $size default field size
1977      */
1978     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $size=null) {
1979         $this->paramtype = $paramtype;
1980         if (!is_null($size)) {
1981             $this->size  = $size;
1982         } else {
1983             $this->size  = ($paramtype === PARAM_INT) ? 5 : 30;
1984         }
1985         parent::__construct($name, $visiblename, $description, $defaultsetting);
1986     }
1988     /**
1989      * Return the setting
1990      *
1991      * @return mixed returns config if successful else null
1992      */
1993     public function get_setting() {
1994         return $this->config_read($this->name);
1995     }
1997     public function write_setting($data) {
1998         if ($this->paramtype === PARAM_INT and $data === '') {
1999         // do not complain if '' used instead of 0
2000             $data = 0;
2001         }
2002         // $data is a string
2003         $validated = $this->validate($data);
2004         if ($validated !== true) {
2005             return $validated;
2006         }
2007         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2008     }
2010     /**
2011      * Validate data before storage
2012      * @param string data
2013      * @return mixed true if ok string if error found
2014      */
2015     public function validate($data) {
2016         // allow paramtype to be a custom regex if it is the form of /pattern/
2017         if (preg_match('#^/.*/$#', $this->paramtype)) {
2018             if (preg_match($this->paramtype, $data)) {
2019                 return true;
2020             } else {
2021                 return get_string('validateerror', 'admin');
2022             }
2024         } else if ($this->paramtype === PARAM_RAW) {
2025             return true;
2027         } else {
2028             $cleaned = clean_param($data, $this->paramtype);
2029             if ("$data" === "$cleaned") { // implicit conversion to string is needed to do exact comparison
2030                 return true;
2031             } else {
2032                 return get_string('validateerror', 'admin');
2033             }
2034         }
2035     }
2037     /**
2038      * Return an XHTML string for the setting
2039      * @return string Returns an XHTML string
2040      */
2041     public function output_html($data, $query='') {
2042         $default = $this->get_defaultsetting();
2044         return format_admin_setting($this, $this->visiblename,
2045         '<div class="form-text defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" /></div>',
2046         $this->description, true, '', $default, $query);
2047     }
2051 /**
2052  * General text area without html editor.
2053  *
2054  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2055  */
2056 class admin_setting_configtextarea extends admin_setting_configtext {
2057     private $rows;
2058     private $cols;
2060     /**
2061      * @param string $name
2062      * @param string $visiblename
2063      * @param string $description
2064      * @param mixed $defaultsetting string or array
2065      * @param mixed $paramtype
2066      * @param string $cols The number of columns to make the editor
2067      * @param string $rows The number of rows to make the editor
2068      */
2069     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2070         $this->rows = $rows;
2071         $this->cols = $cols;
2072         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
2073     }
2075     /**
2076      * Returns an XHTML string for the editor
2077      *
2078      * @param string $data
2079      * @param string $query
2080      * @return string XHTML string for the editor
2081      */
2082     public function output_html($data, $query='') {
2083         $default = $this->get_defaultsetting();
2085         $defaultinfo = $default;
2086         if (!is_null($default) and $default !== '') {
2087             $defaultinfo = "\n".$default;
2088         }
2090         return format_admin_setting($this, $this->visiblename,
2091         '<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>',
2092         $this->description, true, '', $defaultinfo, $query);
2093     }
2097 /**
2098  * General text area with html editor.
2099  */
2100 class admin_setting_confightmleditor extends admin_setting_configtext {
2101     private $rows;
2102     private $cols;
2104     /**
2105      * @param string $name
2106      * @param string $visiblename
2107      * @param string $description
2108      * @param mixed $defaultsetting string or array
2109      * @param mixed $paramtype
2110      */
2111     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2112         $this->rows = $rows;
2113         $this->cols = $cols;
2114         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
2115         editors_head_setup();
2116     }
2118     /**
2119      * Returns an XHTML string for the editor
2120      *
2121      * @param string $data
2122      * @param string $query
2123      * @return string XHTML string for the editor
2124      */
2125     public function output_html($data, $query='') {
2126         $default = $this->get_defaultsetting();
2128         $defaultinfo = $default;
2129         if (!is_null($default) and $default !== '') {
2130             $defaultinfo = "\n".$default;
2131         }
2133         $editor = editors_get_preferred_editor(FORMAT_HTML);
2134         $editor->use_editor($this->get_id(), array('noclean'=>true));
2136         return format_admin_setting($this, $this->visiblename,
2137         '<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>',
2138         $this->description, true, '', $defaultinfo, $query);
2139     }
2143 /**
2144  * Password field, allows unmasking of password
2145  *
2146  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2147  */
2148 class admin_setting_configpasswordunmask extends admin_setting_configtext {
2149     /**
2150      * Constructor
2151      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2152      * @param string $visiblename localised
2153      * @param string $description long localised info
2154      * @param string $defaultsetting default password
2155      */
2156     public function __construct($name, $visiblename, $description, $defaultsetting) {
2157         parent::__construct($name, $visiblename, $description, $defaultsetting, PARAM_RAW, 30);
2158     }
2160     /**
2161      * Returns XHTML for the field
2162      * Writes Javascript into the HTML below right before the last div
2163      *
2164      * @todo Make javascript available through newer methods if possible
2165      * @param string $data Value for the field
2166      * @param string $query Passed as final argument for format_admin_setting
2167      * @return string XHTML field
2168      */
2169     public function output_html($data, $query='') {
2170         $id = $this->get_id();
2171         $unmask = get_string('unmaskpassword', 'form');
2172         $unmaskjs = '<script type="text/javascript">
2173 //<![CDATA[
2174 var is_ie = (navigator.userAgent.toLowerCase().indexOf("msie") != -1);
2176 document.getElementById("'.$id.'").setAttribute("autocomplete", "off");
2178 var unmaskdiv = document.getElementById("'.$id.'unmaskdiv");
2180 var unmaskchb = document.createElement("input");
2181 unmaskchb.setAttribute("type", "checkbox");
2182 unmaskchb.setAttribute("id", "'.$id.'unmask");
2183 unmaskchb.onchange = function() {unmaskPassword("'.$id.'");};
2184 unmaskdiv.appendChild(unmaskchb);
2186 var unmasklbl = document.createElement("label");
2187 unmasklbl.innerHTML = "'.addslashes_js($unmask).'";
2188 if (is_ie) {
2189   unmasklbl.setAttribute("htmlFor", "'.$id.'unmask");
2190 } else {
2191   unmasklbl.setAttribute("for", "'.$id.'unmask");
2193 unmaskdiv.appendChild(unmasklbl);
2195 if (is_ie) {
2196   // ugly hack to work around the famous onchange IE bug
2197   unmaskchb.onclick = function() {this.blur();};
2198   unmaskdiv.onclick = function() {this.blur();};
2200 //]]>
2201 </script>';
2202         return format_admin_setting($this, $this->visiblename,
2203         '<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>',
2204         $this->description, true, '', NULL, $query);
2205     }
2208 /**
2209  * Empty setting used to allow flags (advanced) on settings that can have no sensible default.
2210  * Note: Only advanced makes sense right now - locked does not.
2211  *
2212  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2213  */
2214 class admin_setting_configempty extends admin_setting_configtext {
2216     /**
2217      * @param string $name
2218      * @param string $visiblename
2219      * @param string $description
2220      */
2221     public function __construct($name, $visiblename, $description) {
2222         parent::__construct($name, $visiblename, $description, '', PARAM_RAW);
2223     }
2225     /**
2226      * Returns an XHTML string for the hidden field
2227      *
2228      * @param string $data
2229      * @param string $query
2230      * @return string XHTML string for the editor
2231      */
2232     public function output_html($data, $query='') {
2233         return format_admin_setting($this,
2234                                     $this->visiblename,
2235                                     '<div class="form-empty" >' .
2236                                     '<input type="hidden"' .
2237                                         ' id="'. $this->get_id() .'"' .
2238                                         ' name="'. $this->get_full_name() .'"' .
2239                                         ' value=""/></div>',
2240                                     $this->description,
2241                                     true,
2242                                     '',
2243                                     get_string('none'),
2244                                     $query);
2245     }
2249 /**
2250  * Path to directory
2251  *
2252  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2253  */
2254 class admin_setting_configfile extends admin_setting_configtext {
2255     /**
2256      * Constructor
2257      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2258      * @param string $visiblename localised
2259      * @param string $description long localised info
2260      * @param string $defaultdirectory default directory location
2261      */
2262     public function __construct($name, $visiblename, $description, $defaultdirectory) {
2263         parent::__construct($name, $visiblename, $description, $defaultdirectory, PARAM_RAW, 50);
2264     }
2266     /**
2267      * Returns XHTML for the field
2268      *
2269      * Returns XHTML for the field and also checks whether the file
2270      * specified in $data exists using file_exists()
2271      *
2272      * @param string $data File name and path to use in value attr
2273      * @param string $query
2274      * @return string XHTML field
2275      */
2276     public function output_html($data, $query='') {
2277         $default = $this->get_defaultsetting();
2279         if ($data) {
2280             if (file_exists($data)) {
2281                 $executable = '<span class="pathok">&#x2714;</span>';
2282             } else {
2283                 $executable = '<span class="patherror">&#x2718;</span>';
2284             }
2285         } else {
2286             $executable = '';
2287         }
2289         return format_admin_setting($this, $this->visiblename,
2290         '<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>',
2291         $this->description, true, '', $default, $query);
2292     }
2293     /**
2294      * checks if execpatch has been disabled in config.php
2295      */
2296     public function write_setting($data) {
2297         global $CFG;
2298         if (!empty($CFG->preventexecpath)) {
2299             return '';
2300         }
2301         return parent::write_setting($data);
2302     }
2306 /**
2307  * Path to executable file
2308  *
2309  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2310  */
2311 class admin_setting_configexecutable extends admin_setting_configfile {
2313     /**
2314      * Returns an XHTML field
2315      *
2316      * @param string $data This is the value for the field
2317      * @param string $query
2318      * @return string XHTML field
2319      */
2320     public function output_html($data, $query='') {
2321         global $CFG;
2322         $default = $this->get_defaultsetting();
2324         if ($data) {
2325             if (file_exists($data) and is_executable($data)) {
2326                 $executable = '<span class="pathok">&#x2714;</span>';
2327             } else {
2328                 $executable = '<span class="patherror">&#x2718;</span>';
2329             }
2330         } else {
2331             $executable = '';
2332         }
2333         if (!empty($CFG->preventexecpath)) {
2334             $this->visiblename .= '<div class="form-overridden">'.get_string('execpathnotallowed', 'admin').'</div>';
2335         }
2337         return format_admin_setting($this, $this->visiblename,
2338         '<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>',
2339         $this->description, true, '', $default, $query);
2340     }
2344 /**
2345  * Path to directory
2346  *
2347  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2348  */
2349 class admin_setting_configdirectory extends admin_setting_configfile {
2351     /**
2352      * Returns an XHTML field
2353      *
2354      * @param string $data This is the value for the field
2355      * @param string $query
2356      * @return string XHTML
2357      */
2358     public function output_html($data, $query='') {
2359         $default = $this->get_defaultsetting();
2361         if ($data) {
2362             if (file_exists($data) and is_dir($data)) {
2363                 $executable = '<span class="pathok">&#x2714;</span>';
2364             } else {
2365                 $executable = '<span class="patherror">&#x2718;</span>';
2366             }
2367         } else {
2368             $executable = '';
2369         }
2371         return format_admin_setting($this, $this->visiblename,
2372         '<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>',
2373         $this->description, true, '', $default, $query);
2374     }
2378 /**
2379  * Checkbox
2380  *
2381  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2382  */
2383 class admin_setting_configcheckbox extends admin_setting {
2384     /** @var string Value used when checked */
2385     public $yes;
2386     /** @var string Value used when not checked */
2387     public $no;
2389     /**
2390      * Constructor
2391      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2392      * @param string $visiblename localised
2393      * @param string $description long localised info
2394      * @param string $defaultsetting
2395      * @param string $yes value used when checked
2396      * @param string $no value used when not checked
2397      */
2398     public function __construct($name, $visiblename, $description, $defaultsetting, $yes='1', $no='0') {
2399         parent::__construct($name, $visiblename, $description, $defaultsetting);
2400         $this->yes = (string)$yes;
2401         $this->no  = (string)$no;
2402     }
2404     /**
2405      * Retrieves the current setting using the objects name
2406      *
2407      * @return string
2408      */
2409     public function get_setting() {
2410         return $this->config_read($this->name);
2411     }
2413     /**
2414      * Sets the value for the setting
2415      *
2416      * Sets the value for the setting to either the yes or no values
2417      * of the object by comparing $data to yes
2418      *
2419      * @param mixed $data Gets converted to str for comparison against yes value
2420      * @return string empty string or error
2421      */
2422     public function write_setting($data) {
2423         if ((string)$data === $this->yes) { // convert to strings before comparison
2424             $data = $this->yes;
2425         } else {
2426             $data = $this->no;
2427         }
2428         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2429     }
2431     /**
2432      * Returns an XHTML checkbox field
2433      *
2434      * @param string $data If $data matches yes then checkbox is checked
2435      * @param string $query
2436      * @return string XHTML field
2437      */
2438     public function output_html($data, $query='') {
2439         $default = $this->get_defaultsetting();
2441         if (!is_null($default)) {
2442             if ((string)$default === $this->yes) {
2443                 $defaultinfo = get_string('checkboxyes', 'admin');
2444             } else {
2445                 $defaultinfo = get_string('checkboxno', 'admin');
2446             }
2447         } else {
2448             $defaultinfo = NULL;
2449         }
2451         if ((string)$data === $this->yes) { // convert to strings before comparison
2452             $checked = 'checked="checked"';
2453         } else {
2454             $checked = '';
2455         }
2457         return format_admin_setting($this, $this->visiblename,
2458         '<div class="form-checkbox defaultsnext" ><input type="hidden" name="'.$this->get_full_name().'" value="'.s($this->no).'" /> '
2459             .'<input type="checkbox" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($this->yes).'" '.$checked.' /></div>',
2460         $this->description, true, '', $defaultinfo, $query);
2461     }
2465 /**
2466  * Multiple checkboxes, each represents different value, stored in csv format
2467  *
2468  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2469  */
2470 class admin_setting_configmulticheckbox extends admin_setting {
2471     /** @var array Array of choices value=>label */
2472     public $choices;
2474     /**
2475      * Constructor: uses parent::__construct
2476      *
2477      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2478      * @param string $visiblename localised
2479      * @param string $description long localised info
2480      * @param array $defaultsetting array of selected
2481      * @param array $choices array of $value=>$label for each checkbox
2482      */
2483     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2484         $this->choices = $choices;
2485         parent::__construct($name, $visiblename, $description, $defaultsetting);
2486     }
2488     /**
2489      * This public function may be used in ancestors for lazy loading of choices
2490      *
2491      * @todo Check if this function is still required content commented out only returns true
2492      * @return bool true if loaded, false if error
2493      */
2494     public function load_choices() {
2495         /*
2496         if (is_array($this->choices)) {
2497             return true;
2498         }
2499         .... load choices here
2500         */
2501         return true;
2502     }
2504     /**
2505      * Is setting related to query text - used when searching
2506      *
2507      * @param string $query
2508      * @return bool true on related, false on not or failure
2509      */
2510     public function is_related($query) {
2511         if (!$this->load_choices() or empty($this->choices)) {
2512             return false;
2513         }
2514         if (parent::is_related($query)) {
2515             return true;
2516         }
2518         foreach ($this->choices as $desc) {
2519             if (strpos(core_text::strtolower($desc), $query) !== false) {
2520                 return true;
2521             }
2522         }
2523         return false;
2524     }
2526     /**
2527      * Returns the current setting if it is set
2528      *
2529      * @return mixed null if null, else an array
2530      */
2531     public function get_setting() {
2532         $result = $this->config_read($this->name);
2534         if (is_null($result)) {
2535             return NULL;
2536         }
2537         if ($result === '') {
2538             return array();
2539         }
2540         $enabled = explode(',', $result);
2541         $setting = array();
2542         foreach ($enabled as $option) {
2543             $setting[$option] = 1;
2544         }
2545         return $setting;
2546     }
2548     /**
2549      * Saves the setting(s) provided in $data
2550      *
2551      * @param array $data An array of data, if not array returns empty str
2552      * @return mixed empty string on useless data or bool true=success, false=failed
2553      */
2554     public function write_setting($data) {
2555         if (!is_array($data)) {
2556             return ''; // ignore it
2557         }
2558         if (!$this->load_choices() or empty($this->choices)) {
2559             return '';
2560         }
2561         unset($data['xxxxx']);
2562         $result = array();
2563         foreach ($data as $key => $value) {
2564             if ($value and array_key_exists($key, $this->choices)) {
2565                 $result[] = $key;
2566             }
2567         }
2568         return $this->config_write($this->name, implode(',', $result)) ? '' : get_string('errorsetting', 'admin');
2569     }
2571     /**
2572      * Returns XHTML field(s) as required by choices
2573      *
2574      * Relies on data being an array should data ever be another valid vartype with
2575      * acceptable value this may cause a warning/error
2576      * if (!is_array($data)) would fix the problem
2577      *
2578      * @todo Add vartype handling to ensure $data is an array
2579      *
2580      * @param array $data An array of checked values
2581      * @param string $query
2582      * @return string XHTML field
2583      */
2584     public function output_html($data, $query='') {
2585         if (!$this->load_choices() or empty($this->choices)) {
2586             return '';
2587         }
2588         $default = $this->get_defaultsetting();
2589         if (is_null($default)) {
2590             $default = array();
2591         }
2592         if (is_null($data)) {
2593             $data = array();
2594         }
2595         $options = array();
2596         $defaults = array();
2597         foreach ($this->choices as $key=>$description) {
2598             if (!empty($data[$key])) {
2599                 $checked = 'checked="checked"';
2600             } else {
2601                 $checked = '';
2602             }
2603             if (!empty($default[$key])) {
2604                 $defaults[] = $description;
2605             }
2607             $options[] = '<input type="checkbox" id="'.$this->get_id().'_'.$key.'" name="'.$this->get_full_name().'['.$key.']" value="1" '.$checked.' />'
2608                 .'<label for="'.$this->get_id().'_'.$key.'">'.highlightfast($query, $description).'</label>';
2609         }
2611         if (is_null($default)) {
2612             $defaultinfo = NULL;
2613         } else if (!empty($defaults)) {
2614                 $defaultinfo = implode(', ', $defaults);
2615             } else {
2616                 $defaultinfo = get_string('none');
2617             }
2619         $return = '<div class="form-multicheckbox">';
2620         $return .= '<input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2621         if ($options) {
2622             $return .= '<ul>';
2623             foreach ($options as $option) {
2624                 $return .= '<li>'.$option.'</li>';
2625             }
2626             $return .= '</ul>';
2627         }
2628         $return .= '</div>';
2630         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
2632     }
2636 /**
2637  * Multiple checkboxes 2, value stored as string 00101011
2638  *
2639  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2640  */
2641 class admin_setting_configmulticheckbox2 extends admin_setting_configmulticheckbox {
2643     /**
2644      * Returns the setting if set
2645      *
2646      * @return mixed null if not set, else an array of set settings
2647      */
2648     public function get_setting() {
2649         $result = $this->config_read($this->name);
2650         if (is_null($result)) {
2651             return NULL;
2652         }
2653         if (!$this->load_choices()) {
2654             return NULL;
2655         }
2656         $result = str_pad($result, count($this->choices), '0');
2657         $result = preg_split('//', $result, -1, PREG_SPLIT_NO_EMPTY);
2658         $setting = array();
2659         foreach ($this->choices as $key=>$unused) {
2660             $value = array_shift($result);
2661             if ($value) {
2662                 $setting[$key] = 1;
2663             }
2664         }
2665         return $setting;
2666     }
2668     /**
2669      * Save setting(s) provided in $data param
2670      *
2671      * @param array $data An array of settings to save
2672      * @return mixed empty string for bad data or bool true=>success, false=>error
2673      */
2674     public function write_setting($data) {
2675         if (!is_array($data)) {
2676             return ''; // ignore it
2677         }
2678         if (!$this->load_choices() or empty($this->choices)) {
2679             return '';
2680         }
2681         $result = '';
2682         foreach ($this->choices as $key=>$unused) {
2683             if (!empty($data[$key])) {
2684                 $result .= '1';
2685             } else {
2686                 $result .= '0';
2687             }
2688         }
2689         return $this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin');
2690     }
2694 /**
2695  * Select one value from list
2696  *
2697  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2698  */
2699 class admin_setting_configselect extends admin_setting {
2700     /** @var array Array of choices value=>label */
2701     public $choices;
2703     /**
2704      * Constructor
2705      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2706      * @param string $visiblename localised
2707      * @param string $description long localised info
2708      * @param string|int $defaultsetting
2709      * @param array $choices array of $value=>$label for each selection
2710      */
2711     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2712         $this->choices = $choices;
2713         parent::__construct($name, $visiblename, $description, $defaultsetting);
2714     }
2716     /**
2717      * This function may be used in ancestors for lazy loading of choices
2718      *
2719      * Override this method if loading of choices is expensive, such
2720      * as when it requires multiple db requests.
2721      *
2722      * @return bool true if loaded, false if error
2723      */
2724     public function load_choices() {
2725         /*
2726         if (is_array($this->choices)) {
2727             return true;
2728         }
2729         .... load choices here
2730         */
2731         return true;
2732     }
2734     /**
2735      * Check if this is $query is related to a choice
2736      *
2737      * @param string $query
2738      * @return bool true if related, false if not
2739      */
2740     public function is_related($query) {
2741         if (parent::is_related($query)) {
2742             return true;
2743         }
2744         if (!$this->load_choices()) {
2745             return false;
2746         }
2747         foreach ($this->choices as $key=>$value) {
2748             if (strpos(core_text::strtolower($key), $query) !== false) {
2749                 return true;
2750             }
2751             if (strpos(core_text::strtolower($value), $query) !== false) {
2752                 return true;
2753             }
2754         }
2755         return false;
2756     }
2758     /**
2759      * Return the setting
2760      *
2761      * @return mixed returns config if successful else null
2762      */
2763     public function get_setting() {
2764         return $this->config_read($this->name);
2765     }
2767     /**
2768      * Save a setting
2769      *
2770      * @param string $data
2771      * @return string empty of error string
2772      */
2773     public function write_setting($data) {
2774         if (!$this->load_choices() or empty($this->choices)) {
2775             return '';
2776         }
2777         if (!array_key_exists($data, $this->choices)) {
2778             return ''; // ignore it
2779         }
2781         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2782     }
2784     /**
2785      * Returns XHTML select field
2786      *
2787      * Ensure the options are loaded, and generate the XHTML for the select
2788      * element and any warning message. Separating this out from output_html
2789      * makes it easier to subclass this class.
2790      *
2791      * @param string $data the option to show as selected.
2792      * @param string $current the currently selected option in the database, null if none.
2793      * @param string $default the default selected option.
2794      * @return array the HTML for the select element, and a warning message.
2795      */
2796     public function output_select_html($data, $current, $default, $extraname = '') {
2797         if (!$this->load_choices() or empty($this->choices)) {
2798             return array('', '');
2799         }
2801         $warning = '';
2802         if (is_null($current)) {
2803         // first run
2804         } else if (empty($current) and (array_key_exists('', $this->choices) or array_key_exists(0, $this->choices))) {
2805             // no warning
2806             } else if (!array_key_exists($current, $this->choices)) {
2807                     $warning = get_string('warningcurrentsetting', 'admin', s($current));
2808                     if (!is_null($default) and $data == $current) {
2809                         $data = $default; // use default instead of first value when showing the form
2810                     }
2811                 }
2813         $selecthtml = '<select id="'.$this->get_id().'" name="'.$this->get_full_name().$extraname.'">';
2814         foreach ($this->choices as $key => $value) {
2815         // the string cast is needed because key may be integer - 0 is equal to most strings!
2816             $selecthtml .= '<option value="'.$key.'"'.((string)$key==$data ? ' selected="selected"' : '').'>'.$value.'</option>';
2817         }
2818         $selecthtml .= '</select>';
2819         return array($selecthtml, $warning);
2820     }
2822     /**
2823      * Returns XHTML select field and wrapping div(s)
2824      *
2825      * @see output_select_html()
2826      *
2827      * @param string $data the option to show as selected
2828      * @param string $query
2829      * @return string XHTML field and wrapping div
2830      */
2831     public function output_html($data, $query='') {
2832         $default = $this->get_defaultsetting();
2833         $current = $this->get_setting();
2835         list($selecthtml, $warning) = $this->output_select_html($data, $current, $default);
2836         if (!$selecthtml) {
2837             return '';
2838         }
2840         if (!is_null($default) and array_key_exists($default, $this->choices)) {
2841             $defaultinfo = $this->choices[$default];
2842         } else {
2843             $defaultinfo = NULL;
2844         }
2846         $return = '<div class="form-select defaultsnext">' . $selecthtml . '</div>';
2848         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, $warning, $defaultinfo, $query);
2849     }
2853 /**
2854  * Select multiple items from list
2855  *
2856  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2857  */
2858 class admin_setting_configmultiselect extends admin_setting_configselect {
2859     /**
2860      * Constructor
2861      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2862      * @param string $visiblename localised
2863      * @param string $description long localised info
2864      * @param array $defaultsetting array of selected items
2865      * @param array $choices array of $value=>$label for each list item
2866      */
2867     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2868         parent::__construct($name, $visiblename, $description, $defaultsetting, $choices);
2869     }
2871     /**
2872      * Returns the select setting(s)
2873      *
2874      * @return mixed null or array. Null if no settings else array of setting(s)
2875      */
2876     public function get_setting() {
2877         $result = $this->config_read($this->name);
2878         if (is_null($result)) {
2879             return NULL;
2880         }
2881         if ($result === '') {
2882             return array();
2883         }
2884         return explode(',', $result);
2885     }
2887     /**
2888      * Saves setting(s) provided through $data
2889      *
2890      * Potential bug in the works should anyone call with this function
2891      * using a vartype that is not an array
2892      *
2893      * @param array $data
2894      */
2895     public function write_setting($data) {
2896         if (!is_array($data)) {
2897             return ''; //ignore it
2898         }
2899         if (!$this->load_choices() or empty($this->choices)) {
2900             return '';
2901         }
2903         unset($data['xxxxx']);
2905         $save = array();
2906         foreach ($data as $value) {
2907             if (!array_key_exists($value, $this->choices)) {
2908                 continue; // ignore it
2909             }
2910             $save[] = $value;
2911         }
2913         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
2914     }
2916     /**
2917      * Is setting related to query text - used when searching
2918      *
2919      * @param string $query
2920      * @return bool true if related, false if not
2921      */
2922     public function is_related($query) {
2923         if (!$this->load_choices() or empty($this->choices)) {
2924             return false;
2925         }
2926         if (parent::is_related($query)) {
2927             return true;
2928         }
2930         foreach ($this->choices as $desc) {
2931             if (strpos(core_text::strtolower($desc), $query) !== false) {
2932                 return true;
2933             }
2934         }
2935         return false;
2936     }
2938     /**
2939      * Returns XHTML multi-select field
2940      *
2941      * @todo Add vartype handling to ensure $data is an array
2942      * @param array $data Array of values to select by default
2943      * @param string $query
2944      * @return string XHTML multi-select field
2945      */
2946     public function output_html($data, $query='') {
2947         if (!$this->load_choices() or empty($this->choices)) {
2948             return '';
2949         }
2950         $choices = $this->choices;
2951         $default = $this->get_defaultsetting();
2952         if (is_null($default)) {
2953             $default = array();
2954         }
2955         if (is_null($data)) {
2956             $data = array();
2957         }
2959         $defaults = array();
2960         $size = min(10, count($this->choices));
2961         $return = '<div class="form-select"><input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2962         $return .= '<select id="'.$this->get_id().'" name="'.$this->get_full_name().'[]" size="'.$size.'" multiple="multiple">';
2963         foreach ($this->choices as $key => $description) {
2964             if (in_array($key, $data)) {
2965                 $selected = 'selected="selected"';
2966             } else {
2967                 $selected = '';
2968             }
2969             if (in_array($key, $default)) {
2970                 $defaults[] = $description;
2971             }
2973             $return .= '<option value="'.s($key).'" '.$selected.'>'.$description.'</option>';
2974         }
2976         if (is_null($default)) {
2977             $defaultinfo = NULL;
2978         } if (!empty($defaults)) {
2979             $defaultinfo = implode(', ', $defaults);
2980         } else {
2981             $defaultinfo = get_string('none');
2982         }
2984         $return .= '</select></div>';
2985         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, '', $defaultinfo, $query);
2986     }
2989 /**
2990  * Time selector
2991  *
2992  * This is a liiitle bit messy. we're using two selects, but we're returning
2993  * them as an array named after $name (so we only use $name2 internally for the setting)
2994  *
2995  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2996  */
2997 class admin_setting_configtime extends admin_setting {
2998     /** @var string Used for setting second select (minutes) */
2999     public $name2;
3001     /**
3002      * Constructor
3003      * @param string $hoursname setting for hours
3004      * @param string $minutesname setting for hours
3005      * @param string $visiblename localised
3006      * @param string $description long localised info
3007      * @param array $defaultsetting array representing default time 'h'=>hours, 'm'=>minutes
3008      */
3009     public function __construct($hoursname, $minutesname, $visiblename, $description, $defaultsetting) {
3010         $this->name2 = $minutesname;
3011         parent::__construct($hoursname, $visiblename, $description, $defaultsetting);
3012     }
3014     /**
3015      * Get the selected time
3016      *
3017      * @return mixed An array containing 'h'=>xx, 'm'=>xx, or null if not set
3018      */
3019     public function get_setting() {
3020         $result1 = $this->config_read($this->name);
3021         $result2 = $this->config_read($this->name2);
3022         if (is_null($result1) or is_null($result2)) {
3023             return NULL;
3024         }
3026         return array('h' => $result1, 'm' => $result2);
3027     }
3029     /**
3030      * Store the time (hours and minutes)
3031      *
3032      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3033      * @return bool true if success, false if not
3034      */
3035     public function write_setting($data) {
3036         if (!is_array($data)) {
3037             return '';
3038         }
3040         $result = $this->config_write($this->name, (int)$data['h']) && $this->config_write($this->name2, (int)$data['m']);
3041         return ($result ? '' : get_string('errorsetting', 'admin'));
3042     }
3044     /**
3045      * Returns XHTML time select fields
3046      *
3047      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3048      * @param string $query
3049      * @return string XHTML time select fields and wrapping div(s)
3050      */
3051     public function output_html($data, $query='') {
3052         $default = $this->get_defaultsetting();
3054         if (is_array($default)) {
3055             $defaultinfo = $default['h'].':'.$default['m'];
3056         } else {
3057             $defaultinfo = NULL;
3058         }
3060         $return = '<div class="form-time defaultsnext">'.
3061             '<select id="'.$this->get_id().'h" name="'.$this->get_full_name().'[h]">';
3062         for ($i = 0; $i < 24; $i++) {
3063             $return .= '<option value="'.$i.'"'.($i == $data['h'] ? ' selected="selected"' : '').'>'.$i.'</option>';
3064         }
3065         $return .= '</select>:<select id="'.$this->get_id().'m" name="'.$this->get_full_name().'[m]">';
3066         for ($i = 0; $i < 60; $i += 5) {
3067             $return .= '<option value="'.$i.'"'.($i == $data['m'] ? ' selected="selected"' : '').'>'.$i.'</option>';
3068         }
3069         $return .= '</select></div>';
3070         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
3071     }
3076 /**
3077  * Seconds duration setting.
3078  *
3079  * @copyright 2012 Petr Skoda (http://skodak.org)
3080  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3081  */
3082 class admin_setting_configduration extends admin_setting {
3084     /** @var int default duration unit */
3085     protected $defaultunit;
3087     /**
3088      * Constructor
3089      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
3090      *                     or 'myplugin/mysetting' for ones in config_plugins.
3091      * @param string $visiblename localised name
3092      * @param string $description localised long description
3093      * @param mixed $defaultsetting string or array depending on implementation
3094      * @param int $defaultunit - day, week, etc. (in seconds)
3095      */
3096     public function __construct($name, $visiblename, $description, $defaultsetting, $defaultunit = 86400) {
3097         if (is_number($defaultsetting)) {
3098             $defaultsetting = self::parse_seconds($defaultsetting);
3099         }
3100         $units = self::get_units();
3101         if (isset($units[$defaultunit])) {
3102             $this->defaultunit = $defaultunit;
3103         } else {
3104             $this->defaultunit = 86400;
3105         }
3106         parent::__construct($name, $visiblename, $description, $defaultsetting);
3107     }
3109     /**
3110      * Returns selectable units.
3111      * @static
3112      * @return array
3113      */
3114     protected static function get_units() {
3115         return array(
3116             604800 => get_string('weeks'),
3117             86400 => get_string('days'),
3118             3600 => get_string('hours'),
3119             60 => get_string('minutes'),
3120             1 => get_string('seconds'),
3121         );
3122     }
3124     /**
3125      * Converts seconds to some more user friendly string.
3126      * @static
3127      * @param int $seconds
3128      * @return string
3129      */
3130     protected static function get_duration_text($seconds) {
3131         if (empty($seconds)) {
3132             return get_string('none');
3133         }
3134         $data = self::parse_seconds($seconds);
3135         switch ($data['u']) {
3136             case (60*60*24*7):
3137                 return get_string('numweeks', '', $data['v']);
3138             case (60*60*24):
3139                 return get_string('numdays', '', $data['v']);
3140             case (60*60):
3141                 return get_string('numhours', '', $data['v']);
3142             case (60):
3143                 return get_string('numminutes', '', $data['v']);
3144             default:
3145                 return get_string('numseconds', '', $data['v']*$data['u']);
3146         }
3147     }
3149     /**
3150      * Finds suitable units for given duration.
3151      * @static
3152      * @param int $seconds
3153      * @return array
3154      */
3155     protected static function parse_seconds($seconds) {
3156         foreach (self::get_units() as $unit => $unused) {
3157             if ($seconds % $unit === 0) {
3158                 return array('v'=>(int)($seconds/$unit), 'u'=>$unit);
3159             }
3160         }
3161         return array('v'=>(int)$seconds, 'u'=>1);
3162     }
3164     /**
3165      * Get the selected duration as array.
3166      *
3167      * @return mixed An array containing 'v'=>xx, 'u'=>xx, or null if not set
3168      */
3169     public function get_setting() {
3170         $seconds = $this->config_read($this->name);
3171         if (is_null($seconds)) {
3172             return null;
3173         }
3175         return self::parse_seconds($seconds);
3176     }
3178     /**
3179      * Store the duration as seconds.
3180      *
3181      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3182      * @return bool true if success, false if not
3183      */
3184     public function write_setting($data) {
3185         if (!is_array($data)) {
3186             return '';
3187         }
3189         $seconds = (int)($data['v']*$data['u']);
3190         if ($seconds < 0) {
3191             return get_string('errorsetting', 'admin');
3192         }
3194         $result = $this->config_write($this->name, $seconds);
3195         return ($result ? '' : get_string('errorsetting', 'admin'));
3196     }
3198     /**
3199      * Returns duration text+select fields.
3200      *
3201      * @param array $data Must be form 'v'=>xx, 'u'=>xx
3202      * @param string $query
3203      * @return string duration text+select fields and wrapping div(s)
3204      */
3205     public function output_html($data, $query='') {
3206         $default = $this->get_defaultsetting();
3208         if (is_number($default)) {
3209             $defaultinfo = self::get_duration_text($default);
3210         } else if (is_array($default)) {
3211             $defaultinfo = self::get_duration_text($default['v']*$default['u']);
3212         } else {
3213             $defaultinfo = null;
3214         }
3216         $units = self::get_units();
3218         $return = '<div class="form-duration defaultsnext">';
3219         $return .= '<input type="text" size="5" id="'.$this->get_id().'v" name="'.$this->get_full_name().'[v]" value="'.s($data['v']).'" />';
3220         $return .= '<select id="'.$this->get_id().'u" name="'.$this->get_full_name().'[u]">';
3221         foreach ($units as $val => $text) {
3222             $selected = '';
3223             if ($data['v'] == 0) {
3224                 if ($val == $this->defaultunit) {
3225                     $selected = ' selected="selected"';
3226                 }
3227             } else if ($val == $data['u']) {
3228                 $selected = ' selected="selected"';
3229             }
3230             $return .= '<option value="'.$val.'"'.$selected.'>'.$text.'</option>';
3231         }
3232         $return .= '</select></div>';
3233         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
3234     }
3238 /**
3239  * Used to validate a textarea used for ip addresses
3240  *
3241  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3242  */
3243 class admin_setting_configiplist extends admin_setting_configtextarea {
3245     /**
3246      * Validate the contents of the textarea as IP addresses
3247      *
3248      * Used to validate a new line separated list of IP addresses collected from
3249      * a textarea control
3250      *
3251      * @param string $data A list of IP Addresses separated by new lines
3252      * @return mixed bool true for success or string:error on failure
3253      */
3254     public function validate($data) {
3255         if(!empty($data)) {
3256             $ips = explode("\n", $data);
3257         } else {
3258             return true;
3259         }
3260         $result = true;
3261         foreach($ips as $ip) {
3262             $ip = trim($ip);
3263             if (preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}$#', $ip, $match) ||
3264                 preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}(\/\d{1,2})$#', $ip, $match) ||
3265                 preg_match('#^(\d{1,3})(\.\d{1,3}){3}(-\d{1,3})$#', $ip, $match)) {
3266                 $result = true;
3267             } else {
3268                 $result = false;
3269                 break;
3270             }
3271         }
3272         if($result) {
3273             return true;
3274         } else {
3275             return get_string('validateerror', 'admin');
3276         }
3277     }
3281 /**
3282  * An admin setting for selecting one or more users who have a capability
3283  * in the system context
3284  *
3285  * An admin setting for selecting one or more users, who have a particular capability
3286  * in the system context. Warning, make sure the list will never be too long. There is
3287  * no paging or searching of this list.
3288  *
3289  * To correctly get a list of users from this config setting, you need to call the
3290  * get_users_from_config($CFG->mysetting, $capability); function in moodlelib.php.
3291  *
3292  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3293  */
3294 class admin_setting_users_with_capability extends admin_setting_configmultiselect {
3295     /** @var string The capabilities name */
3296     protected $capability;
3297     /** @var int include admin users too */
3298     protected $includeadmins;
3300     /**
3301      * Constructor.
3302      *
3303      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
3304      * @param string $visiblename localised name
3305      * @param string $description localised long description
3306      * @param array $defaultsetting array of usernames
3307      * @param string $capability string capability name.
3308      * @param bool $includeadmins include administrators
3309      */
3310     function __construct($name, $visiblename, $description, $defaultsetting, $capability, $includeadmins = true) {
3311         $this->capability    = $capability;
3312         $this->includeadmins = $includeadmins;
3313         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
3314     }
3316     /**
3317      * Load all of the uses who have the capability into choice array
3318      *
3319      * @return bool Always returns true
3320      */
3321     function load_choices() {
3322         if (is_array($this->choices)) {
3323             return true;
3324         }
3325         list($sort, $sortparams) = users_order_by_sql('u');
3326         if (!empty($sortparams)) {
3327             throw new coding_exception('users_order_by_sql returned some query parameters. ' .
3328                     'This is unexpected, and a problem because there is no way to pass these ' .
3329                     'parameters to get_users_by_capability. See MDL-34657.');
3330         }
3331         $users = get_users_by_capability(context_system::instance(),
3332                 $this->capability, 'u.id,u.username,u.firstname,u.lastname', $sort);
3333         $this->choices = array(
3334             '$@NONE@$' => get_string('nobody'),
3335             '$@ALL@$' => get_string('everyonewhocan', 'admin', get_capability_string($this->capability)),
3336         );
3337         if ($this->includeadmins) {
3338             $admins = get_admins();
3339             foreach ($admins as $user) {
3340                 $this->choices[$user->id] = fullname($user);
3341             }
3342         }
3343         if (is_array($users)) {
3344             foreach ($users as $user) {
3345                 $this->choices[$user->id] = fullname($user);
3346             }
3347         }
3348         return true;
3349     }
3351     /**
3352      * Returns the default setting for class
3353      *
3354      * @return mixed Array, or string. Empty string if no default
3355      */
3356     public function get_defaultsetting() {
3357         $this->load_choices();
3358         $defaultsetting = parent::get_defaultsetting();
3359         if (empty($defaultsetting)) {
3360             return array('$@NONE@$');
3361         } else if (array_key_exists($defaultsetting, $this->choices)) {
3362                 return $defaultsetting;
3363             } else {
3364                 return '';
3365             }
3366     }
3368     /**
3369      * Returns the current setting
3370      *
3371      * @return mixed array or string
3372      */
3373     public function get_setting() {
3374         $result = parent::get_setting();
3375         if ($result === null) {
3376             // this is necessary for settings upgrade
3377             return null;
3378         }
3379         if (empty($result)) {
3380             $result = array('$@NONE@$');
3381         }
3382         return $result;
3383     }
3385     /**
3386      * Save the chosen setting provided as $data
3387      *
3388      * @param array $data
3389      * @return mixed string or array
3390      */
3391     public function write_setting($data) {
3392     // If all is selected, remove any explicit options.
3393         if (in_array('$@ALL@$', $data)) {
3394             $data = array('$@ALL@$');
3395         }
3396         // None never needs to be written to the DB.
3397         if (in_array('$@NONE@$', $data)) {
3398             unset($data[array_search('$@NONE@$', $data)]);
3399         }
3400         return parent::write_setting($data);
3401     }
3405 /**
3406  * Special checkbox for calendar - resets SESSION vars.
3407  *
3408  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3409  */
3410 class admin_setting_special_adminseesall extends admin_setting_configcheckbox {
3411     /**
3412      * Calls the parent::__construct with default values
3413      *
3414      * name =>  calendar_adminseesall
3415      * visiblename => get_string('adminseesall', 'admin')
3416      * description => get_string('helpadminseesall', 'admin')
3417      * defaultsetting => 0
3418      */
3419     public function __construct() {
3420         parent::__construct('calendar_adminseesall', get_string('adminseesall', 'admin'),
3421             get_string('helpadminseesall', 'admin'), '0');
3422     }
3424     /**
3425      * Stores the setting passed in $data
3426      *
3427      * @param mixed gets converted to string for comparison
3428      * @return string empty string or error message
3429      */
3430     public function write_setting($data) {
3431         global $SESSION;
3432         return parent::write_setting($data);
3433     }
3436 /**
3437  * Special select for settings that are altered in setup.php and can not be altered on the fly
3438  *
3439  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3440  */
3441 class admin_setting_special_selectsetup extends admin_setting_configselect {
3442     /**
3443      * Reads the setting directly from the database
3444      *
3445      * @return mixed
3446      */
3447     public function get_setting() {
3448     // read directly from db!
3449         return get_config(NULL, $this->name);
3450     }
3452     /**
3453      * Save the setting passed in $data
3454      *
3455      * @param string $data The setting to save
3456      * @return string empty or error message
3457      */
3458     public function write_setting($data) {
3459         global $CFG;
3460         // do not change active CFG setting!
3461         $current = $CFG->{$this->name};
3462         $result = parent::write_setting($data);
3463         $CFG->{$this->name} = $current;
3464         return $result;
3465     }
3469 /**
3470  * Special select for frontpage - stores data in course table
3471  *
3472  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3473  */
3474 class admin_setting_sitesetselect extends admin_setting_configselect {
3475     /**
3476      * Returns the site name for the selected site
3477      *
3478      * @see get_site()
3479      * @return string The site name of the selected site
3480      */
3481     public function get_setting() {
3482         $site = course_get_format(get_site())->get_course();
3483         return $site->{$this->name};
3484     }
3486     /**
3487      * Updates the database and save the setting
3488      *
3489      * @param string data
3490      * @return string empty or error message
3491      */
3492     public function write_setting($data) {
3493         global $DB, $SITE, $COURSE;
3494         if (!in_array($data, array_keys($this->choices))) {
3495             return get_string('errorsetting', 'admin');
3496         }
3497         $record = new stdClass();
3498         $record->id           = SITEID;
3499         $temp                 = $this->name;
3500         $record->$temp        = $data;
3501         $record->timemodified = time();
3503         course_get_format($SITE)->update_course_format_options($record);
3504         $DB->update_record('course', $record);
3506         // Reset caches.
3507         $SITE = $DB->get_record('course', array('id'=>$SITE->id), '*', MUST_EXIST);
3508         if ($SITE->id == $COURSE->id) {
3509             $COURSE = $SITE;
3510         }
3511         format_base::reset_course_cache($SITE->id);
3513         return '';
3515     }
3519 /**
3520  * Select for blog's bloglevel setting: if set to 0, will set blog_menu
3521  * block to hidden.
3522  *
3523  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3524  */
3525 class admin_setting_bloglevel extends admin_setting_configselect {
3526     /**
3527      * Updates the database and save the setting
3528      *
3529      * @param string data
3530      * @return string empty or error message
3531      */
3532     public function write_setting($data) {
3533         global $DB, $CFG;
3534         if ($data == 0) {
3535             $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 1");
3536             foreach ($blogblocks as $block) {
3537                 $DB->set_field('block', 'visible', 0, array('id' => $block->id));
3538             }
3539         } else {
3540             // reenable all blocks only when switching from disabled blogs
3541             if (isset($CFG->bloglevel) and $CFG->bloglevel == 0) {
3542                 $blogblocks = $DB->get_records_select('block', "name LIKE 'blog_%' AND visible = 0");
3543                 foreach ($blogblocks as $block) {
3544                     $DB->set_field('block', 'visible', 1, array('id' => $block->id));
3545                 }
3546             }
3547         }
3548         return parent::write_setting($data);
3549     }
3553 /**
3554  * Special select - lists on the frontpage - hacky
3555  *
3556  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3557  */
3558 class admin_setting_courselist_frontpage extends admin_setting {
3559     /** @var array Array of choices value=>label */
3560     public $choices;
3562     /**
3563      * Construct override, requires one param
3564      *
3565      * @param bool $loggedin Is the user logged in
3566      */
3567     public function __construct($loggedin) {
3568         global $CFG;
3569         require_once($CFG->dirroot.'/course/lib.php');
3570         $name        = 'frontpage'.($loggedin ? 'loggedin' : '');
3571         $visiblename = get_string('frontpage'.($loggedin ? 'loggedin' : ''),'admin');
3572         $description = get_string('configfrontpage'.($loggedin ? 'loggedin' : ''),'admin');
3573         $defaults    = array(FRONTPAGEALLCOURSELIST);
3574         parent::__construct($name, $visiblename, $description, $defaults);
3575     }
3577     /**
3578      * Loads the choices available
3579      *
3580      * @return bool always returns true
3581      */
3582     public function load_choices() {
3583         if (is_array($this->choices)) {
3584             return true;
3585         }
3586         $this->choices = array(FRONTPAGENEWS          => get_string('frontpagenews'),
3587             FRONTPAGEALLCOURSELIST => get_string('frontpagecourselist'),
3588             FRONTPAGEENROLLEDCOURSELIST => get_string('frontpageenrolledcourselist'),
3589             FRONTPAGECATEGORYNAMES => get_string('frontpagecategorynames'),
3590             FRONTPAGECATEGORYCOMBO => get_string('frontpagecategorycombo'),
3591             FRONTPAGECOURSESEARCH  => get_string('frontpagecoursesearch'),
3592             'none'                 => get_string('none'));
3593         if ($this->name === 'frontpage') {
3594             unset($this->choices[FRONTPAGEENROLLEDCOURSELIST]);
3595         }
3596         return true;
3597     }
3599     /**
3600      * Returns the selected settings
3601      *
3602      * @param mixed array or setting or null
3603      */
3604     public function get_setting() {
3605         $result = $this->config_read($this->name);
3606         if (is_null($result)) {
3607             return NULL;
3608         }
3609         if ($result === '') {
3610             return array();
3611         }
3612         return explode(',', $result);
3613     }
3615     /**
3616      * Save the selected options
3617      *
3618      * @param array $data
3619      * @return mixed empty string (data is not an array) or bool true=success false=failure
3620      */
3621     public function write_setting($data) {
3622         if (!is_array($data)) {
3623             return '';
3624         }
3625         $this->load_choices();
3626         $save = array();
3627         foreach($data as $datum) {
3628             if ($datum == 'none' or !array_key_exists($datum, $this->choices)) {
3629                 continue;
3630             }
3631             $save[$datum] = $datum; // no duplicates
3632         }
3633         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
3634     }
3636     /**
3637      * Return XHTML select field and wrapping div
3638      *
3639      * @todo Add vartype handling to make sure $data is an array
3640      * @param array $data Array of elements to select by default
3641      * @return string XHTML select field and wrapping div
3642      */
3643     public function output_html($data, $query='') {
3644         $this->load_choices();
3645         $currentsetting = array();
3646         foreach ($data as $key) {
3647             if ($key != 'none' and array_key_exists($key, $this->choices)) {
3648                 $currentsetting[] = $key; // already selected first
3649             }
3650         }
3652         $return = '<div class="form-group">';
3653         for ($i = 0; $i < count($this->choices) - 1; $i++) {
3654             if (!array_key_exists($i, $currentsetting)) {
3655                 $currentsetting[$i] = 'none'; //none
3656             }
3657             $return .='<select class="form-select" id="'.$this->get_id().$i.'" name="'.$this->get_full_name().'[]">';
3658             foreach ($this->choices as $key => $value) {
3659                 $return .= '<option value="'.$key.'"'.("$key" == $currentsetting[$i] ? ' selected="selected"' : '').'>'.$value.'</option>';
3660             }
3661             $return .= '</select>';
3662             if ($i !== count($this->choices) - 2) {
3663                 $return .= '<br />';
3664             }