stm_lms_quiz_{dynamic}

Description

Usage

add_action( 'stm_lms_quiz_{dynamic}', 'your_function_name', 10, 3 );

Parameters

$user_id (mixed)

The user ID of the person taking the quiz.

$quiz_id (mixed)

This parameter holds the unique identifier for the user who has completed the quiz.

$user_quiz (mixed)

This parameter represents the unique identifier of the quiz being completed.

Examples

/**
 * Example of using the 'stm_lms_quiz_{dynamic}' action hook.
 * This function demonstrates how to hook into the action fired after a quiz is completed
 * and potentially perform additional actions based on the quiz status.
 *
 * The dynamic part of the hook ('{dynamic}') refers to the status of the quiz,
 * for example 'stm_lms_quiz_completed', 'stm_lms_quiz_failed', etc.
 */
add_action( 'stm_lms_quiz_completed', 'my_custom_quiz_completion_handler', 10, 3 );

/**
 * Custom handler for the stm_lms_quiz_completed action.
 *
 * @param int $user_id The ID of the user who took the quiz.
 * @param int $quiz_id The ID of the quiz taken.
 * @param float $progress The progress of the user in the quiz (e.g., percentage).
 */
function my_custom_quiz_completion_handler( $user_id, $quiz_id, $progress ) {
	// For demonstration purposes, let's assume we want to send a notification
	// to the site administrator if a user achieves a perfect score.

	$perfect_score_threshold = 100; // Assuming progress is a percentage

	if ( $progress >= $perfect_score_threshold ) {
		// Fetch user and quiz details for a more informative notification
		$user_info = get_userdata( $user_id );
		$quiz_title = get_the_title( $quiz_id );

		if ( $user_info && $quiz_title ) {
			$admin_email = get_option( 'admin_email' );
			$subject = sprintf(
				esc_html__( 'Perfect Score on Quiz "%s" by %s', 'your-text-domain' ),
				$quiz_title,
				$user_info->display_name
			);
			$message = sprintf(
				esc_html__( 'User "%s" (ID: %d) achieved a perfect score of %s%% on quiz "%s" (ID: %d).', 'your-text-domain' ),
				$user_info->display_name,
				$user_id,
				$progress,
				$quiz_title,
				$quiz_id
			);

			// In a real scenario, you might want to use wp_mail() for sending emails.
			// For this example, we'll just log it.
			error_log( "Quiz Perfect Score Alert: Subject - {$subject}, Message - {$message}" );

			// Example of sending an email:
			// wp_mail( $admin_email, $subject, $message );
		}
	}

	// You could also perform other actions here, such as:
	// - Granting a badge to the user.
	// - Enrolling the user in a follow-up course.
	// - Updating custom metadata for the user or quiz.
}

/**
 * Example for a different quiz status, e.g., when a quiz is failed.
 * The dynamic part of the hook is 'failed'.
 */
add_action( 'stm_lms_quiz_failed', 'my_custom_quiz_failure_handler', 10, 3 );

/**
 * Custom handler for the stm_lms_quiz_failed action.
 *
 * @param int $user_id The ID of the user who took the quiz.
 * @param int $quiz_id The ID of the quiz taken.
 * @param float $progress The progress of the user in the quiz (e.g., percentage).
 */
function my_custom_quiz_failure_handler( $user_id, $quiz_id, $progress ) {
	// Perhaps we want to automatically enroll the user in a remedial lesson
	// or send them a study guide if they fail.

	$user_info = get_userdata( $user_id );
	$quiz_title = get_the_title( $quiz_id );

	if ( $user_info && $quiz_title ) {
		$subject = sprintf(
			esc_html__( 'Needs Improvement on Quiz "%s" by %s', 'your-text-domain' ),
			$quiz_title,
			$user_info->display_name
		);
		$message = sprintf(
			esc_html__( 'User "%s" (ID: %d) did not pass quiz "%s" (ID: %d) with a score of %s%%. Consider offering additional resources.', 'your-text-domain' ),
			$user_info->display_name,
			$user_id,
			$quiz_title,
			$quiz_id,
			$progress
		);

		error_log( "Quiz Failure Alert: Subject - {$subject}, Message - {$message}" );

		// Example: Find and enroll in a remedial lesson (requires custom logic)
		// $remedial_lesson_id = get_remedial_lesson_for_quiz( $quiz_id );
		// if ( $remedial_lesson_id ) {
		//     enroll_user_in_lesson( $user_id, $remedial_lesson_id );
		// }
	}
}

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/integrations/masterstudy-lms/actions/masterstudy-markcoursecomplete.php:153
uncanny-automator-pro/src/integrations/masterstudy-lms/actions/masterstudy-mark-quiz-complete.php:147

public function mark_course_complete( $user_id, $action_data, $recipe_id, $args ) {

		$course_id  = $action_data['meta'][ $this->action_meta ];
		$helpers    = new Masterstudy_Helpers( false );
		$curriculum = $helpers->get_course_curriculum_materials( $course_id );

		if ( empty( $curriculum ) ) {
			$action_data['complete_with_errors'] = true;
			$error                               = _x( 'Course does not have any lessons or quizzes to complete.', 'Masterstudy LMS - Complete course action', 'uncanny-automator' );
			Automator()->complete_action( $user_id, $action_data, $recipe_id, $error );
			return;
		}

		// Enroll the user is the course if they are not already enrolled
		$course = stm_lms_get_user_course( $user_id, $course_id, array( 'user_course_id' ) );
		if ( ! count( $course ) ) {
			STM_LMS_Course::add_user_course( $course_id, $user_id, STM_LMS_Course::item_url( $course_id, '' ), 0 );
			STM_LMS_Course::add_student( $course_id );
		}

		foreach ( $curriculum as $post ) {

			if ( 'stm-lessons' === $post['post_type'] ) {

				// Complete Lesson
				$lesson_id = $post['post_id'];

				if ( STM_LMS_Lesson::is_lesson_completed( $user_id, $course_id, $lesson_id ) ) {
					continue;
				};

				$end_time   = time();
				$start_time = get_user_meta( $user_id, "stm_lms_course_started_{$course_id}_{$lesson_id}", true );

				stm_lms_add_user_lesson( compact( 'user_id', 'course_id', 'lesson_id', 'start_time', 'end_time' ) );
				STM_LMS_Course::update_course_progress( $user_id, $course_id );

				do_action( 'stm_lms_lesson_passed', $user_id, $lesson_id );

				delete_user_meta( $user_id, "stm_lms_course_started_{$course_id}_{$lesson_id}" );
			}

			if ( 'stm-quizzes' === $post['post_type'] ) {

				// Complete quiz
				$quiz_id = $post['post_id'];

				if ( STM_LMS_Quiz::quiz_passed( $quiz_id, $user_id ) ) {
					continue;
				}

				$progress  = 100;
				$status    = 'passed';
				$user_quiz = compact( 'user_id', 'course_id', 'quiz_id', 'progress', 'status' );
				stm_lms_add_user_quiz( $user_quiz );
				stm_lms_get_delete_user_quiz_time( $user_id, $quiz_id );

				STM_LMS_Course::update_course_progress( $user_id, $course_id );

				$user_quiz['progress'] = round( $user_quiz['progress'], 1 );
				do_action( 'stm_lms_quiz_' . $status, $user_id, $quiz_id, $user_quiz['progress'] );

			}
		}

		Automator()->complete_action( $user_id, $action_data, $recipe_id );
	}

Related Hooks

• stm_lms_lesson_passed — fires_nearby