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