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