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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body