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

[faisalahammad]

Summary

This PR adds email support to the existing "Certificate Earned" notification and introduces a new "Student earns a certificate" engagement trigger. Previously, the certificate earned notification only supported a popup, and there was no way to fire follow-up engagements when a certificate was awarded.

Fixes #3143

Changes

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

Before:

protected function set_supported_types() {
    return array(
        'basic' => __( 'Popup', 'lifterlms' ),
    );
}

After:

protected function set_supported_types() {
    return array(
        'basic' => __( 'Popup', 'lifterlms' ),
        'email' => __( 'Email', 'lifterlms' ),
    );
}

Why: The controller already hooked into llms_user_earned_certificate; adding the email type lets the existing email processor send the notification without any processor changes.

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

Before:

protected function set_subject() {
    return '';
}

protected function set_body() {
    return '{{MINI_CERTIFICATE}}';
}

protected function set_supported_fields() {
    return array(
        'basic' => array(
            'body'  => true,
            'title' => true,
            'icon'  => true,
        ),
    );
}

After:

protected function set_subject() {
    return sprintf( __( 'You\'ve earned a certificate: %s', 'lifterlms' ), '{{CERTIFICATE_TITLE}}' );
}

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}}';
}

protected function set_supported_fields() {
    return array(
        'basic' => array(
            'body'  => true,
            'title' => true,
            'icon'  => true,
        ),
        'email' => array(
            'body'    => true,
            'icon'    => false,
            'subject' => true,
            'title'   => true,
        ),
    );
}

Why: The view now provides a real email subject and body, while keeping the popup mini-cert preview unchanged. The merge codes for certificate title and URL were already available.

includes/llms.functions.core.php

Before:

'course_completed'       => __( 'Student completes a course', 'lifterlms' ),
// 'days_since_login' => __( 'Days since user last logged in', 'lifterlms' ), // @todo.
'lesson_completed'       => __( 'Student completes a lesson', 'lifterlms' ),

After:

'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' ),

Why: Registers the new engagement trigger in the admin dropdown so site owners can build engagements that fire after a certificate is earned.

includes/class.llms.engagements.php

Before:

$hooks = array(
    'lifterlms_access_plan_purchased',
    'lifterlms_course_completed',
    ...
);

After:

$hooks = array(
    'lifterlms_access_plan_purchased',
    'llms_user_earned_certificate',
    'lifterlms_course_completed',
    ...
);

Plus a new case in parse_hook_find_trigger_type():

case 'llms_user_earned_certificate':
    $trigger_type = 'certificate_earned';
    break;

Why: The engagement engine needs to listen to the existing llms_user_earned_certificate action and map it to the new certificate_earned trigger type so configured engagements can run.

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

Added three new tests:

• test_email_supported() — confirms the controller supports both basic and email types.
• test_email_subscriber_options() — confirms the email type has student and custom subscribers.
• test_email_view() — confirms the email view returns subject, body, and title content with the expected merge codes.

Why: Covers the new email behavior and ensures the notification UI fields are wired correctly.

Testing

Test 1: Email notification for certificate earned

1. Go to LifterLMS → Settings → Notifications → Certificate Earned.
2. Switch to the Email tab and enable it for the Student subscriber.
3. Complete a course that awards a certificate.
4. Confirm the student receives an email with the certificate title and a link to view it.

Result: Works as expected

Test 2: New engagement trigger

1. Go to LifterLMS → Engagements → Add Engagement.
2. Select "Student earns a certificate" as the trigger.
3. Set the action to "Send an Email".
4. Complete a course that awards a certificate.
5. Confirm the follow-up email is sent.

Result: Works as expected