MDL-49329 admin: Make core_plugin_manager better suited for unit testing
[moodle.git] / lib / classes / plugininfo / base.php
CommitLineData
e87214bd
PS
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/>.
16
17/**
18 * Defines classes used for plugin info.
19 *
20 * @package core
21 * @copyright 2011 David Mudrak <david@moodle.com>
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24namespace core\plugininfo;
25
26use core_component, core_plugin_manager, moodle_url, coding_exception;
27
28defined('MOODLE_INTERNAL') || die();
29
30
31/**
32 * Base class providing access to the information about a plugin
33 *
34 * @property-read string component the component name, type_name
35 */
36abstract class base {
37
38 /** @var string the plugintype name, eg. mod, auth or workshopform */
39 public $type;
40 /** @var string full path to the location of all the plugins of this type */
41 public $typerootdir;
42 /** @var string the plugin name, eg. assignment, ldap */
43 public $name;
44 /** @var string the localized plugin name */
45 public $displayname;
46 /** @var string the plugin source, one of core_plugin_manager::PLUGIN_SOURCE_xxx constants */
47 public $source;
48 /** @var string fullpath to the location of this plugin */
49 public $rootdir;
50 /** @var int|string the version of the plugin's source code */
51 public $versiondisk;
52 /** @var int|string the version of the installed plugin */
53 public $versiondb;
54 /** @var int|float|string required version of Moodle core */
55 public $versionrequires;
2f98f5d5
PS
56 /** @var mixed human-readable release information */
57 public $release;
e87214bd
PS
58 /** @var array other plugins that this one depends on, lazy-loaded by {@link get_other_required_plugins()} */
59 public $dependencies;
60 /** @var int number of instances of the plugin - not supported yet */
61 public $instances;
62 /** @var int order of the plugin among other plugins of the same type - not supported yet */
63 public $sortorder;
30d8bc5f 64
e87214bd 65 /** @var array|null array of {@link \core\update\info} for this plugin */
30d8bc5f 66 protected $availableupdates;
e87214bd
PS
67
68 /**
69 * Finds all enabled plugins, the result may include missing plugins.
70 * @return array|null of enabled plugins $pluginname=>$pluginname, null means unknown
71 */
72 public static function get_enabled_plugins() {
73 return null;
74 }
75
76 /**
77 * Gathers and returns the information about all plugins of the given type,
78 * either on disk or previously installed.
79 *
80 * @param string $type the name of the plugintype, eg. mod, auth or workshopform
81 * @param string $typerootdir full path to the location of the plugin dir
82 * @param string $typeclass the name of the actually called class
83 * @return array of plugintype classes, indexed by the plugin name
84 */
85 public static function get_plugins($type, $typerootdir, $typeclass) {
86 // Get the information about plugins at the disk.
87 $plugins = core_component::get_plugin_list($type);
88 $return = array();
89 foreach ($plugins as $pluginname => $pluginrootdir) {
90 $return[$pluginname] = self::make_plugin_instance($type, $typerootdir,
91 $pluginname, $pluginrootdir, $typeclass);
92 }
93
94 // Fetch missing incorrectly uninstalled plugins.
95 $manager = core_plugin_manager::instance();
96 $plugins = $manager->get_installed_plugins($type);
97
98 foreach ($plugins as $name => $version) {
99 if (isset($return[$name])) {
100 continue;
101 }
102 $plugin = new $typeclass();
103 $plugin->type = $type;
104 $plugin->typerootdir = $typerootdir;
105 $plugin->name = $name;
106 $plugin->rootdir = null;
107 $plugin->displayname = $name;
108 $plugin->versiondb = $version;
109 $plugin->init_is_standard();
110
111 $return[$name] = $plugin;
112 }
113
114 return $return;
115 }
116
117 /**
118 * Makes a new instance of the plugininfo class
119 *
120 * @param string $type the plugin type, eg. 'mod'
121 * @param string $typerootdir full path to the location of all the plugins of this type
122 * @param string $name the plugin name, eg. 'workshop'
123 * @param string $namerootdir full path to the location of the plugin
124 * @param string $typeclass the name of class that holds the info about the plugin
125 * @return base the instance of $typeclass
126 */
127 protected static function make_plugin_instance($type, $typerootdir, $name, $namerootdir, $typeclass) {
128 $plugin = new $typeclass();
129 $plugin->type = $type;
130 $plugin->typerootdir = $typerootdir;
131 $plugin->name = $name;
132 $plugin->rootdir = $namerootdir;
133
134 $plugin->init_display_name();
135 $plugin->load_disk_version();
136 $plugin->load_db_version();
137 $plugin->init_is_standard();
138
139 return $plugin;
140 }
141
142 /**
143 * Is this plugin already installed and updated?
144 * @return bool true if plugin installed and upgraded.
145 */
146 public function is_installed_and_upgraded() {
147 if (!$this->rootdir) {
148 return false;
149 }
150 if ($this->versiondb === null and $this->versiondisk === null) {
4ad70aed
DM
151 // There is no version.php or version info inside it.
152 return false;
e87214bd
PS
153 }
154
155 return ((float)$this->versiondb === (float)$this->versiondisk);
156 }
157
158 /**
159 * Sets {@link $displayname} property to a localized name of the plugin
160 */
161 public function init_display_name() {
162 if (!get_string_manager()->string_exists('pluginname', $this->component)) {
163 $this->displayname = '[pluginname,' . $this->component . ']';
164 } else {
165 $this->displayname = get_string('pluginname', $this->component);
166 }
167 }
168
169 /**
170 * Magic method getter, redirects to read only values.
171 *
172 * @param string $name
173 * @return mixed
174 */
175 public function __get($name) {
176 switch ($name) {
177 case 'component': return $this->type . '_' . $this->name;
178
179 default:
180 debugging('Invalid plugin property accessed! '.$name);
181 return null;
182 }
183 }
184
185 /**
186 * Return the full path name of a file within the plugin.
187 *
188 * No check is made to see if the file exists.
189 *
190 * @param string $relativepath e.g. 'version.php'.
191 * @return string e.g. $CFG->dirroot . '/mod/quiz/version.php'.
192 */
193 public function full_path($relativepath) {
194 if (empty($this->rootdir)) {
195 return '';
196 }
197 return $this->rootdir . '/' . $relativepath;
198 }
199
200 /**
201 * Sets {@link $versiondisk} property to a numerical value representing the
202 * version of the plugin's source code.
203 *
204 * If the value is null after calling this method, either the plugin
205 * does not use versioning (typically does not have any database
206 * data) or is missing from disk.
207 */
208 public function load_disk_version() {
209 $versions = core_plugin_manager::instance()->get_present_plugins($this->type);
210
211 $this->versiondisk = null;
212 $this->versionrequires = null;
213 $this->dependencies = array();
214
215 if (!isset($versions[$this->name])) {
216 return;
217 }
218
219 $plugin = $versions[$this->name];
220
221 if (isset($plugin->version)) {
222 $this->versiondisk = $plugin->version;
223 }
224 if (isset($plugin->requires)) {
225 $this->versionrequires = $plugin->requires;
226 }
2f98f5d5
PS
227 if (isset($plugin->release)) {
228 $this->release = $plugin->release;
229 }
e87214bd
PS
230 if (isset($plugin->dependencies)) {
231 $this->dependencies = $plugin->dependencies;
232 }
233 }
234
235 /**
236 * Get the list of other plugins that this plugin requires to be installed.
237 *
238 * @return array with keys the frankenstyle plugin name, and values either
239 * a version string (like '2011101700') or the constant ANY_VERSION.
240 */
241 public function get_other_required_plugins() {
242 if (is_null($this->dependencies)) {
243 $this->load_disk_version();
244 }
245 return $this->dependencies;
246 }
247
248 /**
249 * Is this is a subplugin?
250 *
251 * @return boolean
252 */
253 public function is_subplugin() {
254 return ($this->get_parent_plugin() !== false);
255 }
256
257 /**
258 * If I am a subplugin, return the name of my parent plugin.
259 *
260 * @return string|bool false if not a subplugin, name of the parent otherwise
261 */
262 public function get_parent_plugin() {
263 return $this->get_plugin_manager()->get_parent_of_subplugin($this->type);
264 }
265
266 /**
267 * Sets {@link $versiondb} property to a numerical value representing the
268 * currently installed version of the plugin.
269 *
270 * If the value is null after calling this method, either the plugin
271 * does not use versioning (typically does not have any database
272 * data) or has not been installed yet.
273 */
274 public function load_db_version() {
275 $versions = core_plugin_manager::instance()->get_installed_plugins($this->type);
276
277 if (isset($versions[$this->name])) {
278 $this->versiondb = $versions[$this->name];
279 } else {
280 $this->versiondb = null;
281 }
282 }
283
284 /**
285 * Sets {@link $source} property to one of core_plugin_manager::PLUGIN_SOURCE_xxx
286 * constants.
287 *
288 * If the property's value is null after calling this method, then
289 * the type of the plugin has not been recognized and you should throw
290 * an exception.
291 */
292 public function init_is_standard() {
293
294 $standard = core_plugin_manager::standard_plugins_list($this->type);
295
296 if ($standard !== false) {
297 $standard = array_flip($standard);
298 if (isset($standard[$this->name])) {
299 $this->source = core_plugin_manager::PLUGIN_SOURCE_STANDARD;
300 } else if (!is_null($this->versiondb) and is_null($this->versiondisk)
301 and core_plugin_manager::is_deleted_standard_plugin($this->type, $this->name)) {
302 $this->source = core_plugin_manager::PLUGIN_SOURCE_STANDARD; // To be deleted.
303 } else {
304 $this->source = core_plugin_manager::PLUGIN_SOURCE_EXTENSION;
305 }
306 }
307 }
308
309 /**
310 * Returns true if the plugin is shipped with the official distribution
311 * of the current Moodle version, false otherwise.
312 *
313 * @return bool
314 */
315 public function is_standard() {
316 return $this->source === core_plugin_manager::PLUGIN_SOURCE_STANDARD;
317 }
318
319 /**
320 * Returns true if the the given Moodle version is enough to run this plugin
321 *
322 * @param string|int|double $moodleversion
323 * @return bool
324 */
325 public function is_core_dependency_satisfied($moodleversion) {
326
327 if (empty($this->versionrequires)) {
328 return true;
329
330 } else {
331 return (double)$this->versionrequires <= (double)$moodleversion;
332 }
333 }
334
335 /**
336 * Returns the status of the plugin
337 *
338 * @return string one of core_plugin_manager::PLUGIN_STATUS_xxx constants
339 */
340 public function get_status() {
341
342 if (is_null($this->versiondb) and is_null($this->versiondisk)) {
343 return core_plugin_manager::PLUGIN_STATUS_NODB;
344
345 } else if (is_null($this->versiondb) and !is_null($this->versiondisk)) {
346 return core_plugin_manager::PLUGIN_STATUS_NEW;
347
348 } else if (!is_null($this->versiondb) and is_null($this->versiondisk)) {
349 if (core_plugin_manager::is_deleted_standard_plugin($this->type, $this->name)) {
350 return core_plugin_manager::PLUGIN_STATUS_DELETE;
351 } else {
352 return core_plugin_manager::PLUGIN_STATUS_MISSING;
353 }
354
355 } else if ((float)$this->versiondb === (float)$this->versiondisk) {
356 // Note: the float comparison should work fine here
357 // because there are no arithmetic operations with the numbers.
358 return core_plugin_manager::PLUGIN_STATUS_UPTODATE;
359
360 } else if ($this->versiondb < $this->versiondisk) {
361 return core_plugin_manager::PLUGIN_STATUS_UPGRADE;
362
363 } else if ($this->versiondb > $this->versiondisk) {
364 return core_plugin_manager::PLUGIN_STATUS_DOWNGRADE;
365
366 } else {
367 // $version = pi(); and similar funny jokes - hopefully Donald E. Knuth will never contribute to Moodle ;-)
368 throw new coding_exception('Unable to determine plugin state, check the plugin versions');
369 }
370 }
371
372 /**
373 * Returns the information about plugin availability
374 *
375 * True means that the plugin is enabled. False means that the plugin is
376 * disabled. Null means that the information is not available, or the
377 * plugin does not support configurable availability or the availability
378 * can not be changed.
379 *
380 * @return null|bool
381 */
382 public function is_enabled() {
383 if (!$this->rootdir) {
384 // Plugin missing.
385 return false;
386 }
387
388 $enabled = core_plugin_manager::instance()->get_enabled_plugins($this->type);
389
390 if (!is_array($enabled)) {
391 return null;
392 }
393
394 return isset($enabled[$this->name]);
395 }
396
397 /**
30d8bc5f 398 * Populates the property {@link $availableupdates}
e87214bd 399 *
30d8bc5f
DM
400 * This is supposed to be called by {@link self::available_updates()} only
401 * to lazy load the data once they are first requested.
e87214bd 402 */
30d8bc5f 403 protected function load_available_updates() {
e87214bd
PS
404 global $CFG;
405
30d8bc5f
DM
406 $provider = \core\update\checker::instance();
407
408 if (!$provider->enabled() or during_initial_install()) {
409 $this->availableupdates = array();
410 return;
411 }
412
e87214bd
PS
413 if (isset($CFG->updateminmaturity)) {
414 $minmaturity = $CFG->updateminmaturity;
415 } else {
30d8bc5f 416 // This can happen during the very first upgrade to 2.3.
e87214bd
PS
417 $minmaturity = MATURITY_STABLE;
418 }
419
420 $this->availableupdates = $provider->get_update_info($this->component,
421 array('minmaturity' => $minmaturity));
422 }
423
424 /**
425 * If there are updates for this plugin available, returns them.
426 *
427 * Returns array of {@link \core\update\info} objects, if some update
428 * is available. Returns null if there is no update available or if the update
429 * availability is unknown.
430 *
431 * @return array|null
432 */
433 public function available_updates() {
434
30d8bc5f
DM
435 if ($this->availableupdates === null) {
436 // Lazy load the information about available updates.
437 $this->load_available_updates();
438 }
439
e87214bd
PS
440 if (empty($this->availableupdates) or !is_array($this->availableupdates)) {
441 return null;
442 }
443
444 $updates = array();
445
446 foreach ($this->availableupdates as $availableupdate) {
447 if ($availableupdate->version > $this->versiondisk) {
448 $updates[] = $availableupdate;
449 }
450 }
451
452 if (empty($updates)) {
453 return null;
454 }
455
456 return $updates;
457 }
458
459 /**
460 * Returns the node name used in admin settings menu for this plugin settings (if applicable)
461 *
462 * @return null|string node name or null if plugin does not create settings node (default)
463 */
464 public function get_settings_section_name() {
465 return null;
466 }
467
468 /**
469 * Returns the URL of the plugin settings screen
470 *
471 * Null value means that the plugin either does not have the settings screen
472 * or its location is not available via this library.
473 *
474 * @return null|moodle_url
475 */
476 public function get_settings_url() {
477 $section = $this->get_settings_section_name();
478 if ($section === null) {
479 return null;
480 }
481 $settings = admin_get_root()->locate($section);
482 if ($settings && $settings instanceof \admin_settingpage) {
483 return new moodle_url('/admin/settings.php', array('section' => $section));
484 } else if ($settings && $settings instanceof \admin_externalpage) {
485 return new moodle_url($settings->url);
486 } else {
487 return null;
488 }
489 }
490
491 /**
492 * Loads plugin settings to the settings tree
493 *
494 * This function usually includes settings.php file in plugins folder.
495 * Alternatively it can create a link to some settings page (instance of admin_externalpage)
496 *
497 * @param \part_of_admin_tree $adminroot
498 * @param string $parentnodename
499 * @param bool $hassiteconfig whether the current user has moodle/site:config capability
500 */
501 public function load_settings(\part_of_admin_tree $adminroot, $parentnodename, $hassiteconfig) {
502 }
503
504 /**
505 * Should there be a way to uninstall the plugin via the administration UI.
506 *
507 * By default uninstallation is not allowed, plugin developers must enable it explicitly!
508 *
509 * @return bool
510 */
511 public function is_uninstall_allowed() {
512 return false;
513 }
514
515 /**
516 * Optional extra warning before uninstallation, for example number of uses in courses.
517 *
518 * @return string
519 */
520 public function get_uninstall_extra_warning() {
521 return '';
522 }
523
524 /**
525 * Pre-uninstall hook.
526 *
527 * This is intended for disabling of plugin, some DB table purging, etc.
528 *
529 * NOTE: to be called from uninstall_plugin() only.
530 * @private
531 */
532 public function uninstall_cleanup() {
533 // Override when extending class,
534 // do not forget to call parent::pre_uninstall_cleanup() at the end.
535 }
536
537 /**
538 * Returns relative directory of the plugin with heading '/'
539 *
540 * @return string
541 */
542 public function get_dir() {
543 global $CFG;
544
545 return substr($this->rootdir, strlen($CFG->dirroot));
546 }
547
548 /**
549 * Hook method to implement certain steps when uninstalling the plugin.
550 *
551 * This hook is called by {@link core_plugin_manager::uninstall_plugin()} so
552 * it is basically usable only for those plugin types that use the default
553 * uninstall tool provided by {@link self::get_default_uninstall_url()}.
554 *
555 * @param \progress_trace $progress traces the process
556 * @return bool true on success, false on failure
557 */
558 public function uninstall(\progress_trace $progress) {
559 return true;
560 }
561
562 /**
563 * Where should we return after plugin of this type is uninstalled?
564 * @param string $return
565 * @return moodle_url
566 */
567 public function get_return_url_after_uninstall($return) {
568 if ($return === 'manage') {
569 if ($url = $this->get_manage_url()) {
570 return $url;
571 }
572 }
573 return new moodle_url('/admin/plugins.php#plugin_type_cell_'.$this->type);
574 }
575
576 /**
577 * Return URL used for management of plugins of this type.
578 * @return moodle_url
579 */
580 public static function get_manage_url() {
581 return null;
582 }
583
584 /**
585 * Returns URL to a script that handles common plugin uninstall procedure.
586 *
587 * This URL is intended for all plugin uninstallations.
588 *
589 * @param string $return either 'overview' or 'manage'
590 * @return moodle_url
591 */
592 public final function get_default_uninstall_url($return = 'overview') {
593 return new moodle_url('/admin/plugins.php', array(
594 'sesskey' => sesskey(),
595 'uninstall' => $this->component,
596 'confirm' => 0,
597 'return' => $return,
598 ));
599 }
600
601 /**
602 * Provides access to the core_plugin_manager singleton.
603 *
604 * @return core_plugin_manager
605 */
606 protected function get_plugin_manager() {
607 return core_plugin_manager::instance();
608 }
609}