MDL-49329 admin: Introduce new \core\update\remote_info class
[moodle.git] / lib / classes / update / api.php
CommitLineData
48900324
DM
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
25namespace core\update;
26
27use curl;
28
29defined('MOODLE_INTERNAL') || die();
30
31require_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 */
54class 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
4f18a4e6 93 * @return \core\update\remote_info|bool
48900324
DM
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
4f18a4e6 126 * @return \core\update\remote_info|bool
48900324
DM
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
d6e38c2a
DM
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
4f18a4e6 158 * @return \core\update\remote_info|bool false if data are not valid, original data otherwise
d6e38c2a
DM
159 */
160 public function validate_pluginfo_format($data) {
161
162 if (empty($data) or !is_object($data)) {
163 return false;
164 }
165
4f18a4e6
DM
166 $output = new remote_info();
167
d6e38c2a
DM
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 }
4f18a4e6 177 $output->$property = $data->$property;
d6e38c2a
DM
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
4f18a4e6 214 return $output;
d6e38c2a
DM
215 }
216
48900324
DM
217 /**
218 * Calls the pluginfo.php end-point with given parameters.
219 *
220 * @param array $params
4f18a4e6 221 * @return \core\update\remote_info|bool
48900324
DM
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)
d6e38c2a
DM
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);
48900324
DM
237
238 } else {
d6e38c2a 239 debugging('cURL: Unexpected response', DEBUG_DEVELOPER);
48900324
DM
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}