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