MDL-33531 backup Avoiding possible Notice
[moodle.git] / backup / util / helper / backup_cron_helper.class.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
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.
9 //
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.
14 //
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 /**
20  * Utility helper for automated backups run through cron.
21  *
22  * @package    core
23  * @subpackage backup
24  * @copyright  2010 Sam Hemelryk
25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
28 /**
29  * This class is an abstract class with methods that can be called to aid the
30  * running of automated backups over cron.
31  */
32 abstract class backup_cron_automated_helper {
34     /** automated backups are active and ready to run */
35     const STATE_OK = 0;
36     /** automated backups are disabled and will not be run */
37     const STATE_DISABLED = 1;
38     /** automated backups are all ready running! */
39     const STATE_RUNNING = 2;
41     /** Course automated backup completed successfully */
42     const BACKUP_STATUS_OK = 1;
43     /** Course automated backup errored */
44     const BACKUP_STATUS_ERROR = 0;
45     /** Course automated backup never finished */
46     const BACKUP_STATUS_UNFINISHED = 2;
47     /** Course automated backup was skipped */
48     const BACKUP_STATUS_SKIPPED = 3;
50     /** Run if required by the schedule set in config. Default. **/
51     const RUN_ON_SCHEDULE = 0;
52     /** Run immediately. **/
53     const RUN_IMMEDIATELY = 1;
55     const AUTO_BACKUP_DISABLED = 0;
56     const AUTO_BACKUP_ENABLED = 1;
57     const AUTO_BACKUP_MANUAL = 2;
59     /**
60      * Runs the automated backups if required
61      *
62      * @global moodle_database $DB
63      */
64     public static function run_automated_backup($rundirective = self::RUN_ON_SCHEDULE) {
65         global $CFG, $DB;
67         $status = true;
68         $emailpending = false;
69         $now = time();
71         mtrace("Checking automated backup status",'...');
72         $state = backup_cron_automated_helper::get_automated_backup_state($rundirective);
73         if ($state === backup_cron_automated_helper::STATE_DISABLED) {
74             mtrace('INACTIVE');
75             return $state;
76         } else if ($state === backup_cron_automated_helper::STATE_RUNNING) {
77             mtrace('RUNNING');
78             if ($rundirective == self::RUN_IMMEDIATELY) {
79                 mtrace('Automated backups are already running. If this script is being run by cron this constitues an error. You will need to increase the time between executions within cron.');
80             } else {
81                 mtrace("automated backup are already running. Execution delayed");
82             }
83             return $state;
84         } else {
85             mtrace('OK');
86         }
87         backup_cron_automated_helper::set_state_running();
89         mtrace("Getting admin info");
90         $admin = get_admin();
91         if (!$admin) {
92             mtrace("Error: No admin account was found");
93             $state = false;
94         }
96         if ($status) {
97             mtrace("Checking courses");
98             mtrace("Skipping deleted courses", '...');
99             mtrace(sprintf("%d courses", backup_cron_automated_helper::remove_deleted_courses_from_schedule()));
100         }
102         if ($status) {
104             mtrace('Running required automated backups...');
106             // This could take a while!
107             @set_time_limit(0);
108             raise_memory_limit(MEMORY_EXTRA);
110             $nextstarttime = backup_cron_automated_helper::calculate_next_automated_backup($admin->timezone, $now);
111             $showtime = "undefined";
112             if ($nextstarttime > 0) {
113                 $showtime = userdate($nextstarttime,"",$admin->timezone);
114             }
116             $rs = $DB->get_recordset('course');
117             foreach ($rs as $course) {
118                 $backupcourse = $DB->get_record('backup_courses', array('courseid'=>$course->id));
119                 if (!$backupcourse) {
120                     $backupcourse = new stdClass;
121                     $backupcourse->courseid = $course->id;
122                     $DB->insert_record('backup_courses',$backupcourse);
123                     $backupcourse = $DB->get_record('backup_courses', array('courseid'=>$course->id));
124                 }
126                 // Skip courses that do not yet need backup
127                 $skipped = !(($backupcourse->nextstarttime >= 0 && $backupcourse->nextstarttime < $now) || $rundirective == self::RUN_IMMEDIATELY);
128                 // Skip backup of unavailable courses that have remained unmodified in a month
129                 if (!$skipped && empty($course->visible) && ($now - $course->timemodified) > 31*24*60*60) {  //Hidden + settings were unmodified last month
130                     //Check log if there were any modifications to the course content
131                     $sqlwhere = "course=:courseid AND time>:time AND ". $DB->sql_like('action', ':action', false, true, true);
132                     $params = array('courseid' => $course->id, 'time' => $now-31*24*60*60, 'action' => '%view%');
133                     $logexists = $DB->record_exists_select('log', $sqlwhere, $params);
134                     if (!$logexists) {
135                         $backupcourse->laststatus = backup_cron_automated_helper::BACKUP_STATUS_SKIPPED;
136                         $backupcourse->nextstarttime = $nextstarttime;
137                         $DB->update_record('backup_courses', $backupcourse);
138                         mtrace('Skipping unchanged course '.$course->fullname);
139                         $skipped = true;
140                     }
141                 }
142                 //Now we backup every non-skipped course
143                 if (!$skipped) {
144                     mtrace('Backing up '.$course->fullname, '...');
146                     //We have to send a email because we have included at least one backup
147                     $emailpending = true;
149                     //Only make the backup if laststatus isn't 2-UNFINISHED (uncontrolled error)
150                     if ($backupcourse->laststatus != 2) {
151                         //Set laststarttime
152                         $starttime = time();
154                         $backupcourse->laststarttime = time();
155                         $backupcourse->laststatus = backup_cron_automated_helper::BACKUP_STATUS_UNFINISHED;
156                         $DB->update_record('backup_courses', $backupcourse);
158                         $backupcourse->laststatus = backup_cron_automated_helper::launch_automated_backup($course, $backupcourse->laststarttime, $admin->id);
159                         $backupcourse->lastendtime = time();
160                         $backupcourse->nextstarttime = $nextstarttime;
162                         $DB->update_record('backup_courses', $backupcourse);
164                         if ($backupcourse->laststatus) {
165                             // Clean up any excess course backups now that we have
166                             // taken a successful backup.
167                             $removedcount = backup_cron_automated_helper::remove_excess_backups($course);
168                         }
169                     }
171                     mtrace("complete - next execution: $showtime");
172                 }
173             }
174             $rs->close();
175         }
177         //Send email to admin if necessary
178         if ($emailpending) {
179             mtrace("Sending email to admin");
180             $message = "";
182             $count = backup_cron_automated_helper::get_backup_status_array();
183             $haserrors = ($count[backup_cron_automated_helper::BACKUP_STATUS_ERROR] != 0 || $count[backup_cron_automated_helper::BACKUP_STATUS_UNFINISHED] != 0);
185             //Build the message text
186             //Summary
187             $message .= get_string('summary')."\n";
188             $message .= "==================================================\n";
189             $message .= "  ".get_string('courses').": ".array_sum($count)."\n";
190             $message .= "  ".get_string('ok').": ".$count[backup_cron_automated_helper::BACKUP_STATUS_OK]."\n";
191             $message .= "  ".get_string('skipped').": ".$count[backup_cron_automated_helper::BACKUP_STATUS_SKIPPED]."\n";
192             $message .= "  ".get_string('error').": ".$count[backup_cron_automated_helper::BACKUP_STATUS_ERROR]."\n";
193             $message .= "  ".get_string('unfinished').": ".$count[backup_cron_automated_helper::BACKUP_STATUS_UNFINISHED]."\n\n";
195             //Reference
196             if ($haserrors) {
197                 $message .= "  ".get_string('backupfailed')."\n\n";
198                 $dest_url = "$CFG->wwwroot/report/backups/index.php";
199                 $message .= "  ".get_string('backuptakealook','',$dest_url)."\n\n";
200                 //Set message priority
201                 $admin->priority = 1;
202                 //Reset unfinished to error
203                 $DB->set_field('backup_courses','laststatus','0', array('laststatus'=>'2'));
204             } else {
205                 $message .= "  ".get_string('backupfinished')."\n";
206             }
208             //Build the message subject
209             $site = get_site();
210             $prefix = format_string($site->shortname, true, array('context' => context_course::instance(SITEID))).": ";
211             if ($haserrors) {
212                 $prefix .= "[".strtoupper(get_string('error'))."] ";
213             }
214             $subject = $prefix.get_string('automatedbackupstatus', 'backup');
216             //Send the message
217             $eventdata = new stdClass();
218             $eventdata->modulename        = 'moodle';
219             $eventdata->userfrom          = $admin;
220             $eventdata->userto            = $admin;
221             $eventdata->subject           = $subject;
222             $eventdata->fullmessage       = $message;
223             $eventdata->fullmessageformat = FORMAT_PLAIN;
224             $eventdata->fullmessagehtml   = '';
225             $eventdata->smallmessage      = '';
227             $eventdata->component         = 'moodle';
228             $eventdata->name         = 'backup';
230             message_send($eventdata);
231         }
233         //Everything is finished stop backup_auto_running
234         backup_cron_automated_helper::set_state_running(false);
236         mtrace('Automated backups complete.');
238         return $status;
239     }
241     /**
242      * Gets the results from the last automated backup that was run based upon
243      * the statuses of the courses that were looked at.
244      *
245      * @global moodle_database $DB
246      * @return array
247      */
248     public static function get_backup_status_array() {
249         global $DB;
251         $result = array(
252             self::BACKUP_STATUS_ERROR => 0,
253             self::BACKUP_STATUS_OK => 0,
254             self::BACKUP_STATUS_UNFINISHED => 0,
255             self::BACKUP_STATUS_SKIPPED => 0,
256         );
258         $statuses = $DB->get_records_sql('SELECT DISTINCT bc.laststatus, COUNT(bc.courseid) statuscount FROM {backup_courses} bc GROUP BY bc.laststatus');
260         foreach ($statuses as $status) {
261             if (empty($status->statuscount)) {
262                 $status->statuscount = 0;
263             }
264             $result[(int)$status->laststatus] += $status->statuscount;
265         }
267         return $result;
268     }
270     /**
271      * Works out the next time the automated backup should be run.
272      *
273      * @param mixed $timezone
274      * @param int $now
275      * @return int
276      */
277     public static function calculate_next_automated_backup($timezone, $now) {
279         $result = -1;
280         $config = get_config('backup');
281         $midnight = usergetmidnight($now, $timezone);
282         $date = usergetdate($now, $timezone);
284         // Get number of days (from today) to execute backups
285         $automateddays = substr($config->backup_auto_weekdays, $date['wday']) . $config->backup_auto_weekdays;
286         $daysfromtoday = strpos($automateddays, "1", 1);
288         // If we can't find the next day, we set it to tomorrow
289         if (empty($daysfromtoday)) {
290             $daysfromtoday = 1;
291         }
293         // If some day has been found
294         if ($daysfromtoday !== false) {
295             // Calculate distance
296             $dist = ($daysfromtoday * 86400) +                // Days distance
297                     ($config->backup_auto_hour * 3600) +      // Hours distance
298                     ($config->backup_auto_minute * 60);       // Minutes distance
299             $result = $midnight + $dist;
300         }
302         // If that time is past, call the function recursively to obtain the next valid day
303         if ($result > 0 && $result < time()) {
304             $result = self::calculate_next_automated_backup($timezone, $result);
305         }
307         return $result;
308     }
310     /**
311      * Launches a automated backup routine for the given course
312      *
313      * @param stdClass $course
314      * @param int $starttime
315      * @param int $userid
316      * @return bool
317      */
318     public static function launch_automated_backup($course, $starttime, $userid) {
320         $outcome = true;
321         $config = get_config('backup');
322         $bc = new backup_controller(backup::TYPE_1COURSE, $course->id, backup::FORMAT_MOODLE, backup::INTERACTIVE_NO, backup::MODE_AUTOMATED, $userid);
324         try {
326             $settings = array(
327                 'users' => 'backup_auto_users',
328                 'role_assignments' => 'backup_auto_role_assignments',
329                 'activities' => 'backup_auto_activities',
330                 'blocks' => 'backup_auto_blocks',
331                 'filters' => 'backup_auto_filters',
332                 'comments' => 'backup_auto_comments',
333                 'completion_information' => 'backup_auto_userscompletion',
334                 'logs' => 'backup_auto_logs',
335                 'histories' => 'backup_auto_histories'
336             );
337             foreach ($settings as $setting => $configsetting) {
338                 if ($bc->get_plan()->setting_exists($setting)) {
339                     $bc->get_plan()->get_setting($setting)->set_value($config->{$configsetting});
340                 }
341             }
343             // Set the default filename
344             $format = $bc->get_format();
345             $type = $bc->get_type();
346             $id = $bc->get_id();
347             $users = $bc->get_plan()->get_setting('users')->get_value();
348             $anonymised = $bc->get_plan()->get_setting('anonymize')->get_value();
349             $bc->get_plan()->get_setting('filename')->set_value(backup_plan_dbops::get_default_backup_filename($format, $type, $id, $users, $anonymised));
351             $bc->set_status(backup::STATUS_AWAITING);
353             $bc->execute_plan();
354             $results = $bc->get_results();
355             $file = $results['backup_destination']; // may be empty if file already moved to target location
356             $dir = $config->backup_auto_destination;
357             $storage = (int)$config->backup_auto_storage;
358             if (!file_exists($dir) || !is_dir($dir) || !is_writable($dir)) {
359                 $dir = null;
360             }
361             if ($file && !empty($dir) && $storage !== 0) {
362                 $filename = backup_plan_dbops::get_default_backup_filename($format, $type, $course->id, $users, $anonymised, !$config->backup_shortname);
363                 $outcome = $file->copy_content_to($dir.'/'.$filename);
364                 if ($outcome && $storage === 1) {
365                     $file->delete();
366                 }
367             }
369         } catch (moodle_exception $e) {
370             $bc->log('backup_auto_failed_on_course', backup::LOG_ERROR, $course->shortname); // Log error header.
371             $bc->log('Exception: ' . $e->errorcode, backup::LOG_ERROR, $e->a, 1); // Log original exception problem.
372             $bc->log('Debug: ' . $e->debuginfo, backup::LOG_DEBUG, null, 1); // Log original debug information.
373             $outcome = false;
374         }
376         $bc->destroy();
377         unset($bc);
379         return $outcome;
380     }
382     /**
383      * Removes deleted courses fromn the backup_courses table so that we don't
384      * waste time backing them up.
385      *
386      * @global moodle_database $DB
387      * @return int
388      */
389     public static function remove_deleted_courses_from_schedule() {
390         global $DB;
391         $skipped = 0;
392         $sql = "SELECT bc.courseid FROM {backup_courses} bc WHERE bc.courseid NOT IN (SELECT c.id FROM {course} c)";
393         $rs = $DB->get_recordset_sql($sql);
394         foreach ($rs as $deletedcourse) {
395             //Doesn't exist, so delete from backup tables
396             $DB->delete_records('backup_courses', array('courseid'=>$deletedcourse->courseid));
397             $skipped++;
398         }
399         $rs->close();
400         return $skipped;
401     }
403     /**
404      * Gets the state of the automated backup system.
405      *
406      * @global moodle_database $DB
407      * @return int One of self::STATE_*
408      */
409     public static function get_automated_backup_state($rundirective = self::RUN_ON_SCHEDULE) {
410         global $DB;
412         $config = get_config('backup');
413         $active = (int)$config->backup_auto_active;
414         if ($active === self::AUTO_BACKUP_DISABLED || ($rundirective == self::RUN_ON_SCHEDULE && $active === self::AUTO_BACKUP_MANUAL)) {
415             return self::STATE_DISABLED;
416         } else if (!empty($config->backup_auto_running)) {
417             // Detect if the backup_auto_running semaphore is a valid one
418             // by looking for recent activity in the backup_controllers table
419             // for backups of type backup::MODE_AUTOMATED
420             $timetosee = 60 * 90; // Time to consider in order to clean the semaphore
421             $params = array( 'purpose'   => backup::MODE_AUTOMATED, 'timetolook' => (time() - $timetosee));
422             if ($DB->record_exists_select('backup_controllers',
423                 "operation = 'backup' AND type = 'course' AND purpose = :purpose AND timemodified > :timetolook", $params)) {
424                 return self::STATE_RUNNING; // Recent activity found, still running
425             } else {
426                 // No recent activity found, let's clean the semaphore
427                 mtrace('Automated backups activity not found in last ' . (int)$timetosee/60 . ' minutes. Cleaning running status');
428                 backup_cron_automated_helper::set_state_running(false);
429             }
430         }
431         return self::STATE_OK;
432     }
434     /**
435      * Sets the state of the automated backup system.
436      *
437      * @param bool $running
438      * @return bool
439      */
440     public static function set_state_running($running = true) {
441         if ($running === true) {
442             if (self::get_automated_backup_state() === self::STATE_RUNNING) {
443                 throw new backup_exception('backup_automated_already_running');
444             }
445             set_config('backup_auto_running', '1', 'backup');
446         } else {
447             unset_config('backup_auto_running', 'backup');
448         }
449         return true;
450     }
452     /**
453      * Removes excess backups from the external system and the local file system.
454      *
455      * The number of backups keep comes from $config->backup_auto_keep
456      *
457      * @param stdClass $course
458      * @return bool
459      */
460     public static function remove_excess_backups($course) {
461         $config = get_config('backup');
462         $keep =     (int)$config->backup_auto_keep;
463         $storage =  $config->backup_auto_storage;
464         $dir =      $config->backup_auto_destination;
466         if ($keep == 0) {
467             // means keep all backup files
468             return true;
469         }
471         $backupword = str_replace(' ', '_', textlib::strtolower(get_string('backupfilename')));
472         $backupword = trim(clean_filename($backupword), '_');
474         if (!file_exists($dir) || !is_dir($dir) || !is_writable($dir)) {
475             $dir = null;
476         }
478         // Clean up excess backups in the course backup filearea
479         if ($storage == 0 || $storage == 2) {
480             $fs = get_file_storage();
481             $context = context_course::instance($course->id);
482             $component = 'backup';
483             $filearea = 'automated';
484             $itemid = 0;
485             $files = array();
486             // Store all the matching files into timemodified => stored_file array
487             foreach ($fs->get_area_files($context->id, $component, $filearea, $itemid) as $file) {
488                 if (strpos($file->get_filename(), $backupword) !== 0) {
489                     continue;
490                 }
491                 $files[$file->get_timemodified()] = $file;
492             }
493             if (count($files) <= $keep) {
494                 // There are less matching files than the desired number to keep
495                 // do there is nothing to clean up.
496                 return 0;
497             }
498             // Sort by keys descending (newer to older filemodified)
499             krsort($files);
500             $remove = array_splice($files, $keep);
501             foreach ($remove as $file) {
502                 $file->delete();
503             }
504             //mtrace('Removed '.count($remove).' old backup file(s) from the automated filearea');
505         }
507         // Clean up excess backups in the specified external directory
508         if (!empty($dir) && ($storage == 1 || $storage == 2)) {
509             // Calculate backup filename regex, ignoring the date/time/info parts that can be
510             // variable, depending of languages, formats and automated backup settings
513             // MDL-33531: use different filenames depending on backup_shortname option
514             if ( !empty($config->backup_shortname) ) {
515                 $courseref = $course->shortname;
516                 $courseref = str_replace(' ', '_', $courseref);
517                 $courseref = textlib::strtolower(trim(clean_filename($courseref), '_'));
518             } else {
519                 $courseref = $course->id;
520             }
521             $filename = $backupword . '-' . backup::FORMAT_MOODLE . '-' . backup::TYPE_1COURSE . '-' .$courseref . '-';
522             $regex = '#^'.preg_quote($filename, '#').'.*\.mbz$#';
524             // Store all the matching files into fullpath => timemodified array
525             $files = array();
526             foreach (scandir($dir) as $file) {
527                 if (preg_match($regex, $file, $matches)) {
528                     $files[$file] = filemtime($dir . '/' . $file);
529                 }
530             }
531             if (count($files) <= $keep) {
532                 // There are less matching files than the desired number to keep
533                 // do there is nothing to clean up.
534                 return 0;
535             }
536             // Sort by values descending (newer to older filemodified)
537             arsort($files);
538             $remove = array_splice($files, $keep);
539             foreach (array_keys($remove) as $file) {
540                 unlink($dir . '/' . $file);
541             }
542             //mtrace('Removed '.count($remove).' old backup file(s) from external directory');
543         }
545         return true;
546     }