MDL-66999 theme_boost: @extend replace .alert
[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(__DIR__.'/../../config.php');
59  *         require_once($CFG->libdir.'/adminlib.php');
60  *         admin_externalpage_setup('foo');
61  *         // functionality like processing form submissions goes here
62  *         echo $OUTPUT->header();
63  *         // your HTML goes here
64  *         echo $OUTPUT->footer();
65  * </code>
66  *
67  *  The admin_externalpage_setup() function call ensures the user is logged in,
68  *  and makes sure that they have the proper role permission to access the page.
69  *  It also configures all $PAGE properties needed for navigation.
70  *
71  *  ADMIN_CATEGORY OBJECTS
72  *
73  *  Above and beyond all this, we have admin_category objects. These objects
74  *  appear as folders in the admin tree block. They contain admin_settingpage's,
75  *  admin_externalpage's, and other admin_category's.
76  *
77  *  OTHER NOTES
78  *
79  *  admin_settingpage's, admin_externalpage's, and admin_category's all inherit
80  *  from part_of_admin_tree (a pseudointerface). This interface insists that
81  *  a class has a check_access method for access permissions, a locate method
82  *  used to find a specific node in the admin tree and find parent path.
83  *
84  *  admin_category's inherit from parentable_part_of_admin_tree. This pseudo-
85  *  interface ensures that the class implements a recursive add function which
86  *  accepts a part_of_admin_tree object and searches for the proper place to
87  *  put it. parentable_part_of_admin_tree implies part_of_admin_tree.
88  *
89  *  Please note that the $this->name field of any part_of_admin_tree must be
90  *  UNIQUE throughout the ENTIRE admin tree.
91  *
92  *  The $this->name field of an admin_setting object (which is *not* part_of_
93  *  admin_tree) must be unique on the respective admin_settingpage where it is
94  *  used.
95  *
96  * Original author: Vincenzo K. Marcovecchio
97  * Maintainer:      Petr Skoda
98  *
99  * @package    core
100  * @subpackage admin
101  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
102  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
103  */
105 defined('MOODLE_INTERNAL') || die();
107 /// Add libraries
108 require_once($CFG->libdir.'/ddllib.php');
109 require_once($CFG->libdir.'/xmlize.php');
110 require_once($CFG->libdir.'/messagelib.php');
112 define('INSECURE_DATAROOT_WARNING', 1);
113 define('INSECURE_DATAROOT_ERROR', 2);
115 /**
116  * Automatically clean-up all plugin data and remove the plugin DB tables
117  *
118  * NOTE: do not call directly, use new /admin/plugins.php?uninstall=component instead!
119  *
120  * @param string $type The plugin type, eg. 'mod', 'qtype', 'workshopgrading' etc.
121  * @param string $name The plugin name, eg. 'forum', 'multichoice', 'accumulative' etc.
122  * @uses global $OUTPUT to produce notices and other messages
123  * @return void
124  */
125 function uninstall_plugin($type, $name) {
126     global $CFG, $DB, $OUTPUT;
128     // This may take a long time.
129     core_php_time_limit::raise();
131     // Recursively uninstall all subplugins first.
132     $subplugintypes = core_component::get_plugin_types_with_subplugins();
133     if (isset($subplugintypes[$type])) {
134         $base = core_component::get_plugin_directory($type, $name);
136         $subpluginsfile = "{$base}/db/subplugins.json";
137         if (file_exists($subpluginsfile)) {
138             $subplugins = (array) json_decode(file_get_contents($subpluginsfile))->plugintypes;
139         } else if (file_exists("{$base}/db/subplugins.php")) {
140             debugging('Use of subplugins.php has been deprecated. ' .
141                     'Please update your plugin to provide a subplugins.json file instead.',
142                     DEBUG_DEVELOPER);
143             $subplugins = [];
144             include("{$base}/db/subplugins.php");
145         }
147         if (!empty($subplugins)) {
148             foreach (array_keys($subplugins) as $subplugintype) {
149                 $instances = core_component::get_plugin_list($subplugintype);
150                 foreach ($instances as $subpluginname => $notusedpluginpath) {
151                     uninstall_plugin($subplugintype, $subpluginname);
152                 }
153             }
154         }
155     }
157     $component = $type . '_' . $name;  // eg. 'qtype_multichoice' or 'workshopgrading_accumulative' or 'mod_forum'
159     if ($type === 'mod') {
160         $pluginname = $name;  // eg. 'forum'
161         if (get_string_manager()->string_exists('modulename', $component)) {
162             $strpluginname = get_string('modulename', $component);
163         } else {
164             $strpluginname = $component;
165         }
167     } else {
168         $pluginname = $component;
169         if (get_string_manager()->string_exists('pluginname', $component)) {
170             $strpluginname = get_string('pluginname', $component);
171         } else {
172             $strpluginname = $component;
173         }
174     }
176     echo $OUTPUT->heading($pluginname);
178     // Delete all tag areas, collections and instances associated with this plugin.
179     core_tag_area::uninstall($component);
181     // Custom plugin uninstall.
182     $plugindirectory = core_component::get_plugin_directory($type, $name);
183     $uninstalllib = $plugindirectory . '/db/uninstall.php';
184     if (file_exists($uninstalllib)) {
185         require_once($uninstalllib);
186         $uninstallfunction = 'xmldb_' . $pluginname . '_uninstall';    // eg. 'xmldb_workshop_uninstall()'
187         if (function_exists($uninstallfunction)) {
188             // Do not verify result, let plugin complain if necessary.
189             $uninstallfunction();
190         }
191     }
193     // Specific plugin type cleanup.
194     $plugininfo = core_plugin_manager::instance()->get_plugin_info($component);
195     if ($plugininfo) {
196         $plugininfo->uninstall_cleanup();
197         core_plugin_manager::reset_caches();
198     }
199     $plugininfo = null;
201     // perform clean-up task common for all the plugin/subplugin types
203     //delete the web service functions and pre-built services
204     require_once($CFG->dirroot.'/lib/externallib.php');
205     external_delete_descriptions($component);
207     // delete calendar events
208     $DB->delete_records('event', array('modulename' => $pluginname));
210     // Delete scheduled tasks.
211     $DB->delete_records('task_scheduled', array('component' => $component));
213     // Delete Inbound Message datakeys.
214     $DB->delete_records_select('messageinbound_datakeys',
215             'handler IN (SELECT id FROM {messageinbound_handlers} WHERE component = ?)', array($component));
217     // Delete Inbound Message handlers.
218     $DB->delete_records('messageinbound_handlers', array('component' => $component));
220     // delete all the logs
221     $DB->delete_records('log', array('module' => $pluginname));
223     // delete log_display information
224     $DB->delete_records('log_display', array('component' => $component));
226     // delete the module configuration records
227     unset_all_config_for_plugin($component);
228     if ($type === 'mod') {
229         unset_all_config_for_plugin($pluginname);
230     }
232     // delete message provider
233     message_provider_uninstall($component);
235     // delete the plugin tables
236     $xmldbfilepath = $plugindirectory . '/db/install.xml';
237     drop_plugin_tables($component, $xmldbfilepath, false);
238     if ($type === 'mod' or $type === 'block') {
239         // non-frankenstyle table prefixes
240         drop_plugin_tables($name, $xmldbfilepath, false);
241     }
243     // delete the capabilities that were defined by this module
244     capabilities_cleanup($component);
246     // Delete all remaining files in the filepool owned by the component.
247     $fs = get_file_storage();
248     $fs->delete_component_files($component);
250     // Finally purge all caches.
251     purge_all_caches();
253     // Invalidate the hash used for upgrade detections.
254     set_config('allversionshash', '');
256     echo $OUTPUT->notification(get_string('success'), 'notifysuccess');
259 /**
260  * Returns the version of installed component
261  *
262  * @param string $component component name
263  * @param string $source either 'disk' or 'installed' - where to get the version information from
264  * @return string|bool version number or false if the component is not found
265  */
266 function get_component_version($component, $source='installed') {
267     global $CFG, $DB;
269     list($type, $name) = core_component::normalize_component($component);
271     // moodle core or a core subsystem
272     if ($type === 'core') {
273         if ($source === 'installed') {
274             if (empty($CFG->version)) {
275                 return false;
276             } else {
277                 return $CFG->version;
278             }
279         } else {
280             if (!is_readable($CFG->dirroot.'/version.php')) {
281                 return false;
282             } else {
283                 $version = null; //initialize variable for IDEs
284                 include($CFG->dirroot.'/version.php');
285                 return $version;
286             }
287         }
288     }
290     // activity module
291     if ($type === 'mod') {
292         if ($source === 'installed') {
293             if ($CFG->version < 2013092001.02) {
294                 return $DB->get_field('modules', 'version', array('name'=>$name));
295             } else {
296                 return get_config('mod_'.$name, 'version');
297             }
299         } else {
300             $mods = core_component::get_plugin_list('mod');
301             if (empty($mods[$name]) or !is_readable($mods[$name].'/version.php')) {
302                 return false;
303             } else {
304                 $plugin = new stdClass();
305                 $plugin->version = null;
306                 $module = $plugin;
307                 include($mods[$name].'/version.php');
308                 return $plugin->version;
309             }
310         }
311     }
313     // block
314     if ($type === 'block') {
315         if ($source === 'installed') {
316             if ($CFG->version < 2013092001.02) {
317                 return $DB->get_field('block', 'version', array('name'=>$name));
318             } else {
319                 return get_config('block_'.$name, 'version');
320             }
321         } else {
322             $blocks = core_component::get_plugin_list('block');
323             if (empty($blocks[$name]) or !is_readable($blocks[$name].'/version.php')) {
324                 return false;
325             } else {
326                 $plugin = new stdclass();
327                 include($blocks[$name].'/version.php');
328                 return $plugin->version;
329             }
330         }
331     }
333     // all other plugin types
334     if ($source === 'installed') {
335         return get_config($type.'_'.$name, 'version');
336     } else {
337         $plugins = core_component::get_plugin_list($type);
338         if (empty($plugins[$name])) {
339             return false;
340         } else {
341             $plugin = new stdclass();
342             include($plugins[$name].'/version.php');
343             return $plugin->version;
344         }
345     }
348 /**
349  * Delete all plugin tables
350  *
351  * @param string $name Name of plugin, used as table prefix
352  * @param string $file Path to install.xml file
353  * @param bool $feedback defaults to true
354  * @return bool Always returns true
355  */
356 function drop_plugin_tables($name, $file, $feedback=true) {
357     global $CFG, $DB;
359     // first try normal delete
360     if (file_exists($file) and $DB->get_manager()->delete_tables_from_xmldb_file($file)) {
361         return true;
362     }
364     // then try to find all tables that start with name and are not in any xml file
365     $used_tables = get_used_table_names();
367     $tables = $DB->get_tables();
369     /// Iterate over, fixing id fields as necessary
370     foreach ($tables as $table) {
371         if (in_array($table, $used_tables)) {
372             continue;
373         }
375         if (strpos($table, $name) !== 0) {
376             continue;
377         }
379         // found orphan table --> delete it
380         if ($DB->get_manager()->table_exists($table)) {
381             $xmldb_table = new xmldb_table($table);
382             $DB->get_manager()->drop_table($xmldb_table);
383         }
384     }
386     return true;
389 /**
390  * Returns names of all known tables == tables that moodle knows about.
391  *
392  * @return array Array of lowercase table names
393  */
394 function get_used_table_names() {
395     $table_names = array();
396     $dbdirs = get_db_directories();
398     foreach ($dbdirs as $dbdir) {
399         $file = $dbdir.'/install.xml';
401         $xmldb_file = new xmldb_file($file);
403         if (!$xmldb_file->fileExists()) {
404             continue;
405         }
407         $loaded    = $xmldb_file->loadXMLStructure();
408         $structure = $xmldb_file->getStructure();
410         if ($loaded and $tables = $structure->getTables()) {
411             foreach($tables as $table) {
412                 $table_names[] = strtolower($table->getName());
413             }
414         }
415     }
417     return $table_names;
420 /**
421  * Returns list of all directories where we expect install.xml files
422  * @return array Array of paths
423  */
424 function get_db_directories() {
425     global $CFG;
427     $dbdirs = array();
429     /// First, the main one (lib/db)
430     $dbdirs[] = $CFG->libdir.'/db';
432     /// Then, all the ones defined by core_component::get_plugin_types()
433     $plugintypes = core_component::get_plugin_types();
434     foreach ($plugintypes as $plugintype => $pluginbasedir) {
435         if ($plugins = core_component::get_plugin_list($plugintype)) {
436             foreach ($plugins as $plugin => $plugindir) {
437                 $dbdirs[] = $plugindir.'/db';
438             }
439         }
440     }
442     return $dbdirs;
445 /**
446  * Try to obtain or release the cron lock.
447  * @param string  $name  name of lock
448  * @param int  $until timestamp when this lock considered stale, null means remove lock unconditionally
449  * @param bool $ignorecurrent ignore current lock state, usually extend previous lock, defaults to false
450  * @return bool true if lock obtained
451  */
452 function set_cron_lock($name, $until, $ignorecurrent=false) {
453     global $DB;
454     if (empty($name)) {
455         debugging("Tried to get a cron lock for a null fieldname");
456         return false;
457     }
459     // remove lock by force == remove from config table
460     if (is_null($until)) {
461         set_config($name, null);
462         return true;
463     }
465     if (!$ignorecurrent) {
466         // read value from db - other processes might have changed it
467         $value = $DB->get_field('config', 'value', array('name'=>$name));
469         if ($value and $value > time()) {
470             //lock active
471             return false;
472         }
473     }
475     set_config($name, $until);
476     return true;
479 /**
480  * Test if and critical warnings are present
481  * @return bool
482  */
483 function admin_critical_warnings_present() {
484     global $SESSION;
486     if (!has_capability('moodle/site:config', context_system::instance())) {
487         return 0;
488     }
490     if (!isset($SESSION->admin_critical_warning)) {
491         $SESSION->admin_critical_warning = 0;
492         if (is_dataroot_insecure(true) === INSECURE_DATAROOT_ERROR) {
493             $SESSION->admin_critical_warning = 1;
494         }
495     }
497     return $SESSION->admin_critical_warning;
500 /**
501  * Detects if float supports at least 10 decimal digits
502  *
503  * Detects if float supports at least 10 decimal digits
504  * and also if float-->string conversion works as expected.
505  *
506  * @return bool true if problem found
507  */
508 function is_float_problem() {
509     $num1 = 2009010200.01;
510     $num2 = 2009010200.02;
512     return ((string)$num1 === (string)$num2 or $num1 === $num2 or $num2 <= (string)$num1);
515 /**
516  * Try to verify that dataroot is not accessible from web.
517  *
518  * Try to verify that dataroot is not accessible from web.
519  * It is not 100% correct but might help to reduce number of vulnerable sites.
520  * Protection from httpd.conf and .htaccess is not detected properly.
521  *
522  * @uses INSECURE_DATAROOT_WARNING
523  * @uses INSECURE_DATAROOT_ERROR
524  * @param bool $fetchtest try to test public access by fetching file, default false
525  * @return mixed empty means secure, INSECURE_DATAROOT_ERROR found a critical problem, INSECURE_DATAROOT_WARNING might be problematic
526  */
527 function is_dataroot_insecure($fetchtest=false) {
528     global $CFG;
530     $siteroot = str_replace('\\', '/', strrev($CFG->dirroot.'/')); // win32 backslash workaround
532     $rp = preg_replace('|https?://[^/]+|i', '', $CFG->wwwroot, 1);
533     $rp = strrev(trim($rp, '/'));
534     $rp = explode('/', $rp);
535     foreach($rp as $r) {
536         if (strpos($siteroot, '/'.$r.'/') === 0) {
537             $siteroot = substr($siteroot, strlen($r)+1); // moodle web in subdirectory
538         } else {
539             break; // probably alias root
540         }
541     }
543     $siteroot = strrev($siteroot);
544     $dataroot = str_replace('\\', '/', $CFG->dataroot.'/');
546     if (strpos($dataroot, $siteroot) !== 0) {
547         return false;
548     }
550     if (!$fetchtest) {
551         return INSECURE_DATAROOT_WARNING;
552     }
554     // now try all methods to fetch a test file using http protocol
556     $httpdocroot = str_replace('\\', '/', strrev($CFG->dirroot.'/'));
557     preg_match('|(https?://[^/]+)|i', $CFG->wwwroot, $matches);
558     $httpdocroot = $matches[1];
559     $datarooturl = $httpdocroot.'/'. substr($dataroot, strlen($siteroot));
560     make_upload_directory('diag');
561     $testfile = $CFG->dataroot.'/diag/public.txt';
562     if (!file_exists($testfile)) {
563         file_put_contents($testfile, 'test file, do not delete');
564         @chmod($testfile, $CFG->filepermissions);
565     }
566     $teststr = trim(file_get_contents($testfile));
567     if (empty($teststr)) {
568     // hmm, strange
569         return INSECURE_DATAROOT_WARNING;
570     }
572     $testurl = $datarooturl.'/diag/public.txt';
573     if (extension_loaded('curl') and
574         !(stripos(ini_get('disable_functions'), 'curl_init') !== FALSE) and
575         !(stripos(ini_get('disable_functions'), 'curl_setop') !== FALSE) and
576         ($ch = @curl_init($testurl)) !== false) {
577         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
578         curl_setopt($ch, CURLOPT_HEADER, false);
579         $data = curl_exec($ch);
580         if (!curl_errno($ch)) {
581             $data = trim($data);
582             if ($data === $teststr) {
583                 curl_close($ch);
584                 return INSECURE_DATAROOT_ERROR;
585             }
586         }
587         curl_close($ch);
588     }
590     if ($data = @file_get_contents($testurl)) {
591         $data = trim($data);
592         if ($data === $teststr) {
593             return INSECURE_DATAROOT_ERROR;
594         }
595     }
597     preg_match('|https?://([^/]+)|i', $testurl, $matches);
598     $sitename = $matches[1];
599     $error = 0;
600     if ($fp = @fsockopen($sitename, 80, $error)) {
601         preg_match('|https?://[^/]+(.*)|i', $testurl, $matches);
602         $localurl = $matches[1];
603         $out = "GET $localurl HTTP/1.1\r\n";
604         $out .= "Host: $sitename\r\n";
605         $out .= "Connection: Close\r\n\r\n";
606         fwrite($fp, $out);
607         $data = '';
608         $incoming = false;
609         while (!feof($fp)) {
610             if ($incoming) {
611                 $data .= fgets($fp, 1024);
612             } else if (@fgets($fp, 1024) === "\r\n") {
613                     $incoming = true;
614                 }
615         }
616         fclose($fp);
617         $data = trim($data);
618         if ($data === $teststr) {
619             return INSECURE_DATAROOT_ERROR;
620         }
621     }
623     return INSECURE_DATAROOT_WARNING;
626 /**
627  * Enables CLI maintenance mode by creating new dataroot/climaintenance.html file.
628  */
629 function enable_cli_maintenance_mode() {
630     global $CFG;
632     if (file_exists("$CFG->dataroot/climaintenance.html")) {
633         unlink("$CFG->dataroot/climaintenance.html");
634     }
636     if (isset($CFG->maintenance_message) and !html_is_blank($CFG->maintenance_message)) {
637         $data = $CFG->maintenance_message;
638         $data = bootstrap_renderer::early_error_content($data, null, null, null);
639         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
641     } else if (file_exists("$CFG->dataroot/climaintenance.template.html")) {
642         $data = file_get_contents("$CFG->dataroot/climaintenance.template.html");
644     } else {
645         $data = get_string('sitemaintenance', 'admin');
646         $data = bootstrap_renderer::early_error_content($data, null, null, null);
647         $data = bootstrap_renderer::plain_page(get_string('sitemaintenance', 'admin'), $data);
648     }
650     file_put_contents("$CFG->dataroot/climaintenance.html", $data);
651     chmod("$CFG->dataroot/climaintenance.html", $CFG->filepermissions);
654 /// CLASS DEFINITIONS /////////////////////////////////////////////////////////
657 /**
658  * Interface for anything appearing in the admin tree
659  *
660  * The interface that is implemented by anything that appears in the admin tree
661  * block. It forces inheriting classes to define a method for checking user permissions
662  * and methods for finding something in the admin tree.
663  *
664  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
665  */
666 interface part_of_admin_tree {
668 /**
669  * Finds a named part_of_admin_tree.
670  *
671  * Used to find a part_of_admin_tree. If a class only inherits part_of_admin_tree
672  * and not parentable_part_of_admin_tree, then this function should only check if
673  * $this->name matches $name. If it does, it should return a reference to $this,
674  * otherwise, it should return a reference to NULL.
675  *
676  * If a class inherits parentable_part_of_admin_tree, this method should be called
677  * recursively on all child objects (assuming, of course, the parent object's name
678  * doesn't match the search criterion).
679  *
680  * @param string $name The internal name of the part_of_admin_tree we're searching for.
681  * @return mixed An object reference or a NULL reference.
682  */
683     public function locate($name);
685     /**
686      * Removes named part_of_admin_tree.
687      *
688      * @param string $name The internal name of the part_of_admin_tree we want to remove.
689      * @return bool success.
690      */
691     public function prune($name);
693     /**
694      * Search using query
695      * @param string $query
696      * @return mixed array-object structure of found settings and pages
697      */
698     public function search($query);
700     /**
701      * Verifies current user's access to this part_of_admin_tree.
702      *
703      * Used to check if the current user has access to this part of the admin tree or
704      * not. If a class only inherits part_of_admin_tree and not parentable_part_of_admin_tree,
705      * then this method is usually just a call to has_capability() in the site context.
706      *
707      * If a class inherits parentable_part_of_admin_tree, this method should return the
708      * logical OR of the return of check_access() on all child objects.
709      *
710      * @return bool True if the user has access, false if she doesn't.
711      */
712     public function check_access();
714     /**
715      * Mostly useful for removing of some parts of the tree in admin tree block.
716      *
717      * @return True is hidden from normal list view
718      */
719     public function is_hidden();
721     /**
722      * Show we display Save button at the page bottom?
723      * @return bool
724      */
725     public function show_save();
729 /**
730  * Interface implemented by any part_of_admin_tree that has children.
731  *
732  * The interface implemented by any part_of_admin_tree that can be a parent
733  * to other part_of_admin_tree's. (For now, this only includes admin_category.) Apart
734  * from ensuring part_of_admin_tree compliancy, it also ensures inheriting methods
735  * include an add method for adding other part_of_admin_tree objects as children.
736  *
737  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
738  */
739 interface parentable_part_of_admin_tree extends part_of_admin_tree {
741 /**
742  * Adds a part_of_admin_tree object to the admin tree.
743  *
744  * Used to add a part_of_admin_tree object to this object or a child of this
745  * object. $something should only be added if $destinationname matches
746  * $this->name. If it doesn't, add should be called on child objects that are
747  * also parentable_part_of_admin_tree's.
748  *
749  * $something should be appended as the last child in the $destinationname. If the
750  * $beforesibling is specified, $something should be prepended to it. If the given
751  * sibling is not found, $something should be appended to the end of $destinationname
752  * and a developer debugging message should be displayed.
753  *
754  * @param string $destinationname The internal name of the new parent for $something.
755  * @param part_of_admin_tree $something The object to be added.
756  * @return bool True on success, false on failure.
757  */
758     public function add($destinationname, $something, $beforesibling = null);
763 /**
764  * The object used to represent folders (a.k.a. categories) in the admin tree block.
765  *
766  * Each admin_category object contains a number of part_of_admin_tree objects.
767  *
768  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
769  */
770 class admin_category implements parentable_part_of_admin_tree {
772     /** @var part_of_admin_tree[] An array of part_of_admin_tree objects that are this object's children */
773     protected $children;
774     /** @var string An internal name for this category. Must be unique amongst ALL part_of_admin_tree objects */
775     public $name;
776     /** @var string The displayed name for this category. Usually obtained through get_string() */
777     public $visiblename;
778     /** @var bool Should this category be hidden in admin tree block? */
779     public $hidden;
780     /** @var mixed Either a string or an array or strings */
781     public $path;
782     /** @var mixed Either a string or an array or strings */
783     public $visiblepath;
785     /** @var array fast lookup category cache, all categories of one tree point to one cache */
786     protected $category_cache;
788     /** @var bool If set to true children will be sorted when calling {@link admin_category::get_children()} */
789     protected $sort = false;
790     /** @var bool If set to true children will be sorted in ascending order. */
791     protected $sortasc = true;
792     /** @var bool If set to true sub categories and pages will be split and then sorted.. */
793     protected $sortsplit = true;
794     /** @var bool $sorted True if the children have been sorted and don't need resorting */
795     protected $sorted = false;
797     /**
798      * Constructor for an empty admin category
799      *
800      * @param string $name The internal name for this category. Must be unique amongst ALL part_of_admin_tree objects
801      * @param string $visiblename The displayed named for this category. Usually obtained through get_string()
802      * @param bool $hidden hide category in admin tree block, defaults to false
803      */
804     public function __construct($name, $visiblename, $hidden=false) {
805         $this->children    = array();
806         $this->name        = $name;
807         $this->visiblename = $visiblename;
808         $this->hidden      = $hidden;
809     }
811     /**
812      * Returns a reference to the part_of_admin_tree object with internal name $name.
813      *
814      * @param string $name The internal name of the object we want.
815      * @param bool $findpath initialize path and visiblepath arrays
816      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
817      *                  defaults to false
818      */
819     public function locate($name, $findpath=false) {
820         if (!isset($this->category_cache[$this->name])) {
821             // somebody much have purged the cache
822             $this->category_cache[$this->name] = $this;
823         }
825         if ($this->name == $name) {
826             if ($findpath) {
827                 $this->visiblepath[] = $this->visiblename;
828                 $this->path[]        = $this->name;
829             }
830             return $this;
831         }
833         // quick category lookup
834         if (!$findpath and isset($this->category_cache[$name])) {
835             return $this->category_cache[$name];
836         }
838         $return = NULL;
839         foreach($this->children as $childid=>$unused) {
840             if ($return = $this->children[$childid]->locate($name, $findpath)) {
841                 break;
842             }
843         }
845         if (!is_null($return) and $findpath) {
846             $return->visiblepath[] = $this->visiblename;
847             $return->path[]        = $this->name;
848         }
850         return $return;
851     }
853     /**
854      * Search using query
855      *
856      * @param string query
857      * @return mixed array-object structure of found settings and pages
858      */
859     public function search($query) {
860         $result = array();
861         foreach ($this->get_children() as $child) {
862             $subsearch = $child->search($query);
863             if (!is_array($subsearch)) {
864                 debugging('Incorrect search result from '.$child->name);
865                 continue;
866             }
867             $result = array_merge($result, $subsearch);
868         }
869         return $result;
870     }
872     /**
873      * Removes part_of_admin_tree object with internal name $name.
874      *
875      * @param string $name The internal name of the object we want to remove.
876      * @return bool success
877      */
878     public function prune($name) {
880         if ($this->name == $name) {
881             return false;  //can not remove itself
882         }
884         foreach($this->children as $precedence => $child) {
885             if ($child->name == $name) {
886                 // clear cache and delete self
887                 while($this->category_cache) {
888                     // delete the cache, but keep the original array address
889                     array_pop($this->category_cache);
890                 }
891                 unset($this->children[$precedence]);
892                 return true;
893             } else if ($this->children[$precedence]->prune($name)) {
894                 return true;
895             }
896         }
897         return false;
898     }
900     /**
901      * Adds a part_of_admin_tree to a child or grandchild (or great-grandchild, and so forth) of this object.
902      *
903      * By default the new part of the tree is appended as the last child of the parent. You
904      * can specify a sibling node that the new part should be prepended to. If the given
905      * sibling is not found, the part is appended to the end (as it would be by default) and
906      * a developer debugging message is displayed.
907      *
908      * @throws coding_exception if the $beforesibling is empty string or is not string at all.
909      * @param string $destinationame The internal name of the immediate parent that we want for $something.
910      * @param mixed $something A part_of_admin_tree or setting instance to be added.
911      * @param string $beforesibling The name of the parent's child the $something should be prepended to.
912      * @return bool True if successfully added, false if $something can not be added.
913      */
914     public function add($parentname, $something, $beforesibling = null) {
915         global $CFG;
917         $parent = $this->locate($parentname);
918         if (is_null($parent)) {
919             debugging('parent does not exist!');
920             return false;
921         }
923         if ($something instanceof part_of_admin_tree) {
924             if (!($parent instanceof parentable_part_of_admin_tree)) {
925                 debugging('error - parts of tree can be inserted only into parentable parts');
926                 return false;
927             }
928             if ($CFG->debugdeveloper && !is_null($this->locate($something->name))) {
929                 // The name of the node is already used, simply warn the developer that this should not happen.
930                 // It is intentional to check for the debug level before performing the check.
931                 debugging('Duplicate admin page name: ' . $something->name, DEBUG_DEVELOPER);
932             }
933             if (is_null($beforesibling)) {
934                 // Append $something as the parent's last child.
935                 $parent->children[] = $something;
936             } else {
937                 if (!is_string($beforesibling) or trim($beforesibling) === '') {
938                     throw new coding_exception('Unexpected value of the beforesibling parameter');
939                 }
940                 // Try to find the position of the sibling.
941                 $siblingposition = null;
942                 foreach ($parent->children as $childposition => $child) {
943                     if ($child->name === $beforesibling) {
944                         $siblingposition = $childposition;
945                         break;
946                     }
947                 }
948                 if (is_null($siblingposition)) {
949                     debugging('Sibling '.$beforesibling.' not found', DEBUG_DEVELOPER);
950                     $parent->children[] = $something;
951                 } else {
952                     $parent->children = array_merge(
953                         array_slice($parent->children, 0, $siblingposition),
954                         array($something),
955                         array_slice($parent->children, $siblingposition)
956                     );
957                 }
958             }
959             if ($something instanceof admin_category) {
960                 if (isset($this->category_cache[$something->name])) {
961                     debugging('Duplicate admin category name: '.$something->name);
962                 } else {
963                     $this->category_cache[$something->name] = $something;
964                     $something->category_cache =& $this->category_cache;
965                     foreach ($something->children as $child) {
966                         // just in case somebody already added subcategories
967                         if ($child instanceof admin_category) {
968                             if (isset($this->category_cache[$child->name])) {
969                                 debugging('Duplicate admin category name: '.$child->name);
970                             } else {
971                                 $this->category_cache[$child->name] = $child;
972                                 $child->category_cache =& $this->category_cache;
973                             }
974                         }
975                     }
976                 }
977             }
978             return true;
980         } else {
981             debugging('error - can not add this element');
982             return false;
983         }
985     }
987     /**
988      * Checks if the user has access to anything in this category.
989      *
990      * @return bool True if the user has access to at least one child in this category, false otherwise.
991      */
992     public function check_access() {
993         foreach ($this->children as $child) {
994             if ($child->check_access()) {
995                 return true;
996             }
997         }
998         return false;
999     }
1001     /**
1002      * Is this category hidden in admin tree block?
1003      *
1004      * @return bool True if hidden
1005      */
1006     public function is_hidden() {
1007         return $this->hidden;
1008     }
1010     /**
1011      * Show we display Save button at the page bottom?
1012      * @return bool
1013      */
1014     public function show_save() {
1015         foreach ($this->children as $child) {
1016             if ($child->show_save()) {
1017                 return true;
1018             }
1019         }
1020         return false;
1021     }
1023     /**
1024      * Sets sorting on this category.
1025      *
1026      * Please note this function doesn't actually do the sorting.
1027      * It can be called anytime.
1028      * Sorting occurs when the user calls get_children.
1029      * Code using the children array directly won't see the sorted results.
1030      *
1031      * @param bool $sort If set to true children will be sorted, if false they won't be.
1032      * @param bool $asc If true sorting will be ascending, otherwise descending.
1033      * @param bool $split If true we sort pages and sub categories separately.
1034      */
1035     public function set_sorting($sort, $asc = true, $split = true) {
1036         $this->sort = (bool)$sort;
1037         $this->sortasc = (bool)$asc;
1038         $this->sortsplit = (bool)$split;
1039     }
1041     /**
1042      * Returns the children associated with this category.
1043      *
1044      * @return part_of_admin_tree[]
1045      */
1046     public function get_children() {
1047         // If we should sort and it hasn't already been sorted.
1048         if ($this->sort && !$this->sorted) {
1049             if ($this->sortsplit) {
1050                 $categories = array();
1051                 $pages = array();
1052                 foreach ($this->children as $child) {
1053                     if ($child instanceof admin_category) {
1054                         $categories[] = $child;
1055                     } else {
1056                         $pages[] = $child;
1057                     }
1058                 }
1059                 core_collator::asort_objects_by_property($categories, 'visiblename');
1060                 core_collator::asort_objects_by_property($pages, 'visiblename');
1061                 if (!$this->sortasc) {
1062                     $categories = array_reverse($categories);
1063                     $pages = array_reverse($pages);
1064                 }
1065                 $this->children = array_merge($pages, $categories);
1066             } else {
1067                 core_collator::asort_objects_by_property($this->children, 'visiblename');
1068                 if (!$this->sortasc) {
1069                     $this->children = array_reverse($this->children);
1070                 }
1071             }
1072             $this->sorted = true;
1073         }
1074         return $this->children;
1075     }
1077     /**
1078      * Magically gets a property from this object.
1079      *
1080      * @param $property
1081      * @return part_of_admin_tree[]
1082      * @throws coding_exception
1083      */
1084     public function __get($property) {
1085         if ($property === 'children') {
1086             return $this->get_children();
1087         }
1088         throw new coding_exception('Invalid property requested.');
1089     }
1091     /**
1092      * Magically sets a property against this object.
1093      *
1094      * @param string $property
1095      * @param mixed $value
1096      * @throws coding_exception
1097      */
1098     public function __set($property, $value) {
1099         if ($property === 'children') {
1100             $this->sorted = false;
1101             $this->children = $value;
1102         } else {
1103             throw new coding_exception('Invalid property requested.');
1104         }
1105     }
1107     /**
1108      * Checks if an inaccessible property is set.
1109      *
1110      * @param string $property
1111      * @return bool
1112      * @throws coding_exception
1113      */
1114     public function __isset($property) {
1115         if ($property === 'children') {
1116             return isset($this->children);
1117         }
1118         throw new coding_exception('Invalid property requested.');
1119     }
1123 /**
1124  * Root of admin settings tree, does not have any parent.
1125  *
1126  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1127  */
1128 class admin_root extends admin_category {
1129 /** @var array List of errors */
1130     public $errors;
1131     /** @var string search query */
1132     public $search;
1133     /** @var bool full tree flag - true means all settings required, false only pages required */
1134     public $fulltree;
1135     /** @var bool flag indicating loaded tree */
1136     public $loaded;
1137     /** @var mixed site custom defaults overriding defaults in settings files*/
1138     public $custom_defaults;
1140     /**
1141      * @param bool $fulltree true means all settings required,
1142      *                            false only pages required
1143      */
1144     public function __construct($fulltree) {
1145         global $CFG;
1147         parent::__construct('root', get_string('administration'), false);
1148         $this->errors   = array();
1149         $this->search   = '';
1150         $this->fulltree = $fulltree;
1151         $this->loaded   = false;
1153         $this->category_cache = array();
1155         // load custom defaults if found
1156         $this->custom_defaults = null;
1157         $defaultsfile = "$CFG->dirroot/local/defaults.php";
1158         if (is_readable($defaultsfile)) {
1159             $defaults = array();
1160             include($defaultsfile);
1161             if (is_array($defaults) and count($defaults)) {
1162                 $this->custom_defaults = $defaults;
1163             }
1164         }
1165     }
1167     /**
1168      * Empties children array, and sets loaded to false
1169      *
1170      * @param bool $requirefulltree
1171      */
1172     public function purge_children($requirefulltree) {
1173         $this->children = array();
1174         $this->fulltree = ($requirefulltree || $this->fulltree);
1175         $this->loaded   = false;
1176         //break circular dependencies - this helps PHP 5.2
1177         while($this->category_cache) {
1178             array_pop($this->category_cache);
1179         }
1180         $this->category_cache = array();
1181     }
1185 /**
1186  * Links external PHP pages into the admin tree.
1187  *
1188  * See detailed usage example at the top of this document (adminlib.php)
1189  *
1190  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1191  */
1192 class admin_externalpage implements part_of_admin_tree {
1194     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1195     public $name;
1197     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1198     public $visiblename;
1200     /** @var string The external URL that we should link to when someone requests this external page. */
1201     public $url;
1203     /** @var string The role capability/permission a user must have to access this external page. */
1204     public $req_capability;
1206     /** @var object The context in which capability/permission should be checked, default is site context. */
1207     public $context;
1209     /** @var bool hidden in admin tree block. */
1210     public $hidden;
1212     /** @var mixed either string or array of string */
1213     public $path;
1215     /** @var array list of visible names of page parents */
1216     public $visiblepath;
1218     /**
1219      * Constructor for adding an external page into the admin tree.
1220      *
1221      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1222      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1223      * @param string $url The external URL that we should link to when someone requests this external page.
1224      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1225      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1226      * @param stdClass $context The context the page relates to. Not sure what happens
1227      *      if you specify something other than system or front page. Defaults to system.
1228      */
1229     public function __construct($name, $visiblename, $url, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1230         $this->name        = $name;
1231         $this->visiblename = $visiblename;
1232         $this->url         = $url;
1233         if (is_array($req_capability)) {
1234             $this->req_capability = $req_capability;
1235         } else {
1236             $this->req_capability = array($req_capability);
1237         }
1238         $this->hidden = $hidden;
1239         $this->context = $context;
1240     }
1242     /**
1243      * Returns a reference to the part_of_admin_tree object with internal name $name.
1244      *
1245      * @param string $name The internal name of the object we want.
1246      * @param bool $findpath defaults to false
1247      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
1248      */
1249     public function locate($name, $findpath=false) {
1250         if ($this->name == $name) {
1251             if ($findpath) {
1252                 $this->visiblepath = array($this->visiblename);
1253                 $this->path        = array($this->name);
1254             }
1255             return $this;
1256         } else {
1257             $return = NULL;
1258             return $return;
1259         }
1260     }
1262     /**
1263      * This function always returns false, required function by interface
1264      *
1265      * @param string $name
1266      * @return false
1267      */
1268     public function prune($name) {
1269         return false;
1270     }
1272     /**
1273      * Search using query
1274      *
1275      * @param string $query
1276      * @return mixed array-object structure of found settings and pages
1277      */
1278     public function search($query) {
1279         $found = false;
1280         if (strpos(strtolower($this->name), $query) !== false) {
1281             $found = true;
1282         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1283                 $found = true;
1284             }
1285         if ($found) {
1286             $result = new stdClass();
1287             $result->page     = $this;
1288             $result->settings = array();
1289             return array($this->name => $result);
1290         } else {
1291             return array();
1292         }
1293     }
1295     /**
1296      * Determines if the current user has access to this external page based on $this->req_capability.
1297      *
1298      * @return bool True if user has access, false otherwise.
1299      */
1300     public function check_access() {
1301         global $CFG;
1302         $context = empty($this->context) ? context_system::instance() : $this->context;
1303         foreach($this->req_capability as $cap) {
1304             if (has_capability($cap, $context)) {
1305                 return true;
1306             }
1307         }
1308         return false;
1309     }
1311     /**
1312      * Is this external page hidden in admin tree block?
1313      *
1314      * @return bool True if hidden
1315      */
1316     public function is_hidden() {
1317         return $this->hidden;
1318     }
1320     /**
1321      * Show we display Save button at the page bottom?
1322      * @return bool
1323      */
1324     public function show_save() {
1325         return false;
1326     }
1329 /**
1330  * Used to store details of the dependency between two settings elements.
1331  *
1332  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1333  * @copyright 2017 Davo Smith, Synergy Learning
1334  */
1335 class admin_settingdependency {
1336     /** @var string the name of the setting to be shown/hidden */
1337     public $settingname;
1338     /** @var string the setting this is dependent on */
1339     public $dependenton;
1340     /** @var string the condition to show/hide the element */
1341     public $condition;
1342     /** @var string the value to compare against */
1343     public $value;
1345     /** @var string[] list of valid conditions */
1346     private static $validconditions = ['checked', 'notchecked', 'noitemselected', 'eq', 'neq', 'in'];
1348     /**
1349      * admin_settingdependency constructor.
1350      * @param string $settingname
1351      * @param string $dependenton
1352      * @param string $condition
1353      * @param string $value
1354      * @throws \coding_exception
1355      */
1356     public function __construct($settingname, $dependenton, $condition, $value) {
1357         $this->settingname = $this->parse_name($settingname);
1358         $this->dependenton = $this->parse_name($dependenton);
1359         $this->condition = $condition;
1360         $this->value = $value;
1362         if (!in_array($this->condition, self::$validconditions)) {
1363             throw new coding_exception("Invalid condition '$condition'");
1364         }
1365     }
1367     /**
1368      * Convert the setting name into the form field name.
1369      * @param string $name
1370      * @return string
1371      */
1372     private function parse_name($name) {
1373         $bits = explode('/', $name);
1374         $name = array_pop($bits);
1375         $plugin = '';
1376         if ($bits) {
1377             $plugin = array_pop($bits);
1378             if ($plugin === 'moodle') {
1379                 $plugin = '';
1380             }
1381         }
1382         return 's_'.$plugin.'_'.$name;
1383     }
1385     /**
1386      * Gather together all the dependencies in a format suitable for initialising javascript
1387      * @param admin_settingdependency[] $dependencies
1388      * @return array
1389      */
1390     public static function prepare_for_javascript($dependencies) {
1391         $result = [];
1392         foreach ($dependencies as $d) {
1393             if (!isset($result[$d->dependenton])) {
1394                 $result[$d->dependenton] = [];
1395             }
1396             if (!isset($result[$d->dependenton][$d->condition])) {
1397                 $result[$d->dependenton][$d->condition] = [];
1398             }
1399             if (!isset($result[$d->dependenton][$d->condition][$d->value])) {
1400                 $result[$d->dependenton][$d->condition][$d->value] = [];
1401             }
1402             $result[$d->dependenton][$d->condition][$d->value][] = $d->settingname;
1403         }
1404         return $result;
1405     }
1408 /**
1409  * Used to group a number of admin_setting objects into a page and add them to the admin tree.
1410  *
1411  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1412  */
1413 class admin_settingpage implements part_of_admin_tree {
1415     /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1416     public $name;
1418     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1419     public $visiblename;
1421     /** @var mixed An array of admin_setting objects that are part of this setting page. */
1422     public $settings;
1424     /** @var admin_settingdependency[] list of settings to hide when certain conditions are met */
1425     protected $dependencies = [];
1427     /** @var string The role capability/permission a user must have to access this external page. */
1428     public $req_capability;
1430     /** @var object The context in which capability/permission should be checked, default is site context. */
1431     public $context;
1433     /** @var bool hidden in admin tree block. */
1434     public $hidden;
1436     /** @var mixed string of paths or array of strings of paths */
1437     public $path;
1439     /** @var array list of visible names of page parents */
1440     public $visiblepath;
1442     /**
1443      * see admin_settingpage for details of this function
1444      *
1445      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1446      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1447      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1448      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1449      * @param stdClass $context The context the page relates to. Not sure what happens
1450      *      if you specify something other than system or front page. Defaults to system.
1451      */
1452     public function __construct($name, $visiblename, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1453         $this->settings    = new stdClass();
1454         $this->name        = $name;
1455         $this->visiblename = $visiblename;
1456         if (is_array($req_capability)) {
1457             $this->req_capability = $req_capability;
1458         } else {
1459             $this->req_capability = array($req_capability);
1460         }
1461         $this->hidden      = $hidden;
1462         $this->context     = $context;
1463     }
1465     /**
1466      * see admin_category
1467      *
1468      * @param string $name
1469      * @param bool $findpath
1470      * @return mixed Object (this) if name ==  this->name, else returns null
1471      */
1472     public function locate($name, $findpath=false) {
1473         if ($this->name == $name) {
1474             if ($findpath) {
1475                 $this->visiblepath = array($this->visiblename);
1476                 $this->path        = array($this->name);
1477             }
1478             return $this;
1479         } else {
1480             $return = NULL;
1481             return $return;
1482         }
1483     }
1485     /**
1486      * Search string in settings page.
1487      *
1488      * @param string $query
1489      * @return array
1490      */
1491     public function search($query) {
1492         $found = array();
1494         foreach ($this->settings as $setting) {
1495             if ($setting->is_related($query)) {
1496                 $found[] = $setting;
1497             }
1498         }
1500         if ($found) {
1501             $result = new stdClass();
1502             $result->page     = $this;
1503             $result->settings = $found;
1504             return array($this->name => $result);
1505         }
1507         $found = false;
1508         if (strpos(strtolower($this->name), $query) !== false) {
1509             $found = true;
1510         } else if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
1511                 $found = true;
1512             }
1513         if ($found) {
1514             $result = new stdClass();
1515             $result->page     = $this;
1516             $result->settings = array();
1517             return array($this->name => $result);
1518         } else {
1519             return array();
1520         }
1521     }
1523     /**
1524      * This function always returns false, required by interface
1525      *
1526      * @param string $name
1527      * @return bool Always false
1528      */
1529     public function prune($name) {
1530         return false;
1531     }
1533     /**
1534      * adds an admin_setting to this admin_settingpage
1535      *
1536      * 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
1537      * n.b. each admin_setting in an admin_settingpage must have a unique internal name
1538      *
1539      * @param object $setting is the admin_setting object you want to add
1540      * @return bool true if successful, false if not
1541      */
1542     public function add($setting) {
1543         if (!($setting instanceof admin_setting)) {
1544             debugging('error - not a setting instance');
1545             return false;
1546         }
1548         $name = $setting->name;
1549         if ($setting->plugin) {
1550             $name = $setting->plugin . $name;
1551         }
1552         $this->settings->{$name} = $setting;
1553         return true;
1554     }
1556     /**
1557      * Hide the named setting if the specified condition is matched.
1558      *
1559      * @param string $settingname
1560      * @param string $dependenton
1561      * @param string $condition
1562      * @param string $value
1563      */
1564     public function hide_if($settingname, $dependenton, $condition = 'notchecked', $value = '1') {
1565         $this->dependencies[] = new admin_settingdependency($settingname, $dependenton, $condition, $value);
1567         // Reformat the dependency name to the plugin | name format used in the display.
1568         $dependenton = str_replace('/', ' | ', $dependenton);
1570         // Let the setting know, so it can be displayed underneath.
1571         $findname = str_replace('/', '', $settingname);
1572         foreach ($this->settings as $name => $setting) {
1573             if ($name === $findname) {
1574                 $setting->add_dependent_on($dependenton);
1575             }
1576         }
1577     }
1579     /**
1580      * see admin_externalpage
1581      *
1582      * @return bool Returns true for yes false for no
1583      */
1584     public function check_access() {
1585         global $CFG;
1586         $context = empty($this->context) ? context_system::instance() : $this->context;
1587         foreach($this->req_capability as $cap) {
1588             if (has_capability($cap, $context)) {
1589                 return true;
1590             }
1591         }
1592         return false;
1593     }
1595     /**
1596      * outputs this page as html in a table (suitable for inclusion in an admin pagetype)
1597      * @return string Returns an XHTML string
1598      */
1599     public function output_html() {
1600         $adminroot = admin_get_root();
1601         $return = '<fieldset>'."\n".'<div class="clearer"><!-- --></div>'."\n";
1602         foreach($this->settings as $setting) {
1603             $fullname = $setting->get_full_name();
1604             if (array_key_exists($fullname, $adminroot->errors)) {
1605                 $data = $adminroot->errors[$fullname]->data;
1606             } else {
1607                 $data = $setting->get_setting();
1608                 // do not use defaults if settings not available - upgrade settings handles the defaults!
1609             }
1610             $return .= $setting->output_html($data);
1611         }
1612         $return .= '</fieldset>';
1613         return $return;
1614     }
1616     /**
1617      * Is this settings page hidden in admin tree block?
1618      *
1619      * @return bool True if hidden
1620      */
1621     public function is_hidden() {
1622         return $this->hidden;
1623     }
1625     /**
1626      * Show we display Save button at the page bottom?
1627      * @return bool
1628      */
1629     public function show_save() {
1630         foreach($this->settings as $setting) {
1631             if (empty($setting->nosave)) {
1632                 return true;
1633             }
1634         }
1635         return false;
1636     }
1638     /**
1639      * Should any of the settings on this page be shown / hidden based on conditions?
1640      * @return bool
1641      */
1642     public function has_dependencies() {
1643         return (bool)$this->dependencies;
1644     }
1646     /**
1647      * Format the setting show/hide conditions ready to initialise the page javascript
1648      * @return array
1649      */
1650     public function get_dependencies_for_javascript() {
1651         if (!$this->has_dependencies()) {
1652             return [];
1653         }
1654         return admin_settingdependency::prepare_for_javascript($this->dependencies);
1655     }
1659 /**
1660  * Admin settings class. Only exists on setting pages.
1661  * Read & write happens at this level; no authentication.
1662  *
1663  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1664  */
1665 abstract class admin_setting {
1666     /** @var string unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins. */
1667     public $name;
1668     /** @var string localised name */
1669     public $visiblename;
1670     /** @var string localised long description in Markdown format */
1671     public $description;
1672     /** @var mixed Can be string or array of string */
1673     public $defaultsetting;
1674     /** @var string */
1675     public $updatedcallback;
1676     /** @var mixed can be String or Null.  Null means main config table */
1677     public $plugin; // null means main config table
1678     /** @var bool true indicates this setting does not actually save anything, just information */
1679     public $nosave = false;
1680     /** @var bool if set, indicates that a change to this setting requires rebuild course cache */
1681     public $affectsmodinfo = false;
1682     /** @var array of admin_setting_flag - These are extra checkboxes attached to a setting. */
1683     private $flags = array();
1684     /** @var bool Whether this field must be forced LTR. */
1685     private $forceltr = null;
1686     /** @var array list of other settings that may cause this setting to be hidden */
1687     private $dependenton = [];
1689     /**
1690      * Constructor
1691      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
1692      *                     or 'myplugin/mysetting' for ones in config_plugins.
1693      * @param string $visiblename localised name
1694      * @param string $description localised long description
1695      * @param mixed $defaultsetting string or array depending on implementation
1696      */
1697     public function __construct($name, $visiblename, $description, $defaultsetting) {
1698         $this->parse_setting_name($name);
1699         $this->visiblename    = $visiblename;
1700         $this->description    = $description;
1701         $this->defaultsetting = $defaultsetting;
1702     }
1704     /**
1705      * Generic function to add a flag to this admin setting.
1706      *
1707      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1708      * @param bool $default - The default for the flag
1709      * @param string $shortname - The shortname for this flag. Used as a suffix for the setting name.
1710      * @param string $displayname - The display name for this flag. Used as a label next to the checkbox.
1711      */
1712     protected function set_flag_options($enabled, $default, $shortname, $displayname) {
1713         if (empty($this->flags[$shortname])) {
1714             $this->flags[$shortname] = new admin_setting_flag($enabled, $default, $shortname, $displayname);
1715         } else {
1716             $this->flags[$shortname]->set_options($enabled, $default);
1717         }
1718     }
1720     /**
1721      * Set the enabled options flag on this admin setting.
1722      *
1723      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1724      * @param bool $default - The default for the flag
1725      */
1726     public function set_enabled_flag_options($enabled, $default) {
1727         $this->set_flag_options($enabled, $default, 'enabled', new lang_string('enabled', 'core_admin'));
1728     }
1730     /**
1731      * Set the advanced options flag on this admin setting.
1732      *
1733      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1734      * @param bool $default - The default for the flag
1735      */
1736     public function set_advanced_flag_options($enabled, $default) {
1737         $this->set_flag_options($enabled, $default, 'adv', new lang_string('advanced'));
1738     }
1741     /**
1742      * Set the locked options flag on this admin setting.
1743      *
1744      * @param bool $enabled - One of self::OPTION_ENABLED or self::OPTION_DISABLED
1745      * @param bool $default - The default for the flag
1746      */
1747     public function set_locked_flag_options($enabled, $default) {
1748         $this->set_flag_options($enabled, $default, 'locked', new lang_string('locked', 'core_admin'));
1749     }
1751     /**
1752      * Get the currently saved value for a setting flag
1753      *
1754      * @param admin_setting_flag $flag - One of the admin_setting_flag for this admin_setting.
1755      * @return bool
1756      */
1757     public function get_setting_flag_value(admin_setting_flag $flag) {
1758         $value = $this->config_read($this->name . '_' . $flag->get_shortname());
1759         if (!isset($value)) {
1760             $value = $flag->get_default();
1761         }
1763         return !empty($value);
1764     }
1766     /**
1767      * Get the list of defaults for the flags on this setting.
1768      *
1769      * @param array of strings describing the defaults for this setting. This is appended to by this function.
1770      */
1771     public function get_setting_flag_defaults(& $defaults) {
1772         foreach ($this->flags as $flag) {
1773             if ($flag->is_enabled() && $flag->get_default()) {
1774                 $defaults[] = $flag->get_displayname();
1775             }
1776         }
1777     }
1779     /**
1780      * Output the input fields for the advanced and locked flags on this setting.
1781      *
1782      * @param bool $adv - The current value of the advanced flag.
1783      * @param bool $locked - The current value of the locked flag.
1784      * @return string $output - The html for the flags.
1785      */
1786     public function output_setting_flags() {
1787         $output = '';
1789         foreach ($this->flags as $flag) {
1790             if ($flag->is_enabled()) {
1791                 $output .= $flag->output_setting_flag($this);
1792             }
1793         }
1795         if (!empty($output)) {
1796             return html_writer::tag('span', $output, array('class' => 'adminsettingsflags'));
1797         }
1798         return $output;
1799     }
1801     /**
1802      * Write the values of the flags for this admin setting.
1803      *
1804      * @param array $data - The data submitted from the form or null to set the default value for new installs.
1805      * @return bool - true if successful.
1806      */
1807     public function write_setting_flags($data) {
1808         $result = true;
1809         foreach ($this->flags as $flag) {
1810             $result = $result && $flag->write_setting_flag($this, $data);
1811         }
1812         return $result;
1813     }
1815     /**
1816      * Set up $this->name and potentially $this->plugin
1817      *
1818      * Set up $this->name and possibly $this->plugin based on whether $name looks
1819      * like 'settingname' or 'plugin/settingname'. Also, do some sanity checking
1820      * on the names, that is, output a developer debug warning if the name
1821      * contains anything other than [a-zA-Z0-9_]+.
1822      *
1823      * @param string $name the setting name passed in to the constructor.
1824      */
1825     private function parse_setting_name($name) {
1826         $bits = explode('/', $name);
1827         if (count($bits) > 2) {
1828             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1829         }
1830         $this->name = array_pop($bits);
1831         if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->name)) {
1832             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1833         }
1834         if (!empty($bits)) {
1835             $this->plugin = array_pop($bits);
1836             if ($this->plugin === 'moodle') {
1837                 $this->plugin = null;
1838             } else if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->plugin)) {
1839                     throw new moodle_exception('invalidadminsettingname', '', '', $name);
1840                 }
1841         }
1842     }
1844     /**
1845      * Returns the fullname prefixed by the plugin
1846      * @return string
1847      */
1848     public function get_full_name() {
1849         return 's_'.$this->plugin.'_'.$this->name;
1850     }
1852     /**
1853      * Returns the ID string based on plugin and name
1854      * @return string
1855      */
1856     public function get_id() {
1857         return 'id_s_'.$this->plugin.'_'.$this->name;
1858     }
1860     /**
1861      * @param bool $affectsmodinfo If true, changes to this setting will
1862      *   cause the course cache to be rebuilt
1863      */
1864     public function set_affects_modinfo($affectsmodinfo) {
1865         $this->affectsmodinfo = $affectsmodinfo;
1866     }
1868     /**
1869      * Returns the config if possible
1870      *
1871      * @return mixed returns config if successful else null
1872      */
1873     public function config_read($name) {
1874         global $CFG;
1875         if (!empty($this->plugin)) {
1876             $value = get_config($this->plugin, $name);
1877             return $value === false ? NULL : $value;
1879         } else {
1880             if (isset($CFG->$name)) {
1881                 return $CFG->$name;
1882             } else {
1883                 return NULL;
1884             }
1885         }
1886     }
1888     /**
1889      * Used to set a config pair and log change
1890      *
1891      * @param string $name
1892      * @param mixed $value Gets converted to string if not null
1893      * @return bool Write setting to config table
1894      */
1895     public function config_write($name, $value) {
1896         global $DB, $USER, $CFG;
1898         if ($this->nosave) {
1899             return true;
1900         }
1902         // make sure it is a real change
1903         $oldvalue = get_config($this->plugin, $name);
1904         $oldvalue = ($oldvalue === false) ? null : $oldvalue; // normalise
1905         $value = is_null($value) ? null : (string)$value;
1907         if ($oldvalue === $value) {
1908             return true;
1909         }
1911         // store change
1912         set_config($name, $value, $this->plugin);
1914         // Some admin settings affect course modinfo
1915         if ($this->affectsmodinfo) {
1916             // Clear course cache for all courses
1917             rebuild_course_cache(0, true);
1918         }
1920         $this->add_to_config_log($name, $oldvalue, $value);
1922         return true; // BC only
1923     }
1925     /**
1926      * Log config changes if necessary.
1927      * @param string $name
1928      * @param string $oldvalue
1929      * @param string $value
1930      */
1931     protected function add_to_config_log($name, $oldvalue, $value) {
1932         add_to_config_log($name, $oldvalue, $value, $this->plugin);
1933     }
1935     /**
1936      * Returns current value of this setting
1937      * @return mixed array or string depending on instance, NULL means not set yet
1938      */
1939     public abstract function get_setting();
1941     /**
1942      * Returns default setting if exists
1943      * @return mixed array or string depending on instance; NULL means no default, user must supply
1944      */
1945     public function get_defaultsetting() {
1946         $adminroot =  admin_get_root(false, false);
1947         if (!empty($adminroot->custom_defaults)) {
1948             $plugin = is_null($this->plugin) ? 'moodle' : $this->plugin;
1949             if (isset($adminroot->custom_defaults[$plugin])) {
1950                 if (array_key_exists($this->name, $adminroot->custom_defaults[$plugin])) { // null is valid value here ;-)
1951                     return $adminroot->custom_defaults[$plugin][$this->name];
1952                 }
1953             }
1954         }
1955         return $this->defaultsetting;
1956     }
1958     /**
1959      * Store new setting
1960      *
1961      * @param mixed $data string or array, must not be NULL
1962      * @return string empty string if ok, string error message otherwise
1963      */
1964     public abstract function write_setting($data);
1966     /**
1967      * Return part of form with setting
1968      * This function should always be overwritten
1969      *
1970      * @param mixed $data array or string depending on setting
1971      * @param string $query
1972      * @return string
1973      */
1974     public function output_html($data, $query='') {
1975     // should be overridden
1976         return;
1977     }
1979     /**
1980      * Function called if setting updated - cleanup, cache reset, etc.
1981      * @param string $functionname Sets the function name
1982      * @return void
1983      */
1984     public function set_updatedcallback($functionname) {
1985         $this->updatedcallback = $functionname;
1986     }
1988     /**
1989      * Execute postupdatecallback if necessary.
1990      * @param mixed $original original value before write_setting()
1991      * @return bool true if changed, false if not.
1992      */
1993     public function post_write_settings($original) {
1994         // Comparison must work for arrays too.
1995         if (serialize($original) === serialize($this->get_setting())) {
1996             return false;
1997         }
1999         $callbackfunction = $this->updatedcallback;
2000         if (!empty($callbackfunction) and is_callable($callbackfunction)) {
2001             $callbackfunction($this->get_full_name());
2002         }
2003         return true;
2004     }
2006     /**
2007      * Is setting related to query text - used when searching
2008      * @param string $query
2009      * @return bool
2010      */
2011     public function is_related($query) {
2012         if (strpos(strtolower($this->name), $query) !== false) {
2013             return true;
2014         }
2015         if (strpos(core_text::strtolower($this->visiblename), $query) !== false) {
2016             return true;
2017         }
2018         if (strpos(core_text::strtolower($this->description), $query) !== false) {
2019             return true;
2020         }
2021         $current = $this->get_setting();
2022         if (!is_null($current)) {
2023             if (is_string($current)) {
2024                 if (strpos(core_text::strtolower($current), $query) !== false) {
2025                     return true;
2026                 }
2027             }
2028         }
2029         $default = $this->get_defaultsetting();
2030         if (!is_null($default)) {
2031             if (is_string($default)) {
2032                 if (strpos(core_text::strtolower($default), $query) !== false) {
2033                     return true;
2034                 }
2035             }
2036         }
2037         return false;
2038     }
2040     /**
2041      * Get whether this should be displayed in LTR mode.
2042      *
2043      * @return bool|null
2044      */
2045     public function get_force_ltr() {
2046         return $this->forceltr;
2047     }
2049     /**
2050      * Set whether to force LTR or not.
2051      *
2052      * @param bool $value True when forced, false when not force, null when unknown.
2053      */
2054     public function set_force_ltr($value) {
2055         $this->forceltr = $value;
2056     }
2058     /**
2059      * Add a setting to the list of those that could cause this one to be hidden
2060      * @param string $dependenton
2061      */
2062     public function add_dependent_on($dependenton) {
2063         $this->dependenton[] = $dependenton;
2064     }
2066     /**
2067      * Get a list of the settings that could cause this one to be hidden.
2068      * @return array
2069      */
2070     public function get_dependent_on() {
2071         return $this->dependenton;
2072     }
2075 /**
2076  * An additional option that can be applied to an admin setting.
2077  * The currently supported options are 'ADVANCED' and 'LOCKED'.
2078  *
2079  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2080  */
2081 class admin_setting_flag {
2082     /** @var bool Flag to indicate if this option can be toggled for this setting */
2083     private $enabled = false;
2084     /** @var bool Flag to indicate if this option defaults to true or false */
2085     private $default = false;
2086     /** @var string Short string used to create setting name - e.g. 'adv' */
2087     private $shortname = '';
2088     /** @var string String used as the label for this flag */
2089     private $displayname = '';
2090     /** @const Checkbox for this flag is displayed in admin page */
2091     const ENABLED = true;
2092     /** @const Checkbox for this flag is not displayed in admin page */
2093     const DISABLED = false;
2095     /**
2096      * Constructor
2097      *
2098      * @param bool $enabled Can this option can be toggled.
2099      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
2100      * @param bool $default The default checked state for this setting option.
2101      * @param string $shortname The shortname of this flag. Currently supported flags are 'locked' and 'adv'
2102      * @param string $displayname The displayname of this flag. Used as a label for the flag.
2103      */
2104     public function __construct($enabled, $default, $shortname, $displayname) {
2105         $this->shortname = $shortname;
2106         $this->displayname = $displayname;
2107         $this->set_options($enabled, $default);
2108     }
2110     /**
2111      * Update the values of this setting options class
2112      *
2113      * @param bool $enabled Can this option can be toggled.
2114      *                      Should be one of admin_setting_flag::ENABLED or admin_setting_flag::DISABLED.
2115      * @param bool $default The default checked state for this setting option.
2116      */
2117     public function set_options($enabled, $default) {
2118         $this->enabled = $enabled;
2119         $this->default = $default;
2120     }
2122     /**
2123      * Should this option appear in the interface and be toggleable?
2124      *
2125      * @return bool Is it enabled?
2126      */
2127     public function is_enabled() {
2128         return $this->enabled;
2129     }
2131     /**
2132      * Should this option be checked by default?
2133      *
2134      * @return bool Is it on by default?
2135      */
2136     public function get_default() {
2137         return $this->default;
2138     }
2140     /**
2141      * Return the short name for this flag. e.g. 'adv' or 'locked'
2142      *
2143      * @return string
2144      */
2145     public function get_shortname() {
2146         return $this->shortname;
2147     }
2149     /**
2150      * Return the display name for this flag. e.g. 'Advanced' or 'Locked'
2151      *
2152      * @return string
2153      */
2154     public function get_displayname() {
2155         return $this->displayname;
2156     }
2158     /**
2159      * Save the submitted data for this flag - or set it to the default if $data is null.
2160      *
2161      * @param admin_setting $setting - The admin setting for this flag
2162      * @param array $data - The data submitted from the form or null to set the default value for new installs.
2163      * @return bool
2164      */
2165     public function write_setting_flag(admin_setting $setting, $data) {
2166         $result = true;
2167         if ($this->is_enabled()) {
2168             if (!isset($data)) {
2169                 $value = $this->get_default();
2170             } else {
2171                 $value = !empty($data[$setting->get_full_name() . '_' . $this->get_shortname()]);
2172             }
2173             $result = $setting->config_write($setting->name . '_' . $this->get_shortname(), $value);
2174         }
2176         return $result;
2178     }
2180     /**
2181      * Output the checkbox for this setting flag. Should only be called if the flag is enabled.
2182      *
2183      * @param admin_setting $setting - The admin setting for this flag
2184      * @return string - The html for the checkbox.
2185      */
2186     public function output_setting_flag(admin_setting $setting) {
2187         global $OUTPUT;
2189         $value = $setting->get_setting_flag_value($this);
2191         $context = new stdClass();
2192         $context->id = $setting->get_id() . '_' . $this->get_shortname();
2193         $context->name = $setting->get_full_name() .  '_' . $this->get_shortname();
2194         $context->value = 1;
2195         $context->checked = $value ? true : false;
2196         $context->label = $this->get_displayname();
2198         return $OUTPUT->render_from_template('core_admin/setting_flag', $context);
2199     }
2203 /**
2204  * No setting - just heading and text.
2205  *
2206  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2207  */
2208 class admin_setting_heading extends admin_setting {
2210     /**
2211      * not a setting, just text
2212      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2213      * @param string $heading heading
2214      * @param string $information text in box
2215      */
2216     public function __construct($name, $heading, $information) {
2217         $this->nosave = true;
2218         parent::__construct($name, $heading, $information, '');
2219     }
2221     /**
2222      * Always returns true
2223      * @return bool Always returns true
2224      */
2225     public function get_setting() {
2226         return true;
2227     }
2229     /**
2230      * Always returns true
2231      * @return bool Always returns true
2232      */
2233     public function get_defaultsetting() {
2234         return true;
2235     }
2237     /**
2238      * Never write settings
2239      * @return string Always returns an empty string
2240      */
2241     public function write_setting($data) {
2242     // do not write any setting
2243         return '';
2244     }
2246     /**
2247      * Returns an HTML string
2248      * @return string Returns an HTML string
2249      */
2250     public function output_html($data, $query='') {
2251         global $OUTPUT;
2252         $context = new stdClass();
2253         $context->title = $this->visiblename;
2254         $context->description = $this->description;
2255         $context->descriptionformatted = highlight($query, markdown_to_html($this->description));
2256         return $OUTPUT->render_from_template('core_admin/setting_heading', $context);
2257     }
2260 /**
2261  * No setting - just name and description in same row.
2262  *
2263  * @copyright 2018 onwards Amaia Anabitarte
2264  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2265  */
2266 class admin_setting_description extends admin_setting {
2268     /**
2269      * Not a setting, just text
2270      *
2271      * @param string $name
2272      * @param string $visiblename
2273      * @param string $description
2274      */
2275     public function __construct($name, $visiblename, $description) {
2276         $this->nosave = true;
2277         parent::__construct($name, $visiblename, $description, '');
2278     }
2280     /**
2281      * Always returns true
2282      *
2283      * @return bool Always returns true
2284      */
2285     public function get_setting() {
2286         return true;
2287     }
2289     /**
2290      * Always returns true
2291      *
2292      * @return bool Always returns true
2293      */
2294     public function get_defaultsetting() {
2295         return true;
2296     }
2298     /**
2299      * Never write settings
2300      *
2301      * @param mixed $data Gets converted to str for comparison against yes value
2302      * @return string Always returns an empty string
2303      */
2304     public function write_setting($data) {
2305         // Do not write any setting.
2306         return '';
2307     }
2309     /**
2310      * Returns an HTML string
2311      *
2312      * @param string $data
2313      * @param string $query
2314      * @return string Returns an HTML string
2315      */
2316     public function output_html($data, $query='') {
2317         global $OUTPUT;
2319         $context = new stdClass();
2320         $context->title = $this->visiblename;
2321         $context->description = $this->description;
2323         return $OUTPUT->render_from_template('core_admin/setting_description', $context);
2324     }
2329 /**
2330  * The most flexible setting, the user enters text.
2331  *
2332  * This type of field should be used for config settings which are using
2333  * English words and are not localised (passwords, database name, list of values, ...).
2334  *
2335  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2336  */
2337 class admin_setting_configtext extends admin_setting {
2339     /** @var mixed int means PARAM_XXX type, string is a allowed format in regex */
2340     public $paramtype;
2341     /** @var int default field size */
2342     public $size;
2344     /**
2345      * Config text constructor
2346      *
2347      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2348      * @param string $visiblename localised
2349      * @param string $description long localised info
2350      * @param string $defaultsetting
2351      * @param mixed $paramtype int means PARAM_XXX type, string is a allowed format in regex
2352      * @param int $size default field size
2353      */
2354     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $size=null) {
2355         $this->paramtype = $paramtype;
2356         if (!is_null($size)) {
2357             $this->size  = $size;
2358         } else {
2359             $this->size  = ($paramtype === PARAM_INT) ? 5 : 30;
2360         }
2361         parent::__construct($name, $visiblename, $description, $defaultsetting);
2362     }
2364     /**
2365      * Get whether this should be displayed in LTR mode.
2366      *
2367      * Try to guess from the PARAM type unless specifically set.
2368      */
2369     public function get_force_ltr() {
2370         $forceltr = parent::get_force_ltr();
2371         if ($forceltr === null) {
2372             return !is_rtl_compatible($this->paramtype);
2373         }
2374         return $forceltr;
2375     }
2377     /**
2378      * Return the setting
2379      *
2380      * @return mixed returns config if successful else null
2381      */
2382     public function get_setting() {
2383         return $this->config_read($this->name);
2384     }
2386     public function write_setting($data) {
2387         if ($this->paramtype === PARAM_INT and $data === '') {
2388         // do not complain if '' used instead of 0
2389             $data = 0;
2390         }
2391         // $data is a string
2392         $validated = $this->validate($data);
2393         if ($validated !== true) {
2394             return $validated;
2395         }
2396         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2397     }
2399     /**
2400      * Validate data before storage
2401      * @param string data
2402      * @return mixed true if ok string if error found
2403      */
2404     public function validate($data) {
2405         // allow paramtype to be a custom regex if it is the form of /pattern/
2406         if (preg_match('#^/.*/$#', $this->paramtype)) {
2407             if (preg_match($this->paramtype, $data)) {
2408                 return true;
2409             } else {
2410                 return get_string('validateerror', 'admin');
2411             }
2413         } else if ($this->paramtype === PARAM_RAW) {
2414             return true;
2416         } else {
2417             $cleaned = clean_param($data, $this->paramtype);
2418             if ("$data" === "$cleaned") { // implicit conversion to string is needed to do exact comparison
2419                 return true;
2420             } else {
2421                 return get_string('validateerror', 'admin');
2422             }
2423         }
2424     }
2426     /**
2427      * Return an XHTML string for the setting
2428      * @return string Returns an XHTML string
2429      */
2430     public function output_html($data, $query='') {
2431         global $OUTPUT;
2433         $default = $this->get_defaultsetting();
2434         $context = (object) [
2435             'size' => $this->size,
2436             'id' => $this->get_id(),
2437             'name' => $this->get_full_name(),
2438             'value' => $data,
2439             'forceltr' => $this->get_force_ltr(),
2440         ];
2441         $element = $OUTPUT->render_from_template('core_admin/setting_configtext', $context);
2443         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', $default, $query);
2444     }
2447 /**
2448  * Text input with a maximum length constraint.
2449  *
2450  * @copyright 2015 onwards Ankit Agarwal
2451  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2452  */
2453 class admin_setting_configtext_with_maxlength extends admin_setting_configtext {
2455     /** @var int maximum number of chars allowed. */
2456     protected $maxlength;
2458     /**
2459      * Config text constructor
2460      *
2461      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
2462      *                     or 'myplugin/mysetting' for ones in config_plugins.
2463      * @param string $visiblename localised
2464      * @param string $description long localised info
2465      * @param string $defaultsetting
2466      * @param mixed $paramtype int means PARAM_XXX type, string is a allowed format in regex
2467      * @param int $size default field size
2468      * @param mixed $maxlength int maxlength allowed, 0 for infinite.
2469      */
2470     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW,
2471                                 $size=null, $maxlength = 0) {
2472         $this->maxlength = $maxlength;
2473         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype, $size);
2474     }
2476     /**
2477      * Validate data before storage
2478      *
2479      * @param string $data data
2480      * @return mixed true if ok string if error found
2481      */
2482     public function validate($data) {
2483         $parentvalidation = parent::validate($data);
2484         if ($parentvalidation === true) {
2485             if ($this->maxlength > 0) {
2486                 // Max length check.
2487                 $length = core_text::strlen($data);
2488                 if ($length > $this->maxlength) {
2489                     return get_string('maximumchars', 'moodle',  $this->maxlength);
2490                 }
2491                 return true;
2492             } else {
2493                 return true; // No max length check needed.
2494             }
2495         } else {
2496             return $parentvalidation;
2497         }
2498     }
2501 /**
2502  * General text area without html editor.
2503  *
2504  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2505  */
2506 class admin_setting_configtextarea extends admin_setting_configtext {
2507     private $rows;
2508     private $cols;
2510     /**
2511      * @param string $name
2512      * @param string $visiblename
2513      * @param string $description
2514      * @param mixed $defaultsetting string or array
2515      * @param mixed $paramtype
2516      * @param string $cols The number of columns to make the editor
2517      * @param string $rows The number of rows to make the editor
2518      */
2519     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2520         $this->rows = $rows;
2521         $this->cols = $cols;
2522         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
2523     }
2525     /**
2526      * Returns an XHTML string for the editor
2527      *
2528      * @param string $data
2529      * @param string $query
2530      * @return string XHTML string for the editor
2531      */
2532     public function output_html($data, $query='') {
2533         global $OUTPUT;
2535         $default = $this->get_defaultsetting();
2536         $defaultinfo = $default;
2537         if (!is_null($default) and $default !== '') {
2538             $defaultinfo = "\n".$default;
2539         }
2541         $context = (object) [
2542             'cols' => $this->cols,
2543             'rows' => $this->rows,
2544             'id' => $this->get_id(),
2545             'name' => $this->get_full_name(),
2546             'value' => $data,
2547             'forceltr' => $this->get_force_ltr(),
2548         ];
2549         $element = $OUTPUT->render_from_template('core_admin/setting_configtextarea', $context);
2551         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', $defaultinfo, $query);
2552     }
2555 /**
2556  * General text area with html editor.
2557  */
2558 class admin_setting_confightmleditor extends admin_setting_configtextarea {
2560     /**
2561      * @param string $name
2562      * @param string $visiblename
2563      * @param string $description
2564      * @param mixed $defaultsetting string or array
2565      * @param mixed $paramtype
2566      */
2567     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
2568         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype, $cols, $rows);
2569         $this->set_force_ltr(false);
2570         editors_head_setup();
2571     }
2573     /**
2574      * Returns an XHTML string for the editor
2575      *
2576      * @param string $data
2577      * @param string $query
2578      * @return string XHTML string for the editor
2579      */
2580     public function output_html($data, $query='') {
2581         $editor = editors_get_preferred_editor(FORMAT_HTML);
2582         $editor->set_text($data);
2583         $editor->use_editor($this->get_id(), array('noclean'=>true));
2584         return parent::output_html($data, $query);
2585     }
2587     /**
2588      * Checks if data has empty html.
2589      *
2590      * @param string $data
2591      * @return string Empty when no errors.
2592      */
2593     public function write_setting($data) {
2594         if (trim(html_to_text($data)) === '') {
2595             $data = '';
2596         }
2597         return parent::write_setting($data);
2598     }
2602 /**
2603  * Password field, allows unmasking of password
2604  *
2605  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2606  */
2607 class admin_setting_configpasswordunmask extends admin_setting_configtext {
2609     /**
2610      * Constructor
2611      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2612      * @param string $visiblename localised
2613      * @param string $description long localised info
2614      * @param string $defaultsetting default password
2615      */
2616     public function __construct($name, $visiblename, $description, $defaultsetting) {
2617         parent::__construct($name, $visiblename, $description, $defaultsetting, PARAM_RAW, 30);
2618     }
2620     /**
2621      * Log config changes if necessary.
2622      * @param string $name
2623      * @param string $oldvalue
2624      * @param string $value
2625      */
2626     protected function add_to_config_log($name, $oldvalue, $value) {
2627         if ($value !== '') {
2628             $value = '********';
2629         }
2630         if ($oldvalue !== '' and $oldvalue !== null) {
2631             $oldvalue = '********';
2632         }
2633         parent::add_to_config_log($name, $oldvalue, $value);
2634     }
2636     /**
2637      * Returns HTML for the field.
2638      *
2639      * @param   string  $data       Value for the field
2640      * @param   string  $query      Passed as final argument for format_admin_setting
2641      * @return  string              Rendered HTML
2642      */
2643     public function output_html($data, $query='') {
2644         global $OUTPUT;
2645         $context = (object) [
2646             'id' => $this->get_id(),
2647             'name' => $this->get_full_name(),
2648             'size' => $this->size,
2649             'value' => $data,
2650             'forceltr' => $this->get_force_ltr(),
2651         ];
2652         $element = $OUTPUT->render_from_template('core_admin/setting_configpasswordunmask', $context);
2653         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', null, $query);
2654     }
2657 /**
2658  * Password field, allows unmasking of password, with an advanced checkbox that controls an additional $name.'_adv' setting.
2659  *
2660  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2661  * @copyright 2018 Paul Holden (pholden@greenhead.ac.uk)
2662  */
2663 class admin_setting_configpasswordunmask_with_advanced extends admin_setting_configpasswordunmask {
2665     /**
2666      * Constructor
2667      *
2668      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2669      * @param string $visiblename localised
2670      * @param string $description long localised info
2671      * @param array $defaultsetting ('value'=>string, 'adv'=>bool)
2672      */
2673     public function __construct($name, $visiblename, $description, $defaultsetting) {
2674         parent::__construct($name, $visiblename, $description, $defaultsetting['value']);
2675         $this->set_advanced_flag_options(admin_setting_flag::ENABLED, !empty($defaultsetting['adv']));
2676     }
2679 /**
2680  * Empty setting used to allow flags (advanced) on settings that can have no sensible default.
2681  * Note: Only advanced makes sense right now - locked does not.
2682  *
2683  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2684  */
2685 class admin_setting_configempty extends admin_setting_configtext {
2687     /**
2688      * @param string $name
2689      * @param string $visiblename
2690      * @param string $description
2691      */
2692     public function __construct($name, $visiblename, $description) {
2693         parent::__construct($name, $visiblename, $description, '', PARAM_RAW);
2694     }
2696     /**
2697      * Returns an XHTML string for the hidden field
2698      *
2699      * @param string $data
2700      * @param string $query
2701      * @return string XHTML string for the editor
2702      */
2703     public function output_html($data, $query='') {
2704         global $OUTPUT;
2706         $context = (object) [
2707             'id' => $this->get_id(),
2708             'name' => $this->get_full_name()
2709         ];
2710         $element = $OUTPUT->render_from_template('core_admin/setting_configempty', $context);
2712         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', get_string('none'), $query);
2713     }
2717 /**
2718  * Path to directory
2719  *
2720  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2721  */
2722 class admin_setting_configfile extends admin_setting_configtext {
2723     /**
2724      * Constructor
2725      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2726      * @param string $visiblename localised
2727      * @param string $description long localised info
2728      * @param string $defaultdirectory default directory location
2729      */
2730     public function __construct($name, $visiblename, $description, $defaultdirectory) {
2731         parent::__construct($name, $visiblename, $description, $defaultdirectory, PARAM_RAW, 50);
2732     }
2734     /**
2735      * Returns XHTML for the field
2736      *
2737      * Returns XHTML for the field and also checks whether the file
2738      * specified in $data exists using file_exists()
2739      *
2740      * @param string $data File name and path to use in value attr
2741      * @param string $query
2742      * @return string XHTML field
2743      */
2744     public function output_html($data, $query='') {
2745         global $CFG, $OUTPUT;
2747         $default = $this->get_defaultsetting();
2748         $context = (object) [
2749             'id' => $this->get_id(),
2750             'name' => $this->get_full_name(),
2751             'size' => $this->size,
2752             'value' => $data,
2753             'showvalidity' => !empty($data),
2754             'valid' => $data && file_exists($data),
2755             'readonly' => !empty($CFG->preventexecpath),
2756             'forceltr' => $this->get_force_ltr(),
2757         ];
2759         if ($context->readonly) {
2760             $this->visiblename .= '<div class="alert alert-info">'.get_string('execpathnotallowed', 'admin').'</div>';
2761         }
2763         $element = $OUTPUT->render_from_template('core_admin/setting_configfile', $context);
2765         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', $default, $query);
2766     }
2768     /**
2769      * Checks if execpatch has been disabled in config.php
2770      */
2771     public function write_setting($data) {
2772         global $CFG;
2773         if (!empty($CFG->preventexecpath)) {
2774             if ($this->get_setting() === null) {
2775                 // Use default during installation.
2776                 $data = $this->get_defaultsetting();
2777                 if ($data === null) {
2778                     $data = '';
2779                 }
2780             } else {
2781                 return '';
2782             }
2783         }
2784         return parent::write_setting($data);
2785     }
2790 /**
2791  * Path to executable file
2792  *
2793  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2794  */
2795 class admin_setting_configexecutable extends admin_setting_configfile {
2797     /**
2798      * Returns an XHTML field
2799      *
2800      * @param string $data This is the value for the field
2801      * @param string $query
2802      * @return string XHTML field
2803      */
2804     public function output_html($data, $query='') {
2805         global $CFG, $OUTPUT;
2806         $default = $this->get_defaultsetting();
2807         require_once("$CFG->libdir/filelib.php");
2809         $context = (object) [
2810             'id' => $this->get_id(),
2811             'name' => $this->get_full_name(),
2812             'size' => $this->size,
2813             'value' => $data,
2814             'showvalidity' => !empty($data),
2815             'valid' => $data && file_exists($data) && !is_dir($data) && file_is_executable($data),
2816             'readonly' => !empty($CFG->preventexecpath),
2817             'forceltr' => $this->get_force_ltr()
2818         ];
2820         if (!empty($CFG->preventexecpath)) {
2821             $this->visiblename .= '<div class="alert alert-info">'.get_string('execpathnotallowed', 'admin').'</div>';
2822         }
2824         $element = $OUTPUT->render_from_template('core_admin/setting_configexecutable', $context);
2826         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', $default, $query);
2827     }
2831 /**
2832  * Path to directory
2833  *
2834  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2835  */
2836 class admin_setting_configdirectory extends admin_setting_configfile {
2838     /**
2839      * Returns an XHTML field
2840      *
2841      * @param string $data This is the value for the field
2842      * @param string $query
2843      * @return string XHTML
2844      */
2845     public function output_html($data, $query='') {
2846         global $CFG, $OUTPUT;
2847         $default = $this->get_defaultsetting();
2849         $context = (object) [
2850             'id' => $this->get_id(),
2851             'name' => $this->get_full_name(),
2852             'size' => $this->size,
2853             'value' => $data,
2854             'showvalidity' => !empty($data),
2855             'valid' => $data && file_exists($data) && is_dir($data),
2856             'readonly' => !empty($CFG->preventexecpath),
2857             'forceltr' => $this->get_force_ltr()
2858         ];
2860         if (!empty($CFG->preventexecpath)) {
2861             $this->visiblename .= '<div class="alert alert-info">'.get_string('execpathnotallowed', 'admin').'</div>';
2862         }
2864         $element = $OUTPUT->render_from_template('core_admin/setting_configdirectory', $context);
2866         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', $default, $query);
2867     }
2871 /**
2872  * Checkbox
2873  *
2874  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2875  */
2876 class admin_setting_configcheckbox extends admin_setting {
2877     /** @var string Value used when checked */
2878     public $yes;
2879     /** @var string Value used when not checked */
2880     public $no;
2882     /**
2883      * Constructor
2884      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2885      * @param string $visiblename localised
2886      * @param string $description long localised info
2887      * @param string $defaultsetting
2888      * @param string $yes value used when checked
2889      * @param string $no value used when not checked
2890      */
2891     public function __construct($name, $visiblename, $description, $defaultsetting, $yes='1', $no='0') {
2892         parent::__construct($name, $visiblename, $description, $defaultsetting);
2893         $this->yes = (string)$yes;
2894         $this->no  = (string)$no;
2895     }
2897     /**
2898      * Retrieves the current setting using the objects name
2899      *
2900      * @return string
2901      */
2902     public function get_setting() {
2903         return $this->config_read($this->name);
2904     }
2906     /**
2907      * Sets the value for the setting
2908      *
2909      * Sets the value for the setting to either the yes or no values
2910      * of the object by comparing $data to yes
2911      *
2912      * @param mixed $data Gets converted to str for comparison against yes value
2913      * @return string empty string or error
2914      */
2915     public function write_setting($data) {
2916         if ((string)$data === $this->yes) { // convert to strings before comparison
2917             $data = $this->yes;
2918         } else {
2919             $data = $this->no;
2920         }
2921         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2922     }
2924     /**
2925      * Returns an XHTML checkbox field
2926      *
2927      * @param string $data If $data matches yes then checkbox is checked
2928      * @param string $query
2929      * @return string XHTML field
2930      */
2931     public function output_html($data, $query='') {
2932         global $OUTPUT;
2934         $context = (object) [
2935             'id' => $this->get_id(),
2936             'name' => $this->get_full_name(),
2937             'no' => $this->no,
2938             'value' => $this->yes,
2939             'checked' => (string) $data === $this->yes,
2940         ];
2942         $default = $this->get_defaultsetting();
2943         if (!is_null($default)) {
2944             if ((string)$default === $this->yes) {
2945                 $defaultinfo = get_string('checkboxyes', 'admin');
2946             } else {
2947                 $defaultinfo = get_string('checkboxno', 'admin');
2948             }
2949         } else {
2950             $defaultinfo = NULL;
2951         }
2953         $element = $OUTPUT->render_from_template('core_admin/setting_configcheckbox', $context);
2955         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', $defaultinfo, $query);
2956     }
2960 /**
2961  * Multiple checkboxes, each represents different value, stored in csv format
2962  *
2963  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2964  */
2965 class admin_setting_configmulticheckbox extends admin_setting {
2966     /** @var array Array of choices value=>label */
2967     public $choices;
2969     /**
2970      * Constructor: uses parent::__construct
2971      *
2972      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2973      * @param string $visiblename localised
2974      * @param string $description long localised info
2975      * @param array $defaultsetting array of selected
2976      * @param array $choices array of $value=>$label for each checkbox
2977      */
2978     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2979         $this->choices = $choices;
2980         parent::__construct($name, $visiblename, $description, $defaultsetting);
2981     }
2983     /**
2984      * This public function may be used in ancestors for lazy loading of choices
2985      *
2986      * @todo Check if this function is still required content commented out only returns true
2987      * @return bool true if loaded, false if error
2988      */
2989     public function load_choices() {
2990         /*
2991         if (is_array($this->choices)) {
2992             return true;
2993         }
2994         .... load choices here
2995         */
2996         return true;
2997     }
2999     /**
3000      * Is setting related to query text - used when searching
3001      *
3002      * @param string $query
3003      * @return bool true on related, false on not or failure
3004      */
3005     public function is_related($query) {
3006         if (!$this->load_choices() or empty($this->choices)) {
3007             return false;
3008         }
3009         if (parent::is_related($query)) {
3010             return true;
3011         }
3013         foreach ($this->choices as $desc) {
3014             if (strpos(core_text::strtolower($desc), $query) !== false) {
3015                 return true;
3016             }
3017         }
3018         return false;
3019     }
3021     /**
3022      * Returns the current setting if it is set
3023      *
3024      * @return mixed null if null, else an array
3025      */
3026     public function get_setting() {
3027         $result = $this->config_read($this->name);
3029         if (is_null($result)) {
3030             return NULL;
3031         }
3032         if ($result === '') {
3033             return array();
3034         }
3035         $enabled = explode(',', $result);
3036         $setting = array();
3037         foreach ($enabled as $option) {
3038             $setting[$option] = 1;
3039         }
3040         return $setting;
3041     }
3043     /**
3044      * Saves the setting(s) provided in $data
3045      *
3046      * @param array $data An array of data, if not array returns empty str
3047      * @return mixed empty string on useless data or bool true=success, false=failed
3048      */
3049     public function write_setting($data) {
3050         if (!is_array($data)) {
3051             return ''; // ignore it
3052         }
3053         if (!$this->load_choices() or empty($this->choices)) {
3054             return '';
3055         }
3056         unset($data['xxxxx']);
3057         $result = array();
3058         foreach ($data as $key => $value) {
3059             if ($value and array_key_exists($key, $this->choices)) {
3060                 $result[] = $key;
3061             }
3062         }
3063         return $this->config_write($this->name, implode(',', $result)) ? '' : get_string('errorsetting', 'admin');
3064     }
3066     /**
3067      * Returns XHTML field(s) as required by choices
3068      *
3069      * Relies on data being an array should data ever be another valid vartype with
3070      * acceptable value this may cause a warning/error
3071      * if (!is_array($data)) would fix the problem
3072      *
3073      * @todo Add vartype handling to ensure $data is an array
3074      *
3075      * @param array $data An array of checked values
3076      * @param string $query
3077      * @return string XHTML field
3078      */
3079     public function output_html($data, $query='') {
3080         global $OUTPUT;
3082         if (!$this->load_choices() or empty($this->choices)) {
3083             return '';
3084         }
3086         $default = $this->get_defaultsetting();
3087         if (is_null($default)) {
3088             $default = array();
3089         }
3090         if (is_null($data)) {
3091             $data = array();
3092         }
3094         $context = (object) [
3095             'id' => $this->get_id(),
3096             'name' => $this->get_full_name(),
3097         ];
3099         $options = array();
3100         $defaults = array();
3101         foreach ($this->choices as $key => $description) {
3102             if (!empty($default[$key])) {
3103                 $defaults[] = $description;
3104             }
3106             $options[] = [
3107                 'key' => $key,
3108                 'checked' => !empty($data[$key]),
3109                 'label' => highlightfast($query, $description)
3110             ];
3111         }
3113         if (is_null($default)) {
3114             $defaultinfo = null;
3115         } else if (!empty($defaults)) {
3116             $defaultinfo = implode(', ', $defaults);
3117         } else {
3118             $defaultinfo = get_string('none');
3119         }
3121         $context->options = $options;
3122         $context->hasoptions = !empty($options);
3124         $element = $OUTPUT->render_from_template('core_admin/setting_configmulticheckbox', $context);
3126         return format_admin_setting($this, $this->visiblename, $element, $this->description, false, '', $defaultinfo, $query);
3128     }
3132 /**
3133  * Multiple checkboxes 2, value stored as string 00101011
3134  *
3135  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3136  */
3137 class admin_setting_configmulticheckbox2 extends admin_setting_configmulticheckbox {
3139     /**
3140      * Returns the setting if set
3141      *
3142      * @return mixed null if not set, else an array of set settings
3143      */
3144     public function get_setting() {
3145         $result = $this->config_read($this->name);
3146         if (is_null($result)) {
3147             return NULL;
3148         }
3149         if (!$this->load_choices()) {
3150             return NULL;
3151         }
3152         $result = str_pad($result, count($this->choices), '0');
3153         $result = preg_split('//', $result, -1, PREG_SPLIT_NO_EMPTY);
3154         $setting = array();
3155         foreach ($this->choices as $key=>$unused) {
3156             $value = array_shift($result);
3157             if ($value) {
3158                 $setting[$key] = 1;
3159             }
3160         }
3161         return $setting;
3162     }
3164     /**
3165      * Save setting(s) provided in $data param
3166      *
3167      * @param array $data An array of settings to save
3168      * @return mixed empty string for bad data or bool true=>success, false=>error
3169      */
3170     public function write_setting($data) {
3171         if (!is_array($data)) {
3172             return ''; // ignore it
3173         }
3174         if (!$this->load_choices() or empty($this->choices)) {
3175             return '';
3176         }
3177         $result = '';
3178         foreach ($this->choices as $key=>$unused) {
3179             if (!empty($data[$key])) {
3180                 $result .= '1';
3181             } else {
3182                 $result .= '0';
3183             }
3184         }
3185         return $this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin');
3186     }
3190 /**
3191  * Select one value from list
3192  *
3193  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3194  */
3195 class admin_setting_configselect extends admin_setting {
3196     /** @var array Array of choices value=>label */
3197     public $choices;
3198     /** @var array Array of choices grouped using optgroups */
3199     public $optgroups;
3201     /**
3202      * Constructor
3203      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
3204      * @param string $visiblename localised
3205      * @param string $description long localised info
3206      * @param string|int $defaultsetting
3207      * @param array $choices array of $value=>$label for each selection
3208      */
3209     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
3210         // Look for optgroup and single options.
3211         if (is_array($choices)) {
3212             $this->choices = [];
3213             foreach ($choices as $key => $val) {
3214                 if (is_array($val)) {
3215                     $this->optgroups[$key] = $val;
3216                     $this->choices = array_merge($this->choices, $val);
3217                 } else {
3218                     $this->choices[$key] = $val;
3219                 }
3220             }
3221         }
3223         parent::__construct($name, $visiblename, $description, $defaultsetting);
3224     }
3226     /**
3227      * This function may be used in ancestors for lazy loading of choices
3228      *
3229      * Override this method if loading of choices is expensive, such
3230      * as when it requires multiple db requests.
3231      *
3232      * @return bool true if loaded, false if error
3233      */
3234     public function load_choices() {
3235         /*
3236         if (is_array($this->choices)) {
3237             return true;
3238         }
3239         .... load choices here
3240         */
3241         return true;
3242     }
3244     /**
3245      * Check if this is $query is related to a choice
3246      *
3247      * @param string $query
3248      * @return bool true if related, false if not
3249      */
3250     public function is_related($query) {
3251         if (parent::is_related($query)) {
3252             return true;
3253         }
3254         if (!$this->load_choices()) {
3255             return false;
3256         }
3257         foreach ($this->choices as $key=>$value) {
3258             if (strpos(core_text::strtolower($key), $query) !== false) {
3259                 return true;
3260             }
3261             if (strpos(core_text::strtolower($value), $query) !== false) {
3262                 return true;
3263             }
3264         }
3265         return false;
3266     }
3268     /**
3269      * Return the setting
3270      *
3271      * @return mixed returns config if successful else null
3272      */
3273     public function get_setting() {
3274         return $this->config_read($this->name);
3275     }
3277     /**
3278      * Save a setting
3279      *
3280      * @param string $data
3281      * @return string empty of error string
3282      */
3283     public function write_setting($data) {
3284         if (!$this->load_choices() or empty($this->choices)) {
3285             return '';
3286         }
3287         if (!array_key_exists($data, $this->choices)) {
3288             return ''; // ignore it
3289         }
3291         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
3292     }
3294     /**
3295      * Returns XHTML select field
3296      *
3297      * Ensure the options are loaded, and generate the XHTML for the select
3298      * element and any warning message. Separating this out from output_html
3299      * makes it easier to subclass this class.
3300      *
3301      * @param string $data the option to show as selected.
3302      * @param string $current the currently selected option in the database, null if none.
3303      * @param string $default the default selected option.
3304      * @return array the HTML for the select element, and a warning message.
3305      * @deprecated since Moodle 3.2
3306      */
3307     public function output_select_html($data, $current, $default, $extraname = '') {
3308         debugging('The method admin_setting_configselect::output_select_html is depreacted, do not use any more.', DEBUG_DEVELOPER);
3309     }
3311     /**
3312      * Returns XHTML select field and wrapping div(s)
3313      *
3314      * @see output_select_html()
3315      *
3316      * @param string $data the option to show as selected
3317      * @param string $query
3318      * @return string XHTML field and wrapping div
3319      */
3320     public function output_html($data, $query='') {
3321         global $OUTPUT;
3323         $default = $this->get_defaultsetting();
3324         $current = $this->get_setting();
3326         if (!$this->load_choices() || empty($this->choices)) {
3327             return '';
3328         }
3330         $context = (object) [
3331             'id' => $this->get_id(),
3332             'name' => $this->get_full_name(),
3333         ];
3335         if (!is_null($default) && array_key_exists($default, $this->choices)) {
3336             $defaultinfo = $this->choices[$default];
3337         } else {
3338             $defaultinfo = NULL;
3339         }
3341         // Warnings.
3342         $warning = '';
3343         if ($current === null) {
3344             // First run.
3345         } else if (empty($current) && (array_key_exists('', $this->choices) || array_key_exists(0, $this->choices))) {
3346             // No warning.
3347         } else if (!array_key_exists($current, $this->choices)) {
3348             $warning = get_string('warningcurrentsetting', 'admin', $current);
3349             if (!is_null($default) && $data == $current) {
3350                 $data = $default; // Use default instead of first value when showing the form.
3351             }
3352         }
3354         $options = [];
3355         $template = 'core_admin/setting_configselect';
3357         if (!empty($this->optgroups)) {
3358             $optgroups = [];
3359             foreach ($this->optgroups as $label => $choices) {
3360                 $optgroup = array('label' => $label, 'options' => []);
3361                 foreach ($choices as $value => $name) {
3362                     $optgroup['options'][] = [
3363                         'value' => $value,
3364                         'name' => $name,
3365                         'selected' => (string) $value == $data
3366                     ];
3367                     unset($this->choices[$value]);
3368                 }
3369                 $optgroups[] = $optgroup;
3370             }
3371             $context->options = $options;
3372             $context->optgroups = $optgroups;
3373             $template = 'core_admin/setting_configselect_optgroup';
3374         }
3376         foreach ($this->choices as $value => $name) {
3377             $options[] = [
3378                 'value' => $value,
3379                 'name' => $name,
3380                 'selected' => (string) $value == $data
3381             ];
3382         }
3383         $context->options = $options;
3385         $element = $OUTPUT->render_from_template($template, $context);
3387         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, $warning, $defaultinfo, $query);
3388     }
3392 /**
3393  * Select multiple items from list
3394  *
3395  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3396  */
3397 class admin_setting_configmultiselect extends admin_setting_configselect {
3398     /**
3399      * Constructor
3400      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
3401      * @param string $visiblename localised
3402      * @param string $description long localised info
3403      * @param array $defaultsetting array of selected items
3404      * @param array $choices array of $value=>$label for each list item
3405      */
3406     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
3407         parent::__construct($name, $visiblename, $description, $defaultsetting, $choices);
3408     }
3410     /**
3411      * Returns the select setting(s)
3412      *
3413      * @return mixed null or array. Null if no settings else array of setting(s)
3414      */
3415     public function get_setting() {
3416         $result = $this->config_read($this->name);
3417         if (is_null($result)) {
3418             return NULL;
3419         }
3420         if ($result === '') {
3421             return array();
3422         }
3423         return explode(',', $result);
3424     }
3426     /**
3427      * Saves setting(s) provided through $data
3428      *
3429      * Potential bug in the works should anyone call with this function
3430      * using a vartype that is not an array
3431      *
3432      * @param array $data
3433      */
3434     public function write_setting($data) {
3435         if (!is_array($data)) {
3436             return ''; //ignore it
3437         }
3438         if (!$this->load_choices() or empty($this->choices)) {
3439             return '';
3440         }
3442         unset($data['xxxxx']);
3444         $save = array();
3445         foreach ($data as $value) {
3446             if (!array_key_exists($value, $this->choices)) {
3447                 continue; // ignore it
3448             }
3449             $save[] = $value;
3450         }
3452         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
3453     }
3455     /**
3456      * Is setting related to query text - used when searching
3457      *
3458      * @param string $query
3459      * @return bool true if related, false if not
3460      */
3461     public function is_related($query) {
3462         if (!$this->load_choices() or empty($this->choices)) {
3463             return false;
3464         }
3465         if (parent::is_related($query)) {
3466             return true;
3467         }
3469         foreach ($this->choices as $desc) {
3470             if (strpos(core_text::strtolower($desc), $query) !== false) {
3471                 return true;
3472             }
3473         }
3474         return false;
3475     }
3477     /**
3478      * Returns XHTML multi-select field
3479      *
3480      * @todo Add vartype handling to ensure $data is an array
3481      * @param array $data Array of values to select by default
3482      * @param string $query
3483      * @return string XHTML multi-select field
3484      */
3485     public function output_html($data, $query='') {
3486         global $OUTPUT;
3488         if (!$this->load_choices() or empty($this->choices)) {
3489             return '';
3490         }
3492         $default = $this->get_defaultsetting();
3493         if (is_null($default)) {
3494             $default = array();
3495         }
3496         if (is_null($data)) {
3497             $data = array();
3498         }
3500         $context = (object) [
3501             'id' => $this->get_id(),
3502             'name' => $this->get_full_name(),
3503             'size' => min(10, count($this->choices))
3504         ];
3506         $defaults = [];
3507         $options = [];
3508         $template = 'core_admin/setting_configmultiselect';
3510         if (!empty($this->optgroups)) {
3511             $optgroups = [];
3512             foreach ($this->optgroups as $label => $choices) {
3513                 $optgroup = array('label' => $label, 'options' => []);
3514                 foreach ($choices as $value => $name) {
3515                     if (in_array($value, $default)) {
3516                         $defaults[] = $name;
3517                     }
3518                     $optgroup['options'][] = [
3519                         'value' => $value,
3520                         'name' => $name,
3521                         'selected' => in_array($value, $data)
3522                     ];
3523                     unset($this->choices[$value]);
3524                 }
3525                 $optgroups[] = $optgroup;
3526             }
3527             $context->optgroups = $optgroups;
3528             $template = 'core_admin/setting_configmultiselect_optgroup';
3529         }
3531         foreach ($this->choices as $value => $name) {
3532             if (in_array($value, $default)) {
3533                 $defaults[] = $name;
3534             }
3535             $options[] = [
3536                 'value' => $value,
3537                 'name' => $name,
3538                 'selected' => in_array($value, $data)
3539             ];
3540         }
3541         $context->options = $options;
3543         if (is_null($default)) {
3544             $defaultinfo = NULL;
3545         } if (!empty($defaults)) {
3546             $defaultinfo = implode(', ', $defaults);
3547         } else {
3548             $defaultinfo = get_string('none');
3549         }
3551         $element = $OUTPUT->render_from_template($template, $context);
3553         return format_admin_setting($this, $this->visiblename, $element, $this->description, true, '', $defaultinfo, $query);
3554     }
3557 /**
3558  * Time selector
3559  *
3560  * This is a liiitle bit messy. we're using two selects, but we're returning
3561  * them as an array named after $name (so we only use $name2 internally for the setting)
3562  *
3563  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3564  */
3565 class admin_setting_configtime extends admin_setting {
3566     /** @var string Used for setting second select (minutes) */
3567     public $name2;
3569     /**
3570      * Constructor
3571      * @param string $hoursname setting for hours
3572      * @param string $minutesname setting for hours
3573      * @param string $visiblename localised
3574      * @param string $description long localised info
3575      * @param array $defaultsetting array representing default time 'h'=>hours, 'm'=>minutes
3576      */
3577     public function __construct($hoursname, $minutesname, $visiblename, $description, $defaultsetting) {
3578         $this->name2 = $minutesname;
3579         parent::__construct($hoursname, $visiblename, $description, $defaultsetting);
3580     }
3582     /**
3583      * Get the selected time
3584      *
3585      * @return mixed An array containing 'h'=>xx, 'm'=>xx, or null if not set
3586      */
3587     public function get_setting() {
3588         $result1 = $this->config_read($this->name);
3589         $result2 = $this->config_read($this->name2);
3590         if (is_null($result1) or is_null($result2)) {
3591             return NULL;
3592         }
3594         return array('h' => $result1, 'm' => $result2);
3595     }
3597     /**
3598      * Store the time (hours and minutes)
3599      *
3600      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3601      * @return bool true if success, false if not
3602      */
3603     public function write_setting($data) {
3604         if (!is_array($data)) {
3605             return '';
3606         }
3608         $result = $this->config_write($this->name, (int)$data['h']) && $this->config_write($this->name2, (int)$data['m']);
3609         return ($result ? '' : get_string('errorsetting', 'admin'));
3610     }
3612     /**
3613      * Returns XHTML time select fields
3614      *
3615      * @param array $data Must be form 'h'=>xx, 'm'=>xx
3616      * @param string $query
3617      * @return string XHTML time select fields and wrapping div(s)
3618      */
3619     public function output_html($data, $query='') {
3620         global $OUTPUT;
3622         $default = $this->get_defaultsetting();
3623         if (is_array($default)) {
3624             $defaultinfo = $default['h'].':'.$default['m'];
3625         } else {
3626             $defaultinfo = NULL;
3627         }
3629         $context = (object) [
3630             'id' => $this->get_id(),
3631             'name' => $this->get_full_name(),
3632             'hours' => array_map(function($i) use ($data) {
3633                 return [
3634                     'value' => $i,
3635                     'name' => $i,
3636                     'selected' => $i == $data['h']
3637                 ];
3638             }, range(0, 23)),
3639             'minutes' => array_map(function($i) use ($data) {
3640                 return [
3641                     'value' => $i,
3642                     'name' => $i,
3643                     'selected' => $i == $data['m']
3644                 ];
3645             }, range(0, 59, 5))
3646         ];
3648         $element = $OUTPUT->render_from_template('core_admin/setting_configtime', $context);
3650         return format_admin_setting($this, $this->visiblename, $element, $this->description,
3651             $this->get_id() . 'h', '', $defaultinfo, $query);
3652     }
3657 /**
3658  * Seconds duration setting.
3659  *
3660  * @copyright 2012 Petr Skoda (http://skodak.org)
3661  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3662  */
3663 class admin_setting_configduration extends admin_setting {
3665     /** @var int default duration unit */
3666     protected $defaultunit;
3668     /**
3669      * Constructor
3670      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
3671      *                     or 'myplugin/mysetting' for ones in config_plugins.
3672      * @param string $visiblename localised name
3673      * @param string $description localised long description
3674      * @param mixed $defaultsetting string or array depending on implementation
3675      * @param int $defaultunit - day, week, etc. (in seconds)
3676      */
3677     public function __construct($name, $visiblename, $description, $defaultsetting, $defaultunit = 86400) {
3678         if (is_number($defaultsetting)) {
3679             $defaultsetting = self::parse_seconds($defaultsetting);
3680         }
3681         $u