3 // This file is part of Moodle - http://moodle.org/
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU General Public License for more details.
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
19 * This library includes all the necessary stuff to use the one-click
20 * download and install feature of Moodle, used to keep updated some
21 * items like languages, pear, enviroment... i.e, components.
23 * It has been developed harcoding some important limits that are
25 * - It only can check, download and install items under moodledata.
26 * - Every downloadeable item must be one zip file.
27 * - The zip file root content must be 1 directory, i.e, everything
28 * is stored under 1 directory.
29 * - Zip file name and root directory must have the same name (but
30 * the .zip extension, of course).
31 * - Every .zip file must be defined in one .md5 file that will be
32 * stored in the same remote directory than the .zip file.
33 * - The name of such .md5 file is free, although it's recommended
34 * to use the same name than the .zip (that's the default
35 * assumption if no specified).
36 * - Every remote .md5 file will be a comma separated (CVS) file where each
37 * line will follow this format:
38 * - Field 1: name of the zip file (without extension). Mandatory.
39 * - Field 2: md5 of the zip file. Mandatory.
40 * - Field 3: whatever you want (or need). Optional.
41 * -Every local .md5 file will:
42 * - Have the zip file name (without the extension) plus -md5
43 * - Will reside inside the expanded zip file dir
44 * - Will contain the md5 od the latest installed component
45 * With all these details present, the process will perform this tasks:
46 * - Perform security checks. Only admins are allowed to use this for now.
47 * - Read the .md5 file from source (1).
48 * - Extract the correct line for the .zip being requested.
49 * - Compare it with the local .md5 file (2).
51 * - Download the newer .zip file from source.
52 * - Calculate its md5 (3).
53 * - Compare (1) and (3).
55 * - Delete old directory.
56 * - Uunzip the newer .zip file.
57 * - Create the new local .md5 file.
58 * - Delete the .zip file.
60 * - ERROR. Old package won't be modified. We shouldn't
62 * - If component download is not possible, a message text about how to do
63 * the process manually (remotedownloaderror) must be displayed to explain it.
67 * To install one component:
69 * require_once($CFG->libdir.'/componentlib.class.php');
70 * if ($cd = new component_installer('https://download.moodle.org', 'langpack/2.0',
71 * 'es.zip', 'languages.md5', 'lang')) {
72 * $status = $cd->install(); //returns COMPONENT_(ERROR | UPTODATE | INSTALLED)
74 * case COMPONENT_ERROR:
75 * if ($cd->get_error() == 'remotedownloaderror') {
76 * $a = new stdClass();
77 * $a->url = 'https://download.moodle.org/langpack/2.0/es.zip';
78 * $a->dest= $CFG->dataroot.'/lang';
79 * print_error($cd->get_error(), 'error', '', $a);
81 * print_error($cd->get_error(), 'error');
84 * case COMPONENT_UPTODATE:
85 * //Print error string or whatever you want to do
87 * case COMPONENT_INSTALLED:
88 * //Print/do whatever you want
91 * //We shouldn't reach this point
94 * //We shouldn't reach this point
98 * To switch of component (maintaining the rest of settings):
100 * $status = $cd->change_zip_file('en.zip'); //returns boolean false on error
103 * To retrieve all the components in one remote md5 file
105 * $components = $cd->get_all_components_md5(); //returns boolean false on error, array instead
108 * To check if current component needs to be updated
110 * $status = $cd->need_upgrade(); //returns COMPONENT_(ERROR | UPTODATE | NEEDUPDATE)
113 * To get the 3rd field of the md5 file (optional)
115 * $field = $cd->get_extra_md5_field(); //returns string (empty if not exists)
118 * For all the error situations the $cd->get_error() method should return always the key of the
119 * error to be retrieved by one standard get_string() call against the error.php lang file.
124 * @copyright (C) 2001-3001 Eloy Lafuente (stronk7) {@link http://contiento.com}
125 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
128 defined('MOODLE_INTERNAL') ||
die();
131 * @global object $CFG
135 require_once($CFG->libdir
.'/filelib.php');
137 // Some needed constants
138 define('COMPONENT_ERROR', 0);
139 define('COMPONENT_UPTODATE', 1);
140 define('COMPONENT_NEEDUPDATE', 2);
141 define('COMPONENT_INSTALLED', 3);
144 * This class is used to check, download and install items from
145 * download.moodle.org to the moodledata directory.
147 * It always return true/false in all their public methods to say if
148 * execution has ended succesfuly or not. If there is any problem
149 * its getError() method can be called, returning one error string
150 * to be used with the standard get/print_string() functions.
152 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
153 * @package moodlecore
155 class component_installer
{
159 var $sourcebase; /// Full http URL, base for downloadable items
160 var $zippath; /// Relative path (from sourcebase) where the
161 /// downloadeable item resides.
162 var $zipfilename; /// Name of the .zip file to be downloaded
163 var $md5filename; /// Name of the .md5 file to be read
164 var $componentname;/// Name of the component. Must be the zip name without
165 /// the extension. And it defines a lot of things:
166 /// the md5 line to search for, the default m5 file name
167 /// and the name of the root dir stored inside the zip file
168 var $destpath; /// Relative path (from moodledata) where the .zip
169 /// file will be expanded.
170 var $errorstring; /// Latest error produced. It will contain one lang string key.
171 var $extramd5info; /// Contents of the optional third field in the .md5 file.
172 var $requisitesok; /// Flag to see if requisites check has been passed ok.
176 var $cachedmd5components; /// Array of cached components to avoid to
177 /// download the same md5 file more than once per request.
180 * Standard constructor of the class. It will initialize all attributes.
181 * without performing any check at all.
183 * @param string $sourcebase Full http URL, base for downloadeable items
184 * @param string $zippath Relative path (from sourcebase) where the
185 * downloadeable item resides
186 * @param string $zipfilename Name of the .zip file to be downloaded
187 * @param string $md5filename Name of the .md5 file to be read (default '' = same
189 * @param string $destpath Relative path (from moodledata) where the .zip file will
190 * be expanded (default='' = moodledataitself)
193 public function __construct($sourcebase, $zippath, $zipfilename, $md5filename='', $destpath='') {
195 $this->sourcebase
= $sourcebase;
196 $this->zippath
= $zippath;
197 $this->zipfilename
= $zipfilename;
198 $this->md5filename
= $md5filename;
199 $this->componentname
= '';
200 $this->destpath
= $destpath;
201 $this->errorstring
= '';
202 $this->extramd5info
= '';
203 $this->requisitesok
= false;
204 $this->cachedmd5components
= array();
206 $this->check_requisites();
210 * Old syntax of class constructor. Deprecated in PHP7.
212 * @deprecated since Moodle 3.1
214 public function component_installer($sourcebase, $zippath, $zipfilename, $md5filename='', $destpath='') {
215 debugging('Use of class name as constructor is deprecated', DEBUG_DEVELOPER
);
216 self
::__construct($sourcebase, $zippath, $zipfilename, $md5filename, $destpath);
220 * This function will check if everything is properly set to begin
221 * one installation. Also, it will check for required settings
222 * and will fill everything as needed.
225 * @return boolean true/false (plus detailed error in errorstring)
227 function check_requisites() {
230 $this->requisitesok
= false;
232 /// Check that everything we need is present
233 if (empty($this->sourcebase
) ||
empty($this->zipfilename
)) {
234 $this->errorstring
='missingrequiredfield';
237 /// Check for correct sourcebase (this will be out in the future)
238 if (!PHPUNIT_TEST
and $this->sourcebase
!= 'https://download.moodle.org') {
239 $this->errorstring
='wrongsourcebase';
242 /// Check the zip file is a correct one (by extension)
243 if (stripos($this->zipfilename
, '.zip') === false) {
244 $this->errorstring
='wrongzipfilename';
247 /// Check that exists under dataroot
248 if (!empty($this->destpath
)) {
249 if (!file_exists($CFG->dataroot
.'/'.$this->destpath
)) {
250 $this->errorstring
='wrongdestpath';
254 /// Calculate the componentname
255 $pos = stripos($this->zipfilename
, '.zip');
256 $this->componentname
= substr($this->zipfilename
, 0, $pos);
257 /// Calculate md5filename if it's empty
258 if (empty($this->md5filename
)) {
259 $this->md5filename
= $this->componentname
.'.md5';
261 /// Set the requisites passed flag
262 $this->requisitesok
= true;
267 * This function will perform the full installation if needed, i.e.
268 * compare md5 values, download, unzip, install and regenerate
272 * @uses COMPONENT_ERROR
273 * @uses COMPONENT_UPTODATE
274 * @uses COMPONENT_ERROR
275 * @uses COMPONENT_INSTALLED
276 * @return int COMPONENT_(ERROR | UPTODATE | INSTALLED)
282 /// Check requisites are passed
283 if (!$this->requisitesok
) {
284 return COMPONENT_ERROR
;
286 /// Confirm we need upgrade
287 if ($this->need_upgrade() === COMPONENT_ERROR
) {
288 return COMPONENT_ERROR
;
289 } else if ($this->need_upgrade() === COMPONENT_UPTODATE
) {
290 $this->errorstring
='componentisuptodate';
291 return COMPONENT_UPTODATE
;
293 /// Create temp directory if necesary
294 if (!make_temp_directory('', false)) {
295 $this->errorstring
='cannotcreatetempdir';
296 return COMPONENT_ERROR
;
298 /// Download zip file and save it to temp
299 if ($this->zippath
) {
300 $source = $this->sourcebase
.'/'.$this->zippath
.'/'.$this->zipfilename
;
302 $source = $this->sourcebase
.'/'.$this->zipfilename
;
305 $zipfile= $CFG->tempdir
.'/'.$this->zipfilename
;
307 if($contents = download_file_content($source)) {
308 if ($file = fopen($zipfile, 'w')) {
309 if (!fwrite($file, $contents)) {
311 $this->errorstring
='cannotsavezipfile';
312 return COMPONENT_ERROR
;
315 $this->errorstring
='cannotsavezipfile';
316 return COMPONENT_ERROR
;
320 $this->errorstring
='cannotdownloadzipfile';
321 return COMPONENT_ERROR
;
323 /// Calculate its md5
324 $new_md5 = md5($contents);
325 /// Compare it with the remote md5 to check if we have the correct zip file
326 if (!$remote_md5 = $this->get_component_md5()) {
327 return COMPONENT_ERROR
;
329 if ($new_md5 != $remote_md5) {
330 $this->errorstring
='downloadedfilecheckfailed';
331 return COMPONENT_ERROR
;
333 /// Move current revision to a safe place
334 $destinationdir = $CFG->dataroot
.'/'.$this->destpath
;
335 $destinationcomponent = $destinationdir.'/'.$this->componentname
;
336 @remove_dir
($destinationcomponent.'_old'); // Deleting a possible old version.
338 // Moving to a safe place.
339 @rename
($destinationcomponent, $destinationcomponent.'_old');
341 /// Unzip new version
342 if (!unzip_file($zipfile, $destinationdir, false)) {
343 /// Error so, go back to the older
344 @remove_dir
($destinationcomponent);
345 @rename
($destinationcomponent.'_old', $destinationcomponent);
346 $this->errorstring
='cannotunzipfile';
347 return COMPONENT_ERROR
;
349 /// Delete old component version
350 @remove_dir
($destinationcomponent.'_old');
352 if ($file = fopen($destinationcomponent.'/'.$this->componentname
.'.md5', 'w')) {
353 if (!fwrite($file, $new_md5)) {
355 $this->errorstring
='cannotsavemd5file';
356 return COMPONENT_ERROR
;
359 $this->errorstring
='cannotsavemd5file';
360 return COMPONENT_ERROR
;
363 /// Delete temp zip file
366 return COMPONENT_INSTALLED
;
370 * This function will detect if remote component needs to be installed
371 * because it's different from the local one
373 * @uses COMPONENT_ERROR
374 * @uses COMPONENT_UPTODATE
375 * @uses COMPONENT_NEEDUPDATE
376 * @return int COMPONENT_(ERROR | UPTODATE | NEEDUPDATE)
378 function need_upgrade() {
380 /// Check requisites are passed
381 if (!$this->requisitesok
) {
382 return COMPONENT_ERROR
;
385 $local_md5 = $this->get_local_md5();
387 if (!$remote_md5 = $this->get_component_md5()) {
388 return COMPONENT_ERROR
;
391 if ($local_md5 == $remote_md5) {
392 return COMPONENT_UPTODATE
;
394 return COMPONENT_NEEDUPDATE
;
399 * This function will change the zip file to install on the fly
400 * to allow the class to process different components of the
401 * same md5 file without intantiating more objects.
403 * @param string $newzipfilename New zip filename to process
404 * @return boolean true/false
406 function change_zip_file($newzipfilename) {
408 $this->zipfilename
= $newzipfilename;
409 return $this->check_requisites();
413 * This function will get the local md5 value of the installed
417 * @return bool|string md5 of the local component (false on error)
419 function get_local_md5() {
422 /// Check requisites are passed
423 if (!$this->requisitesok
) {
427 $return_value = 'needtobeinstalled'; /// Fake value to force new installation
429 /// Calculate source to read
430 $source = $CFG->dataroot
.'/'.$this->destpath
.'/'.$this->componentname
.'/'.$this->componentname
.'.md5';
431 /// Read md5 value stored (if exists)
432 if (file_exists($source)) {
433 if ($temp = file_get_contents($source)) {
434 $return_value = $temp;
437 return $return_value;
441 * This function will download the specified md5 file, looking for the
442 * current componentname, returning its md5 field and storing extramd5info
443 * if present. Also it caches results to cachedmd5components for better
444 * performance in the same request.
446 * @return mixed md5 present in server (or false if error)
448 function get_component_md5() {
450 /// Check requisites are passed
451 if (!$this->requisitesok
) {
454 /// Get all components of md5 file
455 if (!$comp_arr = $this->get_all_components_md5()) {
456 if (empty($this->errorstring
)) {
457 $this->errorstring
='cannotdownloadcomponents';
461 /// Search for the componentname component
462 if (empty($comp_arr[$this->componentname
]) ||
!$component = $comp_arr[$this->componentname
]) {
463 $this->errorstring
='cannotfindcomponent';
466 /// Check we have a valid md5
467 if (empty($component[1]) ||
strlen($component[1]) != 32) {
468 $this->errorstring
='invalidmd5';
471 /// Set the extramd5info field
472 if (!empty($component[2])) {
473 $this->extramd5info
= $component[2];
475 return $component[1];
479 * This function allows you to retrieve the complete array of components found in
482 * @return bool|array array of components in md5 file or false if error
484 function get_all_components_md5() {
486 /// Check requisites are passed
487 if (!$this->requisitesok
) {
491 /// Initialize components array
494 /// Define and retrieve the full md5 file
495 if ($this->zippath
) {
496 $source = $this->sourcebase
.'/'.$this->zippath
.'/'.$this->md5filename
;
498 $source = $this->sourcebase
.'/'.$this->md5filename
;
501 /// Check if we have downloaded the md5 file before (per request cache)
502 if (!empty($this->cachedmd5components
[$source])) {
503 $comp_arr = $this->cachedmd5components
[$source];
505 /// Not downloaded, let's do it now
506 $availablecomponents = array();
508 if ($contents = download_file_content($source)) {
509 /// Split text into lines
510 $lines=preg_split('/\r?\n/',$contents);
511 /// Each line will be one component
512 foreach($lines as $line) {
513 $availablecomponents[] = explode(',', $line);
515 /// If no components have been found, return error
516 if (empty($availablecomponents)) {
517 $this->errorstring
='cannotdownloadcomponents';
520 /// Build an associative array of components for easily search
521 /// applying trim to avoid linefeeds and other...
523 foreach ($availablecomponents as $component) {
524 /// Avoid sometimes empty lines
525 if (empty($component[0])) {
528 $component[0]=trim($component[0]);
529 if (!empty($component[1])) {
530 $component[1]=trim($component[1]);
532 if (!empty($component[2])) {
533 $component[2]=trim($component[2]);
535 $comp_arr[$component[0]] = $component;
538 $this->cachedmd5components
[$source] = $comp_arr;
541 $this->errorstring
='remotedownloaderror';
545 /// If there is no commponents or erros found, error
546 if (!empty($this->errorstring
)) {
549 } else if (empty($comp_arr)) {
550 $this->errorstring
='cannotdownloadcomponents';
557 * This function returns the errorstring
559 * @return string the error string
561 function get_error() {
562 return $this->errorstring
;
565 /** This function returns the extramd5 field (optional in md5 file)
567 * @return string the extramd5 field
569 function get_extra_md5_field() {
570 return $this->extramd5info
;
573 } /// End of component_installer class
577 * Language packs installer
579 * This class wraps the functionality provided by {@link component_installer}
580 * and adds support for installing a set of language packs.
582 * Given an array of required language packs, this class fetches them all
583 * and installs them. It detects eventual dependencies and installs
584 * all parent languages, too.
586 * @copyright 2011 David Mudrak <david@moodle.com>
587 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
589 class lang_installer
{
591 /** lang pack was successfully downloaded and deployed */
592 const RESULT_INSTALLED
= 'installed';
593 /** lang pack was up-to-date so no download was needed */
594 const RESULT_UPTODATE
= 'uptodate';
595 /** there was a problem with downloading the lang pack */
596 const RESULT_DOWNLOADERROR
= 'downloaderror';
598 /** @var array of languages to install */
599 protected $queue = array();
600 /** @var string the code of language being currently installed */
602 /** @var array of languages already installed by this instance */
603 protected $done = array();
604 /** @var string this Moodle major version */
608 * Prepare the installer
610 * @param string|array $langcode a code of the language to install
612 public function __construct($langcode = '') {
615 $this->set_queue($langcode);
616 $this->version
= moodle_major_version(true);
618 if (!empty($CFG->langotherroot
) and $CFG->langotherroot
!== $CFG->dataroot
. '/lang') {
619 debugging('The in-built language pack installer does not support alternative location ' .
620 'of languages root directory. You are supposed to install and update your language '.
621 'packs on your own.');
626 * Sets the queue of language packs to be installed
628 * @param string|array $langcodes language code like 'cs' or a list of them
630 public function set_queue($langcodes) {
631 if (is_array($langcodes)) {
632 $this->queue
= $langcodes;
633 } else if (!empty($langcodes)) {
634 $this->queue
= array($langcodes);
641 * This method calls {@link self::install_language_pack} for every language in the
642 * queue. If a dependency is detected, the parent language is added to the queue.
644 * @return array results, array of self::RESULT_xxx constants indexed by language code
646 public function run() {
650 while ($this->current
= array_shift($this->queue
)) {
652 if ($this->was_processed($this->current
)) {
653 // do not repeat yourself
657 if ($this->current
=== 'en') {
658 $this->mark_processed($this->current
);
662 $results[$this->current
] = $this->install_language_pack($this->current
);
664 if (in_array($results[$this->current
], array(self
::RESULT_INSTALLED
, self
::RESULT_UPTODATE
))) {
665 if ($parentlang = $this->get_parent_language($this->current
)) {
666 if (!$this->is_queued($parentlang) and !$this->was_processed($parentlang)) {
667 $this->add_to_queue($parentlang);
672 $this->mark_processed($this->current
);
679 * Returns the URL where a given language pack can be downloaded
681 * Alternatively, if the parameter is empty, returns URL of the page with the
682 * list of all available language packs.
684 * @param string $langcode language code like 'cs' or empty for unknown
687 public function lang_pack_url($langcode = '') {
689 if (empty($langcode)) {
690 return 'https://download.moodle.org/langpack/'.$this->version
.'/';
692 return 'https://download.moodle.org/download.php/langpack/'.$this->version
.'/'.$langcode.'.zip';
697 * Returns the list of available language packs from download.moodle.org
699 * @return array|bool false if can not download
701 public function get_remote_list_of_languages() {
702 $source = 'https://download.moodle.org/langpack/' . $this->version
. '/languages.md5';
703 $availablelangs = array();
705 if ($content = download_file_content($source)) {
706 $alllines = explode("\n", $content);
707 foreach($alllines as $line) {
709 $availablelangs[] = explode(',', $line);
712 return $availablelangs;
719 // Internal implementation /////////////////////////////////////////////////
722 * Adds a language pack (or a list of them) to the queue
724 * @param string|array $langcodes code of the language to install or a list of them
726 protected function add_to_queue($langcodes) {
727 if (is_array($langcodes)) {
728 $this->queue
= array_merge($this->queue
, $langcodes);
729 } else if (!empty($langcodes)) {
730 $this->queue
[] = $langcodes;
735 * Checks if the given language is queued or if the queue is empty
737 * @example $installer->is_queued('es'); // is Spanish going to be installed?
738 * @example $installer->is_queued(); // is there a language queued?
740 * @param string $langcode language code or empty string for "any"
743 protected function is_queued($langcode = '') {
745 if (empty($langcode)) {
746 return !empty($this->queue
);
749 return in_array($langcode, $this->queue
);
754 * Checks if the given language has already been processed by this instance
756 * @see self::mark_processed()
757 * @param string $langcode
760 protected function was_processed($langcode) {
761 return isset($this->done
[$langcode]);
765 * Mark the given language pack as processed
767 * @see self::was_processed()
768 * @param string $langcode
770 protected function mark_processed($langcode) {
771 $this->done
[$langcode] = 1;
775 * Returns a parent language of the given installed language
777 * @param string $langcode
778 * @return string parent language's code
780 protected function get_parent_language($langcode) {
781 return get_parent_language($langcode);
785 * Perform the actual language pack installation
787 * @uses component_installer
788 * @param string $langcode
789 * @return int return status
791 protected function install_language_pack($langcode) {
793 // initialise new component installer to process this language
794 $installer = new component_installer('https://download.moodle.org', 'download.php/direct/langpack/' . $this->version
,
795 $langcode . '.zip', 'languages.md5', 'lang');
797 if (!$installer->requisitesok
) {
798 throw new lang_installer_exception('installer_requisites_check_failed');
801 $status = $installer->install();
803 if ($status == COMPONENT_ERROR
) {
804 if ($installer->get_error() === 'remotedownloaderror') {
805 return self
::RESULT_DOWNLOADERROR
;
807 throw new lang_installer_exception($installer->get_error(), $langcode);
810 } else if ($status == COMPONENT_UPTODATE
) {
811 return self
::RESULT_UPTODATE
;
813 } else if ($status == COMPONENT_INSTALLED
) {
814 return self
::RESULT_INSTALLED
;
817 throw new lang_installer_exception('unexpected_installer_result', $status);
824 * Exception thrown by {@link lang_installer}
826 * @copyright 2011 David Mudrak <david@moodle.com>
827 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
829 class lang_installer_exception
extends moodle_exception
{
831 public function __construct($errorcode, $debuginfo = null) {
832 parent
::__construct($errorcode, 'error', '', null, $debuginfo);