/**
* Takes a bunch of information to format into an email and send
* to the specified recipient.
*
* @param object $course the course
* @param object $quiz the quiz
* @param object $attempt this attempt just finished
* @param object $context the quiz context
* @param object $cm the coursemodule for this quiz
*
* @return int number of emails sent
*/
function quiz_send_notification_emails($course, $quiz, $attempt, $context, $cm)
{
global $CFG, $USER;
// we will count goods and bads for error logging
$emailresult = array('good' => 0, 'block' => 0, 'fail' => 0);
// do nothing if required objects not present
if (empty($course) or empty($quiz) or empty($attempt) or empty($context)) {
debugging('quiz_send_notification_emails: Email(s) not sent due to program error.', DEBUG_DEVELOPER);
return $emailresult['fail'];
}
// check for confirmation required
$sendconfirm = false;
$notifyexcludeusers = '';
if (has_capability('mod/quiz:emailconfirmsubmission', $context, NULL, false)) {
// exclude from notify emails later
$notifyexcludeusers = $USER->id;
// send the email
$sendconfirm = true;
}
// check for notifications required
$notifyfields = 'u.id, u.username, u.firstname, u.lastname, u.email, u.emailstop, u.lang, u.timezone, u.mailformat, u.maildisplay';
$groups = groups_get_all_groups($course->id, $USER->id);
if (is_array($groups) && count($groups) > 0) {
$groups = array_keys($groups);
} else {
if (groups_get_activity_groupmode($cm, $course) != NOGROUPS) {
// If the user is not in a group, and the quiz is set to group mode,
// then set $gropus to a non-existant id so that only users with
// 'moodle/site:accessallgroups' get notified.
$groups = -1;
} else {
$groups = '';
}
}
$userstonotify = get_users_by_capability($context, 'mod/quiz:emailnotifysubmission', $notifyfields, '', '', '', $groups, $notifyexcludeusers, false, false, true);
// if something to send, then build $a
if (!empty($userstonotify) or $sendconfirm) {
$a = new stdClass();
// course info
$a->coursename = $course->fullname;
$a->courseshortname = $course->shortname;
// quiz info
$a->quizname = $quiz->name;
$a->quizreporturl = $CFG->wwwroot . '/mod/quiz/report.php?q=' . $quiz->id;
$a->quizreportlink = '<a href="' . $a->quizreporturl . '">' . format_string($quiz->name) . ' report</a>';
$a->quizreviewurl = $CFG->wwwroot . '/mod/quiz/review.php?attempt=' . $attempt->id;
$a->quizreviewlink = '<a href="' . $a->quizreviewurl . '">' . format_string($quiz->name) . ' review</a>';
$a->quizurl = $CFG->wwwroot . '/mod/quiz/view.php?q=' . $quiz->id;
$a->quizlink = '<a href="' . $a->quizurl . '">' . format_string($quiz->name) . '</a>';
// attempt info
$a->submissiontime = userdate($attempt->timefinish);
$a->timetaken = format_time($attempt->timefinish - $attempt->timestart);
// student who sat the quiz info
$a->studentidnumber = $USER->idnumber;
$a->studentname = fullname($USER);
$a->studentusername = $USER->username;
}
// send confirmation if required
if ($sendconfirm) {
// send the email and update stats
switch (quiz_send_confirmation($a)) {
case true:
$emailresult['good']++;
break;
case false:
$emailresult['fail']++;
break;
case 'emailstop':
$emailresult['block']++;
break;
}
}
// send notifications if required
if (!empty($userstonotify)) {
// loop through recipients and send an email to each and update stats
foreach ($userstonotify as $recipient) {
switch (quiz_send_notification($recipient, $a)) {
case true:
$emailresult['good']++;
break;
case false:
$emailresult['fail']++;
break;
case 'emailstop':
$emailresult['block']++;
break;
}
}
}
// log errors sending emails if any
if (!empty($emailresult['fail'])) {
debugging('quiz_send_notification_emails:: ' . $emailresult['fail'] . ' email(s) failed to be sent.', DEBUG_DEVELOPER);
}
if (!empty($emailresult['block'])) {
debugging('quiz_send_notification_emails:: ' . $emailresult['block'] . ' email(s) were blocked by the user.', DEBUG_DEVELOPER);
}
// return the number of successfully sent emails
return $emailresult['good'];
}
/**
* Send all the requried messages when a quiz attempt is submitted.
*
* @param object $course the course
* @param object $quiz the quiz
* @param object $attempt this attempt just finished
* @param object $context the quiz context
* @param object $cm the coursemodule for this quiz
*
* @return bool true if all necessary messages were sent successfully, else false.
*/
function quiz_send_notification_messages($course, $quiz, $attempt, $context, $cm) {
global $CFG, $DB;
// Do nothing if required objects not present.
if (empty($course) or empty($quiz) or empty($attempt) or empty($context)) {
throw new coding_exception('$course, $quiz, $attempt, $context and $cm must all be set.');
}
$submitter = $DB->get_record('user', array('id' => $attempt->userid), '*', MUST_EXIST);
// Check for confirmation required.
$sendconfirm = false;
$notifyexcludeusers = '';
if (has_capability('mod/quiz:emailconfirmsubmission', $context, $submitter, false)) {
$notifyexcludeusers = $submitter->id;
$sendconfirm = true;
}
// Check for notifications required.
$notifyfields = 'u.id, u.username, u.firstname, u.lastname, u.idnumber, u.email, u.emailstop, ' .
'u.lang, u.timezone, u.mailformat, u.maildisplay';
$groups = groups_get_all_groups($course->id, $submitter->id);
if (is_array($groups) && count($groups) > 0) {
$groups = array_keys($groups);
} else if (groups_get_activity_groupmode($cm, $course) != NOGROUPS) {
// If the user is not in a group, and the quiz is set to group mode,
// then set $groups to a non-existant id so that only users with
// 'moodle/site:accessallgroups' get notified.
$groups = -1;
} else {
$groups = '';
}
$userstonotify = get_users_by_capability($context, 'mod/quiz:emailnotifysubmission',
$notifyfields, '', '', '', $groups, $notifyexcludeusers, false, false, true);
if (empty($userstonotify) && !$sendconfirm) {
return true; // Nothing to do.
}
$a = new stdClass();
// Course info.
$a->coursename = $course->fullname;
$a->courseshortname = $course->shortname;
// Quiz info.
$a->quizname = $quiz->name;
$a->quizreporturl = $CFG->wwwroot . '/mod/quiz/report.php?id=' . $cm->id;
$a->quizreportlink = '<a href="' . $a->quizreporturl . '">' .
format_string($quiz->name) . ' report</a>';
$a->quizurl = $CFG->wwwroot . '/mod/quiz/view.php?id=' . $cm->id;
$a->quizlink = '<a href="' . $a->quizurl . '">' . format_string($quiz->name) . '</a>';
// Attempt info.
$a->submissiontime = userdate($attempt->timefinish);
$a->timetaken = format_time($attempt->timefinish - $attempt->timestart);
$a->quizreviewurl = $CFG->wwwroot . '/mod/quiz/review.php?attempt=' . $attempt->id;
$a->quizreviewlink = '<a href="' . $a->quizreviewurl . '">' .
format_string($quiz->name) . ' review</a>';
// Student who sat the quiz info.
$a->studentidnumber = $submitter->idnumber;
$a->studentname = fullname($submitter);
$a->studentusername = $submitter->username;
$allok = true;
// Send notifications if required.
if (!empty($userstonotify)) {
foreach ($userstonotify as $recipient) {
$allok = $allok && quiz_send_notification($recipient, $submitter, $a);
}
}
// Send confirmation if required. We send the student confirmation last, so
// that if message sending is being intermittently buggy, which means we send
// some but not all messages, and then try again later, then teachers may get
// duplicate messages, but the student will always get exactly one.
if ($sendconfirm) {
$allok = $allok && quiz_send_confirmation($submitter, $a);
}
return $allok;
}
