[Summary view]

Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]

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