[Summary view]

Differences Between: [Versions 310 and 402] [Versions 310 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   * The class \core\update\api is defined here.
  19   *
  20   * @package     core
  21   * @copyright   2015 David Mudrak <david@moodle.com>
  22   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core\update;
  26  
  27  use curl;
  28  
  29  defined('MOODLE_INTERNAL') || die();
  30  
  31  require_once($CFG->libdir.'/filelib.php');
  32  
  33  /**
  34   * General purpose client for https://download.moodle.org/api/
  35   *
  36   * The API provides proxy access to public information about plugins available
  37   * in the Moodle Plugins directory. It is used when we are checking for
  38   * updates, resolving missing dependecies or installing a plugin. This client
  39   * can be used to:
  40   *
  41   * - obtain information about particular plugin version
  42   * - locate the most suitable plugin version for the given Moodle branch
  43   *
  44   * TODO:
  45   *
  46   * - Convert \core\update\checker to use this client too, so that we have a
  47   *   single access point for all the API services.
  48   * - Implement client method for pluglist.php even if it is not actually
  49   *   used by the Moodle core.
  50   *
  51   * @copyright 2015 David Mudrak <david@moodle.com>
  52   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  53   */
  54  class api {
  55  
  56      /** The root of the standard API provider */
  57      const APIROOT = 'https://download.moodle.org/api';
  58  
  59      /** The API version to be used by this client */
  60      const APIVER = '1.3';
  61  
  62      /**
  63       * Factory method returning an instance of the class.
  64       *
  65       * @return \core\update\api client instance
  66       */
  67      public static function client() {
  68          return new static();
  69      }
  70  
  71      /**
  72       * Constructor is protected, use the factory method.
  73       */
  74      protected function __construct() {
  75      }
  76  
  77      /**
  78       * Returns info about the particular plugin version in the plugins directory.
  79       *
  80       * Uses pluginfo.php end-point to find the given plugin version in the
  81       * Moodle plugins directory. This is typically used to handle the
  82       * installation request coming from the plugins directory (aka clicking the
  83       * "Install" button there).
  84       *
  85       * If a plugin with the given component name is found, data about the
  86       * plugin are returned as an object. The ->version property of the object
  87       * contains the information about the requested plugin version.  The
  88       * ->version property is false if the requested version of the plugin was
  89       * not found (yet the plugin itself is known).
  90       *
  91       * @param string $component frankenstyle name of the plugin
  92       * @param int $version plugin version as declared via $plugin->version in its version.php
  93       * @return \core\update\remote_info|bool
  94       */
  95      public function get_plugin_info($component, $version) {
  96  
  97          $params = array(
  98              'plugin' => $component.'@'.$version,
  99              'format' => 'json',
 100          );
 101  
 102          return $this->call_pluginfo_service($params);
 103      }
 104  
 105      /**
 106       * Locate the given plugin in the plugin directory.
 107       *
 108       * Uses pluginfo.php end-point to find a plugin with the given component
 109       * name, that suits best for the given Moodle core branch. Minimal required
 110       * plugin version can be specified. This is typically used for resolving
 111       * dependencies.
 112       *
 113       * False is returned on error, or if there is no plugin with such component
 114       * name found in the plugins directory via the API.
 115       *
 116       * If a plugin with the given component name is found, data about the
 117       * plugin are returned as an object. The ->version property of the object
 118       * contains the information about the particular plugin version that
 119       * matches best the given critera. The ->version property is false if no
 120       * suitable version of the plugin was found (yet the plugin itself is
 121       * known).
 122       *
 123       * @param string $component frankenstyle name of the plugin
 124       * @param string|int $reqversion minimal required version of the plugin, defaults to ANY_VERSION
 125       * @param int $branch moodle core branch such as 29, 30, 31 etc, defaults to $CFG->branch
 126       * @return \core\update\remote_info|bool
 127       */
 128      public function find_plugin($component, $reqversion=ANY_VERSION, $branch=null) {
 129          global $CFG;
 130  
 131          $params = array(
 132              'plugin' => $component,
 133              'format' => 'json',
 134          );
 135  
 136          if ($reqversion === ANY_VERSION) {
 137              $params['minversion'] = 0;
 138          } else {
 139              $params['minversion'] = $reqversion;
 140          }
 141  
 142          if ($branch === null) {
 143              $branch = $CFG->branch;
 144          }
 145  
 146          $params['branch'] = $this->convert_branch_numbering_format($branch);
 147  
 148          return $this->call_pluginfo_service($params);
 149      }
 150  
 151      /**
 152       * Makes sure the given data format match the expected output of the pluginfo service.
 153       *
 154       * Object validated by this method is guaranteed to contain all the data
 155       * provided by the pluginfo.php version this client works with (self::APIVER).
 156       *
 157       * @param stdClass $data
 158       * @return \core\update\remote_info|bool false if data are not valid, original data otherwise
 159       */
 160      public function validate_pluginfo_format($data) {
 161  
 162          if (empty($data) or !is_object($data)) {
 163              return false;
 164          }
 165  
 166          $output = new remote_info();
 167  
 168          $rootproperties = array('id' => 1, 'name' => 1, 'component' => 1, 'source' => 0, 'doc' => 0,
 169              'bugs' => 0, 'discussion' => 0, 'version' => 0);
 170          foreach ($rootproperties as $property => $required) {
 171              if (!property_exists($data, $property)) {
 172                  return false;
 173              }
 174              if ($required and empty($data->$property)) {
 175                  return false;
 176              }
 177              $output->$property = $data->$property;
 178          }
 179  
 180          if (!empty($data->version)) {
 181              if (!is_object($data->version)) {
 182                  return false;
 183              }
 184              $versionproperties = array('id' => 1, 'version' => 1, 'release' => 0, 'maturity' => 0,
 185                  'downloadurl' => 1, 'downloadmd5' => 1, 'vcssystem' => 0, 'vcssystemother' => 0,
 186                  'vcsrepositoryurl' => 0, 'vcsbranch' => 0, 'vcstag' => 0, 'supportedmoodles' => 0);
 187              foreach ($versionproperties as $property => $required) {
 188                  if (!property_exists($data->version, $property)) {
 189                      return false;
 190                  }
 191                  if ($required and empty($data->version->$property)) {
 192                      return false;
 193                  }
 194              }
 195              if (!preg_match('|^https?://|i', $data->version->downloadurl)) {
 196                  return false;
 197              }
 198  
 199              if (!empty($data->version->supportedmoodles)) {
 200                  if (!is_array($data->version->supportedmoodles)) {
 201                      return false;
 202                  }
 203                  foreach ($data->version->supportedmoodles as $supportedmoodle) {
 204                      if (!is_object($supportedmoodle)) {
 205                          return false;
 206                      }
 207                      if (empty($supportedmoodle->version) or empty($supportedmoodle->release)) {
 208                          return false;
 209                      }
 210                  }
 211              }
 212          }
 213  
 214          return $output;
 215      }
 216  
 217      /**
 218       * Calls the pluginfo.php end-point with given parameters.
 219       *
 220       * @param array $params
 221       * @return \core\update\remote_info|bool
 222       */
 223      protected function call_pluginfo_service(array $params) {
 224  
 225          $serviceurl = $this->get_serviceurl_pluginfo();
 226          $response = $this->call_service($serviceurl, $params);
 227  
 228          if ($response) {
 229              if ($response->info['http_code'] == 404) {
 230                  // There is no such plugin found in the plugins directory.
 231                  return false;
 232  
 233              } else if ($response->info['http_code'] == 200 and isset($response->data->status)
 234                      and $response->data->status === 'OK' and $response->data->apiver == self::APIVER
 235                      and isset($response->data->pluginfo)) {
 236                      return $this->validate_pluginfo_format($response->data->pluginfo);
 237  
 238              } else {
 239                  debugging('cURL: Unexpected response', DEBUG_DEVELOPER);
 240                  return false;
 241              }
 242          }
 243  
 244          return false;
 245      }
 246  
 247      /**
 248       * Calls the given end-point service with the given parameters.
 249       *
 250       * Returns false on cURL error and/or SSL verification failure. Otherwise
 251       * an object with the response, cURL info and HTTP status message is
 252       * returned.
 253       *
 254       * @param string $serviceurl
 255       * @param array $params
 256       * @return stdClass|bool
 257       */
 258      protected function call_service($serviceurl, array $params=array()) {
 259  
 260          $response = (object)array(
 261              'data' => null,
 262              'info' => null,
 263              'status' => null,
 264          );
 265  
 266          $curl = new curl();
 267  
 268          $response->data = json_decode($curl->get($serviceurl, $params, array(
 269              'CURLOPT_SSL_VERIFYHOST' => 2,
 270              'CURLOPT_SSL_VERIFYPEER' => true,
 271          )));
 272  
 273          $curlerrno = $curl->get_errno();
 274  
 275          if (!empty($curlerrno)) {
 276              debugging('cURL: Error '.$curlerrno.' when calling '.$serviceurl, DEBUG_DEVELOPER);
 277              return false;
 278          }
 279  
 280          $response->info = $curl->get_info();
 281  
 282          if (isset($response->info['ssl_verify_result']) and $response->info['ssl_verify_result'] != 0) {
 283              debugging('cURL/SSL: Unable to verify remote service response when calling '.$serviceurl, DEBUG_DEVELOPER);
 284              return false;
 285          }
 286  
 287          // The first response header with the HTTP status code and reason phrase.
 288          $response->status = array_shift($curl->response);
 289  
 290          return $response;
 291      }
 292  
 293      /**
 294       * Converts the given branch from XY format to the X.Y format
 295       *
 296       * The syntax of $CFG->branch uses the XY format that suits the Moodle docs
 297       * versioning and stable branches numbering scheme. The API at
 298       * download.moodle.org uses the X.Y numbering scheme.
 299       *
 300       * @param int $branch moodle branch in the XY format (e.g. 29, 30, 31 etc)
 301       * @return string moodle branch in the X.Y format (e.g. 2.9, 3.0, 3.1 etc)
 302       */
 303      protected function convert_branch_numbering_format($branch) {
 304  
 305          $branch = (string)$branch;
 306  
 307          if (strpos($branch, '.') === false) {
 308              $branch = substr($branch, 0, -1).'.'.substr($branch, -1);
 309          }
 310  
 311          return $branch;
 312      }
 313  
 314      /**
 315       * Returns URL of the pluginfo.php API end-point.
 316       *
 317       * @return string
 318       */
 319      protected function get_serviceurl_pluginfo() {
 320          global $CFG;
 321  
 322          if (!empty($CFG->config_php_settings['alternativepluginfoserviceurl'])) {
 323              return $CFG->config_php_settings['alternativepluginfoserviceurl'];
 324          } else {
 325              return self::APIROOT.'/'.self::APIVER.'/pluginfo.php';
 326          }
 327      }
 328  }