MDL-49329 admin: Introduce new \core\update\remote_info class
[moodle.git] / lib / classes / update / api.php
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/>.
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  */
25 namespace core\update;
27 use curl;
29 defined('MOODLE_INTERNAL') || die();
31 require_once($CFG->libdir.'/filelib.php');
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 {
56     /** The root of the standard API provider */
57     const APIROOT = 'https://download.moodle.org/api';
59     /** The API version to be used by this client */
60     const APIVER = '1.3';
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     }
71     /**
72      * Constructor is protected, use the factory method.
73      */
74     protected function __construct() {
75     }
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) {
97         $params = array(
98             'plugin' => $component.'@'.$version,
99             'format' => 'json',
100         );
102         return $this->call_pluginfo_service($params);
103     }
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;
131         $params = array(
132             'plugin' => $component,
133             'format' => 'json',
134         );
136         if ($reqversion === ANY_VERSION) {
137             $params['minversion'] = 0;
138         } else {
139             $params['minversion'] = $reqversion;
140         }
142         if ($branch === null) {
143             $branch = $CFG->branch;
144         }
146         $params['branch'] = $this->convert_branch_numbering_format($branch);
148         return $this->call_pluginfo_service($params);
149     }
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) {
162         if (empty($data) or !is_object($data)) {
163             return false;
164         }
166         $output = new remote_info();
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         }
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             }
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         }
214         return $output;
215     }
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) {
225         $serviceurl = $this->get_serviceurl_pluginfo();
226         $response = $this->call_service($serviceurl, $params);
228         if ($response) {
229             if ($response->info['http_code'] == 404) {
230                 // There is no such plugin found in the plugins directory.
231                 return false;
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);
238             } else {
239                 debugging('cURL: Unexpected response', DEBUG_DEVELOPER);
240                 return false;
241             }
242         }
244         return false;
245     }
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()) {
260         $response = (object)array(
261             'data' => null,
262             'info' => null,
263             'status' => null,
264         );
266         $curl = new curl();
268         $response->data = json_decode($curl->get($serviceurl, $params, array(
269             'CURLOPT_SSL_VERIFYHOST' => 2,
270             'CURLOPT_SSL_VERIFYPEER' => true,
271         )));
273         $curlerrno = $curl->get_errno();
275         if (!empty($curlerrno)) {
276             debugging('cURL: Error '.$curlerrno.' when calling '.$serviceurl, DEBUG_DEVELOPER);
277             return false;
278         }
280         $response->info = $curl->get_info();
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         }
287         // The first response header with the HTTP status code and reason phrase.
288         $response->status = array_shift($curl->response);
290         return $response;
291     }
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) {
305         $branch = (string)$branch;
307         if (strpos($branch, '.') === false) {
308             $branch = substr($branch, 0, -1).'.'.substr($branch, -1);
309         }
311         return $branch;
312     }
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;
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     }