Merge branch 'MDL-53140-master' of git://github.com/rezaies/moodle
[moodle.git] / completion / classes / manager.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  * Bulk activity completion manager class
19  *
20  * @package     core_completion
21  * @category    completion
22  * @copyright   2017 Adrian Greeve
23  * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 namespace core_completion;
28 use stdClass;
29 use context_course;
30 use cm_info;
31 use tabobject;
32 use lang_string;
33 use moodle_url;
34 defined('MOODLE_INTERNAL') || die;
36 /**
37  * Bulk activity completion manager class
38  *
39  * @package     core_completion
40  * @category    completion
41  * @copyright   2017 Adrian Greeve
42  * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43  */
44 class manager {
46     /**
47      * @var int $courseid the course id.
48      */
49     protected $courseid;
51     /**
52      * manager constructor.
53      * @param int $courseid the course id.
54      */
55     public function __construct($courseid) {
56         $this->courseid = $courseid;
57     }
59     /**
60      * Gets the data (context) to be used with the bulkactivitycompletion template.
61      *
62      * @return stdClass data for use with the bulkactivitycompletion template.
63      */
64     public function get_activities_and_headings() {
65         global $OUTPUT;
66         $moduleinfo = get_fast_modinfo($this->courseid);
67         $sections = $moduleinfo->get_sections();
68         $data = new stdClass;
69         $data->courseid = $this->courseid;
70         $data->sesskey = sesskey();
71         $data->helpicon = $OUTPUT->help_icon('bulkcompletiontracking', 'core_completion');
72         $data->sections = [];
73         foreach ($sections as $sectionnumber => $section) {
74             $sectioninfo = $moduleinfo->get_section_info($sectionnumber);
76             $sectionobject = new stdClass();
77             $sectionobject->sectionnumber = $sectionnumber;
78             $sectionobject->name = get_section_name($this->courseid, $sectioninfo);
79             $sectionobject->activities = $this->get_activities($section, true);
80             $data->sections[] = $sectionobject;
81         }
82         return $data;
83     }
85     /**
86      * Gets the data (context) to be used with the activityinstance template
87      *
88      * @param array $cmids list of course module ids
89      * @param bool $withcompletiondetails include completion details
90      * @return array
91      */
92     public function get_activities($cmids, $withcompletiondetails = false) {
93         $moduleinfo = get_fast_modinfo($this->courseid);
94         $activities = [];
95         foreach ($cmids as $cmid) {
96             $mod = $moduleinfo->get_cm($cmid);
97             if (!$mod->uservisible) {
98                 continue;
99             }
100             $moduleobject = new stdClass();
101             $moduleobject->cmid = $cmid;
102             $moduleobject->modname = $mod->get_formatted_name();
103             $moduleobject->icon = $mod->get_icon_url()->out();
104             $moduleobject->url = $mod->url;
105             $moduleobject->canmanage = $withcompletiondetails && self::can_edit_bulk_completion($this->courseid, $mod);
107             // Get activity completion information.
108             if ($moduleobject->canmanage) {
109                 $moduleobject->completionstatus = $this->get_completion_detail($mod);
110             } else {
111                 $moduleobject->completionstatus = ['icon' => null, 'string' => null];
112             }
113             if (self::can_edit_bulk_completion($this->courseid, $mod)) {
114                 $activities[] = $moduleobject;
115             }
116         }
117         return $activities;
118     }
121     /**
122      * Get completion information on the selected module or module type
123      *
124      * @param cm_info|stdClass $mod either instance of cm_info (with 'customcompletionrules' in customdata) or
125      *      object with fields ->completion, ->completionview, ->completionexpected, ->completionusegrade
126      *      and ->customdata['customcompletionrules']
127      * @return array
128      */
129     private function get_completion_detail($mod) {
130         global $OUTPUT;
131         $strings = [];
132         switch ($mod->completion) {
133             case COMPLETION_TRACKING_NONE:
134                 $strings['string'] = get_string('none');
135                 break;
137             case COMPLETION_TRACKING_MANUAL:
138                 $strings['string'] = get_string('manual', 'completion');
139                 $strings['icon'] = $OUTPUT->pix_icon('i/completion-manual-y', get_string('completion_manual', 'completion'));
140                 break;
142             case COMPLETION_TRACKING_AUTOMATIC:
143                 $strings['string'] = get_string('withconditions', 'completion');
144                 $strings['icon'] = $OUTPUT->pix_icon('i/completion-auto-y', get_string('completion_automatic', 'completion'));
145                 break;
147             default:
148                 $strings['string'] = get_string('none');
149                 break;
150         }
152         // Get the descriptions for all the active completion rules for the module.
153         if ($ruledescriptions = $this->get_completion_active_rule_descriptions($mod)) {
154             foreach ($ruledescriptions as $ruledescription) {
155                 $strings['string'] .= \html_writer::empty_tag('br') . $ruledescription;
156             }
157         }
158         return $strings;
159     }
161     /**
162      * Get the descriptions for all active conditional completion rules for the current module.
163      *
164      * @param cm_info|stdClass $moduledata either instance of cm_info (with 'customcompletionrules' in customdata) or
165      *      object with fields ->completion, ->completionview, ->completionexpected, ->completionusegrade
166      *      and ->customdata['customcompletionrules']
167      * @return array $activeruledescriptions an array of strings describing the active completion rules.
168      */
169     protected function get_completion_active_rule_descriptions($moduledata) {
170         $activeruledescriptions = [];
172         if ($moduledata->completion == COMPLETION_TRACKING_AUTOMATIC) {
173             // Generate the description strings for the core conditional completion rules (if set).
174             if (!empty($moduledata->completionview)) {
175                 $activeruledescriptions[] = get_string('completionview_desc', 'completion');
176             }
177             if ($moduledata instanceof cm_info && !is_null($moduledata->completiongradeitemnumber) ||
178                 ($moduledata instanceof stdClass && !empty($moduledata->completionusegrade))) {
179                 $activeruledescriptions[] = get_string('completionusegrade_desc', 'completion');
180             }
182             // Now, ask the module to provide descriptions for its custom conditional completion rules.
183             if ($customruledescriptions = component_callback($moduledata->modname,
184                 'get_completion_active_rule_descriptions', [$moduledata])) {
185                 $activeruledescriptions = array_merge($activeruledescriptions, $customruledescriptions);
186             }
187         }
189         if ($moduledata->completion != COMPLETION_TRACKING_NONE) {
190             if (!empty($moduledata->completionexpected)) {
191                 $activeruledescriptions[] = get_string('completionexpecteddesc', 'completion',
192                     userdate($moduledata->completionexpected));
193             }
194         }
196         return $activeruledescriptions;
197     }
199     /**
200      * Gets the course modules for the current course.
201      *
202      * @return stdClass $data containing the modules
203      */
204     public function get_activities_and_resources() {
205         global $DB, $OUTPUT, $CFG;
206         require_once($CFG->dirroot.'/course/lib.php');
208         // Get enabled activities and resources.
209         $modules = $DB->get_records('modules', ['visible' => 1], 'name ASC');
210         $data = new stdClass();
211         $data->courseid = $this->courseid;
212         $data->sesskey = sesskey();
213         $data->helpicon = $OUTPUT->help_icon('bulkcompletiontracking', 'core_completion');
214         // Add icon information.
215         $data->modules = array_values($modules);
216         $coursecontext = context_course::instance($this->courseid);
217         $canmanage = has_capability('moodle/course:manageactivities', $coursecontext);
218         $course = get_course($this->courseid);
219         foreach ($data->modules as $module) {
220             $module->icon = $OUTPUT->image_url('icon', $module->name)->out();
221             $module->formattedname = format_string(get_string('modulenameplural', 'mod_' . $module->name),
222                 true, ['context' => $coursecontext]);
223             $module->canmanage = $canmanage && course_allowed_module($course, $module->name);
224             $defaults = self::get_default_completion($course, $module, false);
225             $defaults->modname = $module->name;
226             $module->completionstatus = $this->get_completion_detail($defaults);
227         }
229         return $data;
230     }
232     /**
233      * Checks if current user can edit activity completion
234      *
235      * @param int|stdClass $courseorid
236      * @param \cm_info|null $cm if specified capability for a given coursemodule will be check,
237      *     if not specified capability to edit at least one activity is checked.
238      */
239     public static function can_edit_bulk_completion($courseorid, $cm = null) {
240         if ($cm) {
241             return $cm->uservisible && has_capability('moodle/course:manageactivities', $cm->context);
242         }
243         $coursecontext = context_course::instance(is_object($courseorid) ? $courseorid->id : $courseorid);
244         if (has_capability('moodle/course:manageactivities', $coursecontext)) {
245             return true;
246         }
247         $modinfo = get_fast_modinfo($courseorid);
248         foreach ($modinfo->cms as $mod) {
249             if ($mod->uservisible && has_capability('moodle/course:manageactivities', $mod->context)) {
250                 return true;
251             }
252         }
253         return false;
254     }
256     /**
257      * Gets the available completion tabs for the current course and user.
258      *
259      * @param stdClass|int $courseorid the course object or id.
260      * @return tabobject[]
261      */
262     public static function get_available_completion_tabs($courseorid) {
263         $tabs = [];
265         $courseid = is_object($courseorid) ? $courseorid->id : $courseorid;
266         $coursecontext = context_course::instance($courseid);
268         if (has_capability('moodle/course:update', $coursecontext)) {
269             $tabs[] = new tabobject(
270                 'completion',
271                 new moodle_url('/course/completion.php', ['id' => $courseid]),
272                 new lang_string('coursecompletion', 'completion')
273             );
274         }
276         if (has_capability('moodle/course:manageactivities', $coursecontext)) {
277             $tabs[] = new tabobject(
278                 'defaultcompletion',
279                 new moodle_url('/course/defaultcompletion.php', ['id' => $courseid]),
280                 new lang_string('defaultcompletion', 'completion')
281             );
282         }
284         if (self::can_edit_bulk_completion($courseorid)) {
285             $tabs[] = new tabobject(
286                 'bulkcompletion',
287                 new moodle_url('/course/bulkcompletion.php', ['id' => $courseid]),
288                 new lang_string('bulkactivitycompletion', 'completion')
289             );
290         }
292         return $tabs;
293     }
295     /**
296      * Applies completion from the bulk edit form to all selected modules
297      *
298      * @param stdClass $data data received from the core_completion_bulkedit_form
299      * @param bool $updateinstances if we need to update the instance tables of the module (i.e. 'assign', 'forum', etc.) -
300      *      if no module-specific completion rules were added to the form, update of the module table is not needed.
301      */
302     public function apply_completion($data, $updateinstances) {
303         $updated = false;
304         $needreset = [];
305         $modinfo = get_fast_modinfo($this->courseid);
307         $cmids = $data->cmid;
309         $data = (array)$data;
310         unset($data['id']); // This is a course id, we don't want to confuse it with cmid or instance id.
311         unset($data['cmid']);
312         unset($data['submitbutton']);
314         foreach ($cmids as $cmid) {
315             $cm = $modinfo->get_cm($cmid);
316             if (self::can_edit_bulk_completion($this->courseid, $cm) && $this->apply_completion_cm($cm, $data, $updateinstances)) {
317                 $updated = true;
318                 if ($cm->completion != COMPLETION_TRACKING_MANUAL || $data['completion'] != COMPLETION_TRACKING_MANUAL) {
319                     // If completion was changed we will need to reset it's state. Exception is when completion was and remains as manual.
320                     $needreset[] = $cm->id;
321                 }
322             }
323             // Update completion calendar events.
324             $completionexpected = ($data['completionexpected']) ? $data['completionexpected'] : null;
325             \core_completion\api::update_completion_date_event($cm->id, $cm->modname, $cm->instance, $completionexpected);
326         }
327         if ($updated) {
328             // Now that modules are fully updated, also update completion data if required.
329             // This will wipe all user completion data and recalculate it.
330             rebuild_course_cache($this->courseid, true);
331             $modinfo = get_fast_modinfo($this->courseid);
332             $completion = new \completion_info($modinfo->get_course());
333             foreach ($needreset as $cmid) {
334                 $completion->reset_all_state($modinfo->get_cm($cmid));
335             }
337             // And notify the user of the result.
338             \core\notification::add(get_string('activitycompletionupdated', 'core_completion'), \core\notification::SUCCESS);
339         }
340     }
342     /**
343      * Applies new completion rules to one course module
344      *
345      * @param \cm_info $cm
346      * @param array $data
347      * @param bool $updateinstance if we need to update the instance table of the module (i.e. 'assign', 'forum', etc.) -
348      *      if no module-specific completion rules were added to the form, update of the module table is not needed.
349      * @return bool if module was updated
350      */
351     protected function apply_completion_cm(\cm_info $cm, $data, $updateinstance) {
352         global $DB;
354         $defaults = ['completion' => COMPLETION_DISABLED, 'completionview' => COMPLETION_VIEW_NOT_REQUIRED,
355             'completionexpected' => 0, 'completiongradeitemnumber' => null];
357         $data += ['completion' => $cm->completion,
358             'completionexpected' => $cm->completionexpected,
359             'completionview' => $cm->completionview];
361         if ($cm->completion == $data['completion'] && $cm->completion == COMPLETION_TRACKING_NONE) {
362             // If old and new completion are both "none" - no changes are needed.
363             return false;
364         }
366         if ($cm->completion == $data['completion'] && $cm->completion == COMPLETION_TRACKING_NONE &&
367                 $cm->completionexpected == $data['completionexpected']) {
368             // If old and new completion are both "manual" and completion expected date is not changed - no changes are needed.
369             return false;
370         }
372         if (array_key_exists('completionusegrade', $data)) {
373             // Convert the 'use grade' checkbox into a grade-item number: 0 if checked, null if not.
374             $data['completiongradeitemnumber'] = !empty($data['completionusegrade']) ? 0 : null;
375             unset($data['completionusegrade']);
376         } else {
377             $data['completiongradeitemnumber'] = $cm->completiongradeitemnumber;
378         }
380         // Update module instance table.
381         if ($updateinstance) {
382             $moddata = ['id' => $cm->instance, 'timemodified' => time()] + array_diff_key($data, $defaults);
383             $DB->update_record($cm->modname, $moddata);
384         }
386         // Update course modules table.
387         $cmdata = ['id' => $cm->id, 'timemodified' => time()] + array_intersect_key($data, $defaults);
388         $DB->update_record('course_modules', $cmdata);
390         \core\event\course_module_updated::create_from_cm($cm, $cm->context)->trigger();
392         // We need to reset completion data for this activity.
393         return true;
394     }
397     /**
398      * Saves default completion from edit form to all selected module types
399      *
400      * @param stdClass $data data received from the core_completion_bulkedit_form
401      * @param bool $updatecustomrules if we need to update the custom rules of the module -
402      *      if no module-specific completion rules were added to the form, update of the module table is not needed.
403      */
404     public function apply_default_completion($data, $updatecustomrules) {
405         global $DB;
407         $courseid = $data->id;
408         $coursecontext = context_course::instance($courseid);
409         if (!$modids = $data->modids) {
410             return;
411         }
412         $defaults = [
413             'completion' => COMPLETION_DISABLED,
414             'completionview' => COMPLETION_VIEW_NOT_REQUIRED,
415             'completionexpected' => 0,
416             'completionusegrade' => 0
417         ];
419         $data = (array)$data;
421         if ($updatecustomrules) {
422             $customdata = array_diff_key($data, $defaults);
423             $data['customrules'] = $customdata ? json_encode($customdata) : null;
424             $defaults['customrules'] = null;
425         }
426         $data = array_intersect_key($data, $defaults);
428         // Get names of the affected modules.
429         list($modidssql, $params) = $DB->get_in_or_equal($modids);
430         $params[] = 1;
431         $modules = $DB->get_records_select_menu('modules', 'id ' . $modidssql . ' and visible = ?', $params, '', 'id, name');
433         // Get an associative array of [module_id => course_completion_defaults_id].
434         list($in, $params) = $DB->get_in_or_equal($modids);
435         $params[] = $courseid;
436         $defaultsids = $DB->get_records_select_menu('course_completion_defaults', 'module ' . $in . ' and course = ?', $params, '',
437                                                       'module, id');
439         foreach ($modids as $modid) {
440             if (!array_key_exists($modid, $modules)) {
441                 continue;
442             }
443             if (isset($defaultsids[$modid])) {
444                 $DB->update_record('course_completion_defaults', $data + ['id' => $defaultsids[$modid]]);
445             } else {
446                 $defaultsids[$modid] = $DB->insert_record('course_completion_defaults', $data + ['course' => $courseid,
447                                                                                                  'module' => $modid]);
448             }
449             // Trigger event.
450             \core\event\completion_defaults_updated::create([
451                 'objectid' => $defaultsids[$modid],
452                 'context' => $coursecontext,
453                 'other' => ['modulename' => $modules[$modid]],
454             ])->trigger();
455         }
457         // Add notification.
458         \core\notification::add(get_string('defaultcompletionupdated', 'completion'), \core\notification::SUCCESS);
459     }
461     /**
462      * Returns default completion rules for given module type in the given course
463      *
464      * @param stdClass $course
465      * @param stdClass $module
466      * @param bool $flatten if true all module custom completion rules become properties of the same object,
467      *   otherwise they can be found as array in ->customdata['customcompletionrules']
468      * @return stdClass
469      */
470     public static function get_default_completion($course, $module, $flatten = true) {
471         global $DB, $CFG;
472         if ($data = $DB->get_record('course_completion_defaults', ['course' => $course->id, 'module' => $module->id],
473             'completion, completionview, completionexpected, completionusegrade, customrules')) {
474             if ($data->customrules && ($customrules = @json_decode($data->customrules, true))) {
475                 if ($flatten) {
476                     foreach ($customrules as $key => $value) {
477                         $data->$key = $value;
478                     }
479                 } else {
480                     $data->customdata['customcompletionrules'] = $customrules;
481                 }
482             }
483             unset($data->customrules);
484         } else {
485             $data = new stdClass();
486             $data->completion = COMPLETION_TRACKING_NONE;
487             if ($CFG->completiondefault) {
488                 $completion = new \completion_info(get_fast_modinfo($course->id)->get_course());
489                 if ($completion->is_enabled() && plugin_supports('mod', $module->name, FEATURE_MODEDIT_DEFAULT_COMPLETION, true)) {
490                     $data->completion = COMPLETION_TRACKING_MANUAL;
491                     $data->completionview = 1;
492                 }
493             }
494         }
495         return $data;
496     }