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 * Provides base converter classes
22 * @subpackage backup-convert
23 * @copyright 2011 Mark Nielsen <mark@moodlerooms.com>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 defined('MOODLE_INTERNAL') ||
die();
29 require_once($CFG->dirroot
. '/backup/util/includes/convert_includes.php');
32 * Base converter class
34 * All Moodle backup converters are supposed to extend this base class.
36 * @throws convert_exception
38 abstract class base_converter
implements loggable
{
40 /** @var string unique identifier of this converter instance */
43 /** @var string the name of the directory containing the unpacked backup being converted */
46 /** @var string the name of the directory where the backup is converted to */
49 /** @var null|base_logger logger to use during the conversion */
50 protected $logger = null;
55 * @param string $tempdir the relative path to the directory containing the unpacked backup to convert
56 * @param null|base_logger logger to use during the conversion
58 public function __construct($tempdir, $logger = null) {
60 $this->tempdir
= $tempdir;
61 $this->id
= convert_helper
::generate_id($tempdir);
62 $this->workdir
= $tempdir . '_' . $this->get_name() . '_' . $this->id
;
63 $this->set_logger($logger);
64 $this->log('instantiating '.$this->get_name().' converter '.$this->get_id(), backup
::LOG_DEBUG
);
65 $this->log('conversion source directory', backup
::LOG_DEBUG
, $this->tempdir
);
66 $this->log('conversion target directory', backup
::LOG_DEBUG
, $this->workdir
);
71 * Sets the logger to use during the conversion
73 * @param null|base_logger $logger
75 public function set_logger($logger) {
76 if (is_null($logger) or ($logger instanceof base_logger
)) {
77 $this->logger
= $logger;
82 * If the logger was set for the converter, log the message
84 * If the $display is enabled, the spaces in the $message text are removed
85 * and the text is used as a string identifier in the core_backup language file.
87 * @see backup_helper::log()
88 * @param string $message message text
89 * @param int $level message level {@example backup::LOG_WARNING}
90 * @param null|mixed $a additional information
91 * @param null|int $depth the message depth
92 * @param bool $display whether the message should be sent to the output, too
94 public function log($message, $level, $a = null, $depth = null, $display = false) {
95 if ($this->logger
instanceof base_logger
) {
96 backup_helper
::log($message, $level, $a, $depth, $display, $this->logger
);
101 * Get instance identifier
103 * @return string the unique identifier of this converter instance
105 public function get_id() {
112 * @return string the system name of the converter
114 public function get_name() {
115 return array_shift(explode('_', get_class($this)));
119 * Converts the backup directory
121 public function convert() {
124 $this->log('creating the target directory', backup
::LOG_DEBUG
);
125 $this->create_workdir();
127 $this->log('executing the conversion', backup
::LOG_DEBUG
);
130 $this->log('replacing the source directory with the converted version', backup
::LOG_DEBUG
);
131 $this->replace_tempdir();
132 } catch (Exception
$e) {
135 // clean-up stuff if needed
138 // eventually re-throw the execution exception
139 if (isset($e) and ($e instanceof Exception
)) {
145 * @return string the full path to the working directory
147 public function get_workdir_path() {
150 return "$CFG->tempdir/backup/$this->workdir";
154 * @return string the full path to the directory with the source backup
156 public function get_tempdir_path() {
159 return "$CFG->tempdir/backup/$this->tempdir";
162 /// public static methods //////////////////////////////////////////////////
165 * Makes sure that this converter is available at this site
167 * This is intended for eventual PHP extensions check, environment check etc.
168 * All checks that do not depend on actual backup data should be done here.
170 * @return boolean true if this converter should be considered as available
172 public static function is_available() {
177 * Detects the format of the backup directory
179 * Moodle 2.x format is being detected by the core itself. The converters are
180 * therefore supposed to detect the source format. Eventually, if the target
181 * format os not {@link backup::FORMAT_MOODLE} then they should be able to
182 * detect both source and target formats.
184 * @param string $tempdir the name of the backup directory
185 * @return null|string null if not recognized, backup::FORMAT_xxx otherwise
187 public static function detect_format($tempdir) {
192 * Returns the basic information about the converter
194 * The returned array must contain the following keys:
195 * 'from' - the supported source format, eg. backup::FORMAT_MOODLE1
196 * 'to' - the supported target format, eg. backup::FORMAT_MOODLE
197 * 'cost' - the cost of the conversion, non-negative non-zero integer
199 public static function description() {
208 /// end of public API //////////////////////////////////////////////////////
211 * Initialize the instance if needed, called by the constructor
213 protected function init() {
217 * Converts the contents of the tempdir into the target format in the workdir
219 protected abstract function execute();
222 * Prepares a new empty working directory
224 protected function create_workdir() {
226 fulldelete($this->get_workdir_path());
227 if (!check_dir_exists($this->get_workdir_path())) {
228 throw new convert_exception('failed_create_workdir');
233 * Replaces the source backup directory with the converted version
235 * If $CFG->keeptempdirectoriesonbackup is defined, the original source
236 * source backup directory is kept for debugging purposes.
238 protected function replace_tempdir() {
241 if (empty($CFG->keeptempdirectoriesonbackup
)) {
242 fulldelete($this->get_tempdir_path());
244 if (!rename($this->get_tempdir_path(), $this->get_tempdir_path() . '_' . $this->get_name() . '_' . $this->id
. '_source')) {
245 throw new convert_exception('failed_rename_source_tempdir');
249 if (!rename($this->get_workdir_path(), $this->get_tempdir_path())) {
250 throw new convert_exception('failed_move_converted_into_place');
255 * Cleans up stuff after the execution
257 * Note that we do not know if the execution was successful or not.
258 * An exception might have been thrown.
260 protected function destroy() {
263 if (empty($CFG->keeptempdirectoriesonbackup
)) {
264 fulldelete($this->get_workdir_path());
270 * General convert-related exception
272 * @author David Mudrak <david@moodle.com>
274 class convert_exception
extends moodle_exception
{
279 * @param string $errorcode key for the corresponding error string
280 * @param object $a extra words and phrases that might be required in the error string
281 * @param string $debuginfo optional debugging information
283 public function __construct($errorcode, $a = null, $debuginfo = null) {
284 parent
::__construct($errorcode, '', '', $a, $debuginfo);