MDL-49329 admin: Fix reported coding style warnings
[moodle.git] / lib / classes / update / validator.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  * Provides validation class to check the plugin ZIP contents
19  *
20  * Uses fragments of the local_plugins_archive_validator class copyrighted by
21  * Marina Glancy that is part of the local_plugins plugin.
22  *
23  * @package     core_plugin
24  * @subpackage  validation
25  * @copyright   2013, 2015 David Mudrak <david@moodle.com>
26  * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
29 namespace core\update;
31 use core_component;
32 use core_plugin_manager;
33 use help_icon;
34 use coding_exception;
36 defined('MOODLE_INTERNAL') || die();
38 if (!defined('T_ML_COMMENT')) {
39     define('T_ML_COMMENT', T_COMMENT);
40 } else {
41     define('T_DOC_COMMENT', T_ML_COMMENT);
42 }
44 /**
45  * Validates the contents of extracted plugin ZIP file
46  *
47  * @copyright 2013, 2015 David Mudrak <david@moodle.com>
48  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
49  */
50 class validator {
52     /** Critical error message level, causes the validation fail. */
53     const ERROR     = 'error';
55     /** Warning message level, validation does not fail but the admin should be always informed. */
56     const WARNING   = 'warning';
58     /** Information message level that the admin should be aware of. */
59     const INFO      = 'info';
61     /** Debugging message level, should be displayed in debugging mode only. */
62     const DEBUG     = 'debug';
64     /** @var string full path to the extracted ZIP contents */
65     protected $extractdir = null;
67     /** @var array as returned by {@link zip_packer::extract_to_pathname()} */
68     protected $extractfiles = null;
70     /** @var bool overall result of validation */
71     protected $result = null;
73     /** @var string the name of the plugin root directory */
74     protected $rootdir = null;
76     /** @var array explicit list of expected/required characteristics of the ZIP */
77     protected $assertions = null;
79     /** @var array of validation log messages */
80     protected $messages = array();
82     /** @var array|null array of relevant data obtained from version.php */
83     protected $versionphp = null;
85     /** @var string|null the name of found English language file without the .php extension */
86     protected $langfilename = null;
88     /**
89      * Factory method returning instance of the validator
90      *
91      * @param string $zipcontentpath full path to the extracted ZIP contents
92      * @param array $zipcontentfiles (string)filerelpath => (bool|string)true or error
93      * @return \core\update\validator
94      */
95     public static function instance($zipcontentpath, array $zipcontentfiles) {
96         return new static($zipcontentpath, $zipcontentfiles);
97     }
99     /**
100      * Set the expected plugin type, fail the validation otherwise
101      *
102      * @param string $required plugin type
103      */
104     public function assert_plugin_type($required) {
105         $this->assertions['plugintype'] = $required;
106     }
108     /**
109      * Set the expectation that the plugin can be installed into the given Moodle version
110      *
111      * @param string $required Moodle version we are about to install to
112      */
113     public function assert_moodle_version($required) {
114         $this->assertions['moodleversion'] = $required;
115     }
117     /**
118      * Execute the validation process against all explicit and implicit requirements
119      *
120      * Returns true if the validation passes (all explicit and implicit requirements
121      * pass) and the plugin can be installed. Returns false if the validation fails
122      * (some explicit or implicit requirement fails) and the plugin must not be
123      * installed.
124      *
125      * @return bool
126      */
127     public function execute() {
129         $this->result = (
130                 $this->validate_files_layout()
131             and $this->validate_version_php()
132             and $this->validate_language_pack()
133             and $this->validate_target_location()
134         );
136         return $this->result;
137     }
139     /**
140      * Returns overall result of the validation.
141      *
142      * Null is returned if the validation has not been executed yet. Otherwise
143      * this method returns true (the installation can continue) or false (it is not
144      * safe to continue with the installation).
145      *
146      * @return bool|null
147      */
148     public function get_result() {
149         return $this->result;
150     }
152     /**
153      * Return the list of validation log messages
154      *
155      * Each validation message is a plain object with properties level, msgcode
156      * and addinfo.
157      *
158      * @return array of (int)index => (stdClass) validation message
159      */
160     public function get_messages() {
161         return $this->messages;
162     }
164     /**
165      * Returns human readable localised name of the given log level.
166      *
167      * @param string $level e.g. self::INFO
168      * @return string
169      */
170     public function message_level_name($level) {
171         return get_string('validationmsglevel_'.$level, 'core_plugin');
172     }
174     /**
175      * If defined, returns human readable validation code.
176      *
177      * Otherwise, it simply returns the code itself as a fallback.
178      *
179      * @param string $msgcode
180      * @return string
181      */
182     public function message_code_name($msgcode) {
184         $stringman = get_string_manager();
186         if ($stringman->string_exists('validationmsg_'.$msgcode, 'core_plugin')) {
187             return get_string('validationmsg_'.$msgcode, 'core_plugin');
188         }
190         return $msgcode;
191     }
193     /**
194      * Returns help icon for the message code if defined.
195      *
196      * @param string $msgcode
197      * @return \help_icon|false
198      */
199     public function message_help_icon($msgcode) {
201         $stringman = get_string_manager();
203         if ($stringman->string_exists('validationmsg_'.$msgcode.'_help', 'core_plugin')) {
204             return new help_icon('validationmsg_'.$msgcode, 'core_plugin');
205         }
207         return false;
208     }
210     /**
211      * Localizes the message additional info if it exists.
212      *
213      * @param string $msgcode
214      * @param array|string|null $addinfo value for the $a placeholder in the string
215      * @return string
216      */
217     public function message_code_info($msgcode, $addinfo) {
219         $stringman = get_string_manager();
221         if ($addinfo !== null and $stringman->string_exists('validationmsg_'.$msgcode.'_info', 'core_plugin')) {
222             return get_string('validationmsg_'.$msgcode.'_info', 'core_plugin', $addinfo);
223         }
225         return '';
226     }
228     /**
229      * Return the information provided by the the plugin's version.php
230      *
231      * If version.php was not found in the plugin, null is returned. Otherwise
232      * the array is returned. It may be empty if no information was parsed
233      * (which should not happen).
234      *
235      * @return null|array
236      */
237     public function get_versionphp_info() {
238         return $this->versionphp;
239     }
241     /**
242      * Returns the name of the English language file without the .php extension
243      *
244      * This can be used as a suggestion for fixing the plugin root directory in the
245      * ZIP file during the upload. If no file was found, or multiple PHP files are
246      * located in lang/en/ folder, then null is returned.
247      *
248      * @return null|string
249      */
250     public function get_language_file_name() {
251         return $this->langfilename;
252     }
254     /**
255      * Returns the rootdir of the extracted package (after eventual renaming)
256      *
257      * @return string|null
258      */
259     public function get_rootdir() {
260         return $this->rootdir;
261     }
263     // End of external API.
265     /**
266      * No public constructor, use {@link self::instance()} instead.
267      *
268      * @param string $zipcontentpath full path to the extracted ZIP contents
269      * @param array $zipcontentfiles (string)filerelpath => (bool|string)true or error
270      */
271     protected function __construct($zipcontentpath, array $zipcontentfiles) {
272         $this->extractdir = $zipcontentpath;
273         $this->extractfiles = $zipcontentfiles;
274     }
276     // Validation methods.
278     /**
279      * Returns false if files in the ZIP do not have required layout.
280      *
281      * @return bool
282      */
283     protected function validate_files_layout() {
285         if (!is_array($this->extractfiles) or count($this->extractfiles) < 4) {
286             // We need the English language pack with the name of the plugin at least.
287             $this->add_message(self::ERROR, 'filesnumber');
288             return false;
289         }
291         foreach ($this->extractfiles as $filerelname => $filestatus) {
292             if ($filestatus !== true) {
293                 $this->add_message(self::ERROR, 'filestatus', array('file' => $filerelname, 'status' => $filestatus));
294                 return false;
295             }
296         }
298         foreach (array_keys($this->extractfiles) as $filerelname) {
299             if (!file_exists($this->extractdir.'/'.$filerelname)) {
300                 $this->add_message(self::ERROR, 'filenotexists', array('file' => $filerelname));
301                 return false;
302             }
303         }
305         foreach (array_keys($this->extractfiles) as $filerelname) {
306             $matches = array();
307             if (!preg_match("#^([^/]+)/#", $filerelname, $matches)
308                     or (!is_null($this->rootdir) and $this->rootdir !== $matches[1])) {
309                 $this->add_message(self::ERROR, 'onedir');
310                 return false;
311             }
312             $this->rootdir = $matches[1];
313         }
315         if ($this->rootdir !== clean_param($this->rootdir, PARAM_PLUGIN)) {
316             $this->add_message(self::ERROR, 'rootdirinvalid', $this->rootdir);
317             return false;
318         } else {
319             $this->add_message(self::INFO, 'rootdir', $this->rootdir);
320         }
322         return is_dir($this->extractdir.'/'.$this->rootdir);
323     }
325     /**
326      * Returns false if the version.php file does not declare required information.
327      *
328      * @return bool
329      */
330     protected function validate_version_php() {
332         if (!isset($this->assertions['plugintype'])) {
333             throw new coding_exception('Required plugin type must be set before calling this');
334         }
336         if (!isset($this->assertions['moodleversion'])) {
337             throw new coding_exception('Required Moodle version must be set before calling this');
338         }
340         $fullpath = $this->extractdir.'/'.$this->rootdir.'/version.php';
342         if (!file_exists($fullpath)) {
343             // This is tolerated for themes only.
344             if ($this->assertions['plugintype'] === 'theme') {
345                 $this->add_message(self::DEBUG, 'missingversionphp');
346                 return true;
347             } else {
348                 $this->add_message(self::ERROR, 'missingversionphp');
349                 return false;
350             }
351         }
353         $this->versionphp = array();
354         $info = $this->parse_version_php($fullpath);
356         if (isset($info['module->version'])) {
357             $this->add_message(self::ERROR, 'versionphpsyntax', '$module');
358             return false;
359         }
361         if (isset($info['plugin->version'])) {
362             $this->versionphp['version'] = $info['plugin->version'];
363             $this->add_message(self::INFO, 'pluginversion', $this->versionphp['version']);
364         } else {
365             $this->add_message(self::ERROR, 'missingversion');
366             return false;
367         }
369         if (isset($info['plugin->requires'])) {
370             $this->versionphp['requires'] = $info['plugin->requires'];
371             if ($this->versionphp['requires'] > $this->assertions['moodleversion']) {
372                 $this->add_message(self::ERROR, 'requiresmoodle', $this->versionphp['requires']);
373                 return false;
374             }
375             $this->add_message(self::INFO, 'requiresmoodle', $this->versionphp['requires']);
376         }
378         if (!isset($info['plugin->component'])) {
379             $this->add_message(self::ERROR, 'missingcomponent');
380             return false;
381         }
383         $this->versionphp['component'] = $info['plugin->component'];
384         list($reqtype, $reqname) = core_component::normalize_component($this->versionphp['component']);
385         if ($reqtype !== $this->assertions['plugintype']) {
386             $this->add_message(self::ERROR, 'componentmismatchtype', array(
387                 'expected' => $this->assertions['plugintype'],
388                 'found' => $reqtype));
389             return false;
390         }
391         if ($reqname !== $this->rootdir) {
392             $this->add_message(self::ERROR, 'componentmismatchname', $reqname);
393             return false;
394         }
395         $this->add_message(self::INFO, 'componentmatch', $this->versionphp['component']);
397         if (isset($info['plugin->maturity'])) {
398             $this->versionphp['maturity'] = $info['plugin->maturity'];
399             if ($this->versionphp['maturity'] === 'MATURITY_STABLE') {
400                 $this->add_message(self::INFO, 'maturity', $this->versionphp['maturity']);
401             } else {
402                 $this->add_message(self::WARNING, 'maturity', $this->versionphp['maturity']);
403             }
404         }
406         if (isset($info['plugin->release'])) {
407             $this->versionphp['release'] = $info['plugin->release'];
408             $this->add_message(self::INFO, 'release', $this->versionphp['release']);
409         }
411         return true;
412     }
414     /**
415      * Returns false if the English language pack is not provided correctly.
416      *
417      * @return bool
418      */
419     protected function validate_language_pack() {
421         if (!isset($this->assertions['plugintype'])) {
422             throw new coding_exception('Required plugin type must be set before calling this');
423         }
425         if (!isset($this->extractfiles[$this->rootdir.'/lang/en/'])
426                 or $this->extractfiles[$this->rootdir.'/lang/en/'] !== true
427                 or !is_dir($this->extractdir.'/'.$this->rootdir.'/lang/en')) {
428             $this->add_message(self::ERROR, 'missinglangenfolder');
429             return false;
430         }
432         $langfiles = array();
433         foreach (array_keys($this->extractfiles) as $extractfile) {
434             $matches = array();
435             if (preg_match('#^'.preg_quote($this->rootdir).'/lang/en/([^/]+).php?$#i', $extractfile, $matches)) {
436                 $langfiles[] = $matches[1];
437             }
438         }
440         if (empty($langfiles)) {
441             $this->add_message(self::ERROR, 'missinglangenfile');
442             return false;
443         } else if (count($langfiles) > 1) {
444             $this->add_message(self::WARNING, 'multiplelangenfiles');
445         } else {
446             $this->langfilename = $langfiles[0];
447             $this->add_message(self::DEBUG, 'foundlangfile', $this->langfilename);
448         }
450         if ($this->assertions['plugintype'] === 'mod') {
451             $expected = $this->rootdir.'.php';
452         } else {
453             $expected = $this->assertions['plugintype'].'_'.$this->rootdir.'.php';
454         }
456         if (!isset($this->extractfiles[$this->rootdir.'/lang/en/'.$expected])
457                 or $this->extractfiles[$this->rootdir.'/lang/en/'.$expected] !== true
458                 or !is_file($this->extractdir.'/'.$this->rootdir.'/lang/en/'.$expected)) {
459             $this->add_message(self::ERROR, 'missingexpectedlangenfile', $expected);
460             return false;
461         }
463         return true;
464     }
466     /**
467      * Returns false of the given add-on can't be installed into its location.
468      *
469      * @return bool
470      */
471     public function validate_target_location() {
473         if (!isset($this->assertions['plugintype'])) {
474             throw new coding_exception('Required plugin type must be set before calling this');
475         }
477         $plugintypepath = $this->get_plugintype_location($this->assertions['plugintype']);
479         if (is_null($plugintypepath)) {
480             $this->add_message(self::ERROR, 'unknowntype', $this->assertions['plugintype']);
481             return false;
482         }
484         if (!is_dir($plugintypepath)) {
485             throw new coding_exception('Plugin type location does not exist!');
486         }
488         // Always check that the plugintype root is writable.
489         if (!is_writable($plugintypepath)) {
490             $this->add_message(self::ERROR, 'pathwritable', $plugintypepath);
491             return false;
492         } else {
493             $this->add_message(self::INFO, 'pathwritable', $plugintypepath);
494         }
496         // The target location itself may or may not exist. Even if installing an
497         // available update, the code could have been removed by accident (and
498         // be reported as missing) etc. So we just make sure that the code
499         // can be replaced if it already exists.
500         $target = $plugintypepath.'/'.$this->rootdir;
501         if (file_exists($target)) {
502             if (!is_dir($target)) {
503                 $this->add_message(self::ERROR, 'targetnotdir', $target);
504                 return false;
505             }
506             $this->add_message(self::WARNING, 'targetexists', $target);
507             if ($this->get_plugin_manager()->is_directory_removable($target)) {
508                 $this->add_message(self::INFO, 'pathwritable', $target);
509             } else {
510                 $this->add_message(self::ERROR, 'pathwritable', $target);
511                 return false;
512             }
513         }
515         return true;
516     }
518     // Helper methods.
520     /**
521      * Get as much information from existing version.php as possible
522      *
523      * @param string $fullpath full path to the version.php file
524      * @return array of found meta-info declarations
525      */
526     protected function parse_version_php($fullpath) {
528         $content = $this->get_stripped_file_contents($fullpath);
530         preg_match_all('#\$((plugin|module)\->(version|maturity|release|requires))=()(\d+(\.\d+)?);#m', $content, $matches1);
531         preg_match_all('#\$((plugin|module)\->(maturity))=()(MATURITY_\w+);#m', $content, $matches2);
532         preg_match_all('#\$((plugin|module)\->(release))=([\'"])(.*?)\4;#m', $content, $matches3);
533         preg_match_all('#\$((plugin|module)\->(component))=([\'"])(.+?_.+?)\4;#m', $content, $matches4);
535         if (count($matches1[1]) + count($matches2[1]) + count($matches3[1]) + count($matches4[1])) {
536             $info = array_combine(
537                 array_merge($matches1[1], $matches2[1], $matches3[1], $matches4[1]),
538                 array_merge($matches1[5], $matches2[5], $matches3[5], $matches4[5])
539             );
541         } else {
542             $info = array();
543         }
545         return $info;
546     }
548     /**
549      * Append the given message to the messages log
550      *
551      * @param string $level e.g. self::ERROR
552      * @param string $msgcode may form a string
553      * @param string|array|object $a optional additional info suitable for {@link get_string()}
554      */
555     protected function add_message($level, $msgcode, $a = null) {
556         $msg = (object)array(
557             'level'     => $level,
558             'msgcode'   => $msgcode,
559             'addinfo'   => $a,
560         );
561         $this->messages[] = $msg;
562     }
564     /**
565      * Returns bare PHP code from the given file
566      *
567      * Returns contents without PHP opening and closing tags, text outside php code,
568      * comments and extra whitespaces.
569      *
570      * @param string $fullpath full path to the file
571      * @return string
572      */
573     protected function get_stripped_file_contents($fullpath) {
575         $source = file_get_contents($fullpath);
576         $tokens = token_get_all($source);
577         $output = '';
578         $doprocess = false;
579         foreach ($tokens as $token) {
580             if (is_string($token)) {
581                 // Simple one character token.
582                 $id = -1;
583                 $text = $token;
584             } else {
585                 // Token array.
586                 list($id, $text) = $token;
587             }
588             switch ($id) {
589                 case T_WHITESPACE:
590                 case T_COMMENT:
591                 case T_ML_COMMENT:
592                 case T_DOC_COMMENT:
593                     // Ignore whitespaces, inline comments, multiline comments and docblocks.
594                     break;
595                 case T_OPEN_TAG:
596                     // Start processing.
597                     $doprocess = true;
598                     break;
599                 case T_CLOSE_TAG:
600                     // Stop processing.
601                     $doprocess = false;
602                     break;
603                 default:
604                     // Anything else is within PHP tags, return it as is.
605                     if ($doprocess) {
606                         $output .= $text;
607                         if ($text === 'function') {
608                             // Explicitly keep the whitespace that would be ignored.
609                             $output .= ' ';
610                         }
611                     }
612                     break;
613             }
614         }
616         return $output;
617     }
619     /**
620      * Returns the full path to the root directory of the given plugin type.
621      *
622      * @param string $plugintype
623      * @return string|null
624      */
625     public function get_plugintype_location($plugintype) {
626         return $this->get_plugin_manager()->get_plugintype_root($plugintype);
627     }
629     /**
630      * Returns plugin manager to use.
631      *
632      * @return core_plugin_manager
633      */
634     protected function get_plugin_manager() {
635         return core_plugin_manager::instance();
636     }