fix(notifications): add certificate earned email notification and engagement trigger

.changelogs/issue-3143.yml

@@ -0,0 +1,3 @@
+significance: minor
+type: added
+entry: "Added email support to the 'Certificate Earned' notification and added a new 'Student earns a certificate' engagement trigger."

includes/class.llms.engagements.php

@@ -5,7 +5,7 @@
  * @package LifterLMS/Classes
  *
  * @since 2.3.0
- * @version 6.6.0
+ * @version 10.0.6
  */
 
 defined( 'ABSPATH' ) || exit;
@@ -27,6 +27,7 @@
  *              - Deprecated the `LLMS_Engagements::log()` method.
  *                Engagement debug logging is removed. Use the {@see llms_log()} function directly instead.
  *              - Removed the deprecated `LLMS_Engagements::$_instance` property.
+ * @since 10.0.6 Added `llms_user_earned_certificate` as an engagement trigger hook.
  */
 class LLMS_Engagements {
 
@@ -223,6 +224,7 @@ protected function get_trigger_hooks() {
 
 		$hooks = array(
 			'lifterlms_access_plan_purchased',
+			'llms_user_earned_certificate',
 			'lifterlms_course_completed',
 			'lifterlms_course_track_completed',
 			'lifterlms_lesson_completed',
@@ -446,6 +448,10 @@ private function parse_hook_find_trigger_type( $action, $related_post_id ) {
 			case 'lifterlms_product_purchased':
 				$trigger_type = str_replace( 'llms_', '', get_post_type( $related_post_id ) ) . '_purchased';
 				break;
+
+			case 'llms_user_earned_certificate':
+				$trigger_type = 'certificate_earned';
+				break;
 		}
 
 		return $trigger_type;

includes/llms.functions.core.php

@@ -443,6 +443,7 @@ function llms_get_donut( $percentage, $text = '', $size = 'default', $classes =
  * @return array
  * @since 3.1.0
  * @since 3.24.1
+ * @since 10.0.6 Added `certificate_earned` trigger.
  */
 function llms_get_engagement_triggers() {
 	/**
@@ -460,6 +461,7 @@ function llms_get_engagement_triggers() {
 			'course_enrollment'      => __( 'Student enrolls in a course', 'lifterlms' ),
 			'course_purchased'       => __( 'Student purchases a course', 'lifterlms' ),
 			'course_completed'       => __( 'Student completes a course', 'lifterlms' ),
+			'certificate_earned'    => __( 'Student earns a certificate', 'lifterlms' ),
 			// 'days_since_login' => __( 'Days since user last logged in', 'lifterlms' ), // @todo.
 			'lesson_completed'       => __( 'Student completes a lesson', 'lifterlms' ),
 			'quiz_completed'         => __( 'Student completes a quiz', 'lifterlms' ),

includes/notifications/controllers/class.llms.notification.controller.certificate.earned.php

@@ -5,7 +5,7 @@
  * @package LifterLMS/Notifications/Controllers/Classes
  *
  * @since 3.8.0
- * @version 3.8.0
+ * @version 10.0.6
  */
 
 defined( 'ABSPATH' ) || exit;
@@ -99,7 +99,7 @@ public function get_title() {
 	 * @param    string $type  notification type id
 	 * @return   array
 	 * @since    3.8.0
-	 * @version  3.8.0
+	 * @version  10.0.6
 	 */
 	protected function set_subscriber_options( $type ) {
 
@@ -111,6 +111,11 @@ protected function set_subscriber_options( $type ) {
 				$options[] = $this->get_subscriber_option_array( 'student', 'yes' );
 				break;
 
+			case 'email':
+				$options[] = $this->get_subscriber_option_array( 'student', 'yes' );
+				$options[] = $this->get_subscriber_option_array( 'custom', 'no' );
+				break;
+
 		}
 
 		return $options;
@@ -123,11 +128,12 @@ protected function set_subscriber_options( $type ) {
 	 *
 	 * @return   array        associative array, keys are the ID/db type, values should be translated display types
 	 * @since    3.8.0
-	 * @version  3.8.0
+	 * @version  10.0.6
 	 */
 	protected function set_supported_types() {
 		return array(
 			'basic' => __( 'Popup', 'lifterlms' ),
+			'email' => __( 'Email', 'lifterlms' ),
 		);
 	}
 }

includes/notifications/views/class.llms.notification.view.certificate.earned.php

@@ -5,7 +5,7 @@
  * @package LifterLMS/Notifications/Views/Classes
  *
  * @since 3.8.0
- * @version 6.0.0
+ * @version 10.0.6
  */
 
 defined( 'ABSPATH' ) || exit;
@@ -78,10 +78,15 @@ private function get_mini_html( $title ) {
 	 * Setup body content for output.
 	 *
 	 * @since 3.8.0
+	 * @version 10.0.6
 	 *
 	 * @return string
 	 */
 	protected function set_body() {
+		if ( 'email' === $this->notification->get( 'type' ) ) {
+			return '<p>' . sprintf( __( 'Congratulations! You earned %s.', 'lifterlms' ), '{{CERTIFICATE_TITLE}}' ) . '</p>'
+				. '<p><a href="{{CERTIFICATE_URL}}">' . __( 'View Full Certificate', 'lifterlms' ) . '</a></p>';
+		}
 		return '{{MINI_CERTIFICATE}}';
 	}
 
@@ -209,11 +214,12 @@ private function set_merge_data_student_name( $cert ) {
 	 * Setup notification subject for output.
 	 *
 	 * @since 3.8.0
+	 * @version 10.0.6
 	 *
 	 * @return string
 	 */
 	protected function set_subject() {
-		return '';
+		return sprintf( __( 'You\'ve earned a certificate: %s', 'lifterlms' ), '{{CERTIFICATE_TITLE}}' );
 	}
 
 	/**
@@ -231,6 +237,7 @@ protected function set_title() {
 	 * Defines field support for the view.
 	 *
 	 * @since 3.8.0
+	 * @version 10.0.6
 	 *
 	 * @return array
 	 */
@@ -241,6 +248,12 @@ protected function set_supported_fields() {
 				'title' => true,
 				'icon'  => true,
 			),
+			'email' => array(
+				'body'    => true,
+				'icon'    => false,
+				'subject' => true,
+				'title'   => true,
+			),
 		);
 	}
 }

tests/phpunit/unit-tests/notifications/class-llms-test-notification-certificate-earned.php

@@ -7,6 +7,7 @@
  * @group notifications
  *
  * @since 6.0.0
+ * @since 10.0.6 Added tests for email notification support.
  */
 class LLMS_Test_Notification_Certificate_Earned extends LLMS_NotificationTestCase {
 
@@ -94,4 +95,67 @@ public function test_set_merge_data() {
 
 	}
 
+	/**
+	 * Test that the email notification type is supported.
+	 *
+	 * @since 10.0.6
+	 *
+	 * @return void
+	 */
+	public function test_email_supported() {
+
+		$controller = $this->get_controller();
+		$types      = LLMS_Unit_Test_Util::call_method( $controller, 'get_supported_types' );
+
+		$this->assertArrayHasKey( 'email', $types );
+		$this->assertArrayHasKey( 'basic', $types );
+
+	}
+
+	/**
+	 * Test email subscriber options.
+	 *
+	 * @since 10.0.6
+	 *
+	 * @return void
+	 */
+	public function test_email_subscriber_options() {
+
+		$controller = $this->get_controller();
+		$options    = LLMS_Unit_Test_Util::call_method( $controller, 'get_subscriber_options', array( 'email' ) );
+
+		$types = array();
+		foreach ( $options as $option ) {
+			$types[] = $option['subscriber_type'];
+		}
+
+		$this->assertContains( 'student', $types );
+		$this->assertContains( 'custom', $types );
+
+	}
+
+	/**
+	 * Test email view subject and body.
+	 *
+	 * @since 10.0.6
+	 *
+	 * @return void
+	 */
+	public function test_email_view() {
+
+		$notification = $this->get_notification();
+		$notification->set( 'type', 'email' );
+
+		$view = llms()->notifications()->get_view( $notification );
+
+		$subject = LLMS_Unit_Test_Util::call_method( $view, 'set_subject' );
+		$body    = LLMS_Unit_Test_Util::call_method( $view, 'set_body' );
+		$title   = LLMS_Unit_Test_Util::call_method( $view, 'set_title' );
+
+		$this->assertStringContainsString( '{{CERTIFICATE_TITLE}}', $subject );
+		$this->assertStringContainsString( '{{CERTIFICATE_URL}}', $body );
+		$this->assertStringContainsString( 'certificate', strtolower( $title ) );
+
+	}
+
 }