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