includes/class.llms.engagements.php
<?php
/**
* LLMS_Engagements class file
*
* @package LifterLMS/Classes
*
* @since 2.3.0
* @version 6.6.0
*/
defined( 'ABSPATH' ) || exit;
/**
* Engagements Class
*
* @since 2.3.0
* @since 3.30.3 Fixed spelling errors.
* @since 5.3.0 Replace singleton code with `LLMS_Trait_Singleton`.
* @since 6.0.0 Changes:
* - Deprecated the `LLMS_Engagements::handle_achievement()` method.
* Use the {@see LLMS_Engagement_Handler::handle_achievement()} method instead.
* - Deprecated the `LLMS_Engagements::handle_certificate()` method.
* Use the {@see LLMS_Engagement_Handler::handle_certificate()} method instead.
* - Deprecated the `LLMS_Engagements::handle_email()` method.
* Use the {@see LLMS_Engagement_Handler::handle_email()} method instead.
* - Deprecated the `LLMS_Engagements::init()` method with no replacement.
* - 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.
*/
class LLMS_Engagements {
use LLMS_Trait_Singleton;
/**
* Enable debug logging
*
* @since 2.7.9
* @var boolean
*/
private $debug = false;
/**
* Constructor
*
* Adds actions to events that trigger engagements.
*
* @since 2.3.0
* @since 6.0.0 Added deprecation warning when using constant `LLMS_ENGAGEMENT_DEBUG`.
* Don't call deprecated `init()` method.
*
* @return void
*/
private function __construct() {
if ( defined( 'LLMS_ENGAGEMENT_DEBUG' ) && LLMS_ENGAGEMENT_DEBUG ) {
_deprecated_function( 'Constant: LLMS_ENGAGEMENT_DEBUG', '6.0.0' );
$this->debug = true;
}
$this->add_actions();
}
/**
* Register all actions that trigger engagements
*
* @since 2.3.0
* @since 3.11.0 Unknown.
* @since 3.39.0 Added `llms_rest_student_registered` as action hook.
* @since 6.0.0 Moved the list of hooks to the `get_trigger_hooks()` method.
*
* @return void
*/
private function add_actions() {
foreach ( $this->get_trigger_hooks() as $action ) {
add_action( $action, array( $this, 'maybe_trigger_engagement' ), 777, 3 );
}
// Handlers are in charge of processing (awarding/sending) the email/cert/achievement.
$handlers = array(
'lifterlms_engagement_send_email' => 'handle_email',
'lifterlms_engagement_award_achievement' => 'handle_achievement',
'lifterlms_engagement_award_certificate' => 'handle_certificate',
);
foreach ( $handlers as $action => $method ) {
/**
* Adds an action for the deprecated method so that `remove_action()` calls
* on the old method will continue to remove the new method.
*
* When we *remove* the deprecated methods we can remove this logic.
*/
add_action( $action, array( $this, $method ) );
// If the above action has been completely removed this will be false and we won't add the new method callback.
$priority = has_action( $action, array( $this, $method ) );
if ( false !== $priority ) {
// Remove the deprecated action.
remove_action( $action, array( $this, $method ) );
// Call the new action at the specified priority. If the old action was restored at a different priority this will retain that customization.
add_action( $action, array( 'LLMS_Engagement_Handler', $method ), $priority );
}
}
add_action( 'deleted_post', array( $this, 'unschedule_delayed_engagements' ), 20, 2 );
}
/**
* Retrieve a group id used when scheduling delayed engagement action triggers.
*
* @since 6.0.0
*
* @param int $engagement_id WP_Post ID of the `llms_engagement` post type.
* @return string
*/
private function get_delayed_group_id( $engagement_id ) {
return sprintf( 'llms_engagement_%d', $engagement_id );
}
/**
* Retrieve engagements based on the trigger type
*
* Joins rather than nested loops and sub queries ftw.
*
* @since 2.3.0
* @since 3.13.1 Unknown.
* @since 6.0.0 Removed engagement debug logging & moved filter onto the return instead of calling in `maybe_trigger_engagement()`.
*
* @param string $trigger_type Name of the trigger to look for.
* @param int|string $related_post_id The WP_Post ID of the related post or an empty string.
* @return object[] {
* Array of objects from the database.
*
* @type int $engagement_id WP_Post ID of the engagement post (email, certificate, achievement).
* @type int $trigger_id WP_Post ID of the llms_engagement post.
* @type string $trigger_event The triggering action (user_registration, course_completed, etc...).
* @type string $event_type The engagement event action (certificate, achievement, email).
* @type int $delay The engagement send delay (in days).
* }
*/
private function get_engagements( $trigger_type, $related_post_id = '' ) {
global $wpdb;
$related_select = '';
$related_join = '';
$related_where = '';
if ( $related_post_id ) {
$related_select = ', relation_meta.meta_value AS related_post_id';
$related_join = "LEFT JOIN $wpdb->postmeta AS relation_meta ON triggers.ID = relation_meta.post_id";
$related_where = $wpdb->prepare( "AND relation_meta.meta_key = '_llms_engagement_trigger_post' AND relation_meta.meta_value = %d", $related_post_id );
}
// phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared
$results = $wpdb->get_results(
$wpdb->prepare(
"SELECT
DISTINCT triggers.ID AS trigger_id
, triggers_meta.meta_value AS engagement_id
, engagements_meta.meta_value AS trigger_event
, event_meta.meta_value AS event_type
, delay.meta_value AS delay
$related_select
FROM $wpdb->postmeta AS engagements_meta
LEFT JOIN $wpdb->posts AS triggers ON triggers.ID = engagements_meta.post_id
LEFT JOIN $wpdb->postmeta AS triggers_meta ON triggers.ID = triggers_meta.post_id
LEFT JOIN $wpdb->posts AS engagements ON engagements.ID = triggers_meta.meta_value
LEFT JOIN $wpdb->postmeta AS event_meta ON triggers.ID = event_meta.post_id
LEFT JOIN $wpdb->postmeta AS delay ON triggers.ID = delay.post_id
$related_join
WHERE
triggers.post_type = 'llms_engagement'
AND triggers.post_status = 'publish'
AND triggers_meta.meta_key = '_llms_engagement'
AND engagements_meta.meta_key = '_llms_trigger_type'
AND engagements_meta.meta_value = %s
AND engagements.post_status = 'publish'
AND event_meta.meta_key = '_llms_engagement_type'
AND delay.meta_key = '_llms_engagement_delay'
$related_where
",
// Prepare variables.
$trigger_type
),
OBJECT
); // no-cache ok.
// phpcs:enable WordPress.DB.PreparedSQL.InterpolatedNotPrepared
/**
* Filters the list of engagements to be triggered for a given trigger type and related post.
*
* @since 6.0.0
*
* @param object[] $results Array of engagement objects.
* @param string $trigger_type Name of the engagement trigger.
* @param int $related_post_id WP_Post ID of the related post.
*/
return apply_filters( 'lifterlms_get_engagements', $results, $trigger_type, $related_post_id );
}
/**
* Retrieve a list of hooks that trigger engagements to be awarded.
*
* @since 6.0.0
*
* @return string[]
*/
protected function get_trigger_hooks() {
$hooks = array(
'lifterlms_access_plan_purchased',
'lifterlms_course_completed',
'lifterlms_course_track_completed',
'lifterlms_lesson_completed',
'lifterlms_product_purchased',
'lifterlms_quiz_completed',
'lifterlms_quiz_failed',
'lifterlms_quiz_passed',
'lifterlms_section_completed',
'lifterlms_user_registered',
'llms_rest_student_registered',
'llms_user_added_to_membership_level',
'llms_user_enrolled_in_course',
);
// If there are any actions registered to this deprecated hook, add it to the list.
if ( has_action( 'lifterlms_created_person' ) ) {
$hooks[] = 'lifterlms_created_person';
}
/**
* Filters the list of hooks which can trigger engagements to be sent/awarded.
*
* @since 2.3.0
*
* @param string[] $hooks List of hook names.
*/
return apply_filters( 'lifterlms_engagement_actions', $hooks );
}
/**
* Include engagement types (excluding email)
*
* @since Unknown
* @deprecated 6.0.0 `LLMS_Engagements::init()` is deprecated with no replacement.
*
* @return void
*/
public function init() {
_deprecated_function( 'LLMS_Engagements::init()', '6.0.0' );
}
/**
* Award an achievement
*
* @since 2.3.0
* @deprecated 6.0.0 `LLMS_Engagements::handle_achievement` is deprecated in favor of `LLMS_Engagement_Handler::handle_achievement`.
*
* @param array $args {
* Indexed array of arguments.
*
* @type int $0 WP_User ID.
* @type int $1 WP_Post ID of the achievement template post.
* @type int|string $2 WP_Post ID of the related post that triggered the award or an empty string.
* @type int $3 WP_Post ID of the engagement post.
* }
* @return void
*/
public function handle_achievement( $args ) {
_deprecated_function( 'LLMS_Engagements::handle_achievement', '6.0.0', 'LLMS_Engagement_Handler::handle_achievement' );
LLMS_Engagement_Handler::handle_achievement( $args );
}
/**
* Award a certificate
*
* @since 2.3.0
* @deprecated 6.0.0 `LLMS_Engagements::handle_certificate` is deprecated in favor of `LLMS_Engagement_Handler::handle_certificate`.
*
* @param array $args {
* Indexed array of arguments.
*
* @type int $0 WP_User ID.
* @type int $1 WP_Post ID of the certificate template post.
* @type int|string $2 WP_Post ID of the related post that triggered the award or an empty string.
* @type int $3 WP_Post ID of the engagement post.
* }
* @return void
*/
public function handle_certificate( $args ) {
_deprecated_function( 'LLMS_Engagements::handle_certificate', '6.0.0', 'LLMS_Engagement_Handler::handle_certificate' );
LLMS_Engagement_Handler::handle_certificate( $args );
}
/**
* Send an email engagement
*
* This is called via do_action() by the 'maybe_trigger_engagement' function in this class.
*
* @since 2.3.0
* @since 3.8.0 Unknown.
* @since 4.4.1 Use postmeta helpers for dupcheck and postmeta insertion.
* Add a return value in favor of `void`.
* Log successes and failures to the `engagement-emails` log file instead of the main `llms` log.
* @since 4.4.3 Fixed different emails triggered by the same related post not sent because of a wrong duplicate check.
* Fixed dupcheck log message and error message which reversed the email and person order.
* @deprecated 6.0.0 `LLMS_Engagements::handle_email` is deprecated in favor of `LLMS_Engagement_Handler::handle_email`.
*
* @param mixed[] $args {
* An array of arguments from the triggering hook.
*
* @type int $0 WP_User ID.
* @type int $1 WP_Post ID of the email.
* @type int|string $2 WP_Post ID of the related triggering post or an empty string for engagements with no related post.
* @type int $3 WP_Post ID of the engagement post.
* }
* @return bool|WP_Error Returns `true` on success, `false` when the email is skipped, and a `WP_Error` when
* the email has failed or is prevented.
*/
public function handle_email( $args ) {
_deprecated_function( 'LLMS_Engagements::handle_email', '6.0.0', 'LLMS_Engagement_Handler::handle_email' );
$res = LLMS_Engagement_Handler::handle_email( $args );
if ( true === $res ) {
return $res;
}
// The new handler returns an array of errors in favor of a single error. Retain the initial return type for this deprecated version.
return $res[0];
}
/**
* Parse incoming hook / callback data to determine if an engagement should be triggered from a given hook.
*
* @since 6.0.0
* @since 6.6.0 Fixed an issue where the `lifterlms_external_engagement_query_arguments` filter
* would not trigger if a 3rd party registered a trigger hook.
*
* @param string $action Action hook name.
* @param array $args Array of arguments passed to the callback function.
* @return array {
* An associative array of parsed data used to trigger the engagement.
*
* @type string $trigger_type The name of the engagement trigger. See `llms_get_engagement_triggers()` for a list of valid triggers.
* @type int $user_id The WP_User ID of the user who the engagement is being awarded or sent to.
* @type int $related_post_id The WP_Post ID of a related post.
* }
*/
private function parse_hook( $action, $args ) {
$parsed = array(
'trigger_type' => null,
'user_id' => null,
'related_post_id' => null,
);
/**
* Allows 3rd parties to hook into the core engagement system by parsing data passed to the hook.
*
* @since 2.3.0
*
* @param array $parsed {
* An associative array of parsed data used to trigger the engagement.
*
* @type string $trigger_type (Required) The name of the engagement trigger. See `llms_get_engagement_triggers()` for a list of valid triggers.
* @type int $user_id (Required) The WP_User ID of the user who the engagement is being awarded or sent to.
* @type int $related_post_id (Optional) The WP_Post ID of a related post.
* }
* @param string $action The name of the hook which triggered the engagement.
* @param array $args The original arguments provided by the triggering hook.
*/
$filtered_parsed = apply_filters(
'lifterlms_external_engagement_query_arguments',
$parsed,
$action,
$args
);
// If valid, return the filtered parsed data.
if ( isset( $filtered_parsed['trigger_type'] ) && isset( $filtered_parsed['user_id'] ) ) {
return $filtered_parsed;
}
// Verify that the action is a supported hook.
if ( ! in_array( $action, $this->get_trigger_hooks(), true ) ) {
return $parsed;
}
// The user registration action doesn't have a related post id.
$related_post_id = isset( $args[1] ) && is_numeric( $args[1] ) ? absint( $args[1] ) : '';
$parsed['user_id'] = absint( $args[0] );
$parsed['trigger_type'] = $this->parse_hook_find_trigger_type( $action, $related_post_id );
$parsed['related_post_id'] = $related_post_id;
return $parsed;
}
/**
* Get the engagement trigger type based on the action and related post id
*
* @since 6.0.0
*
* @param string $action Name of the triggering action hook.
* @param int|string $related_post_id WP_Post ID of the related post or an empty string.
* @return string
*/
private function parse_hook_find_trigger_type( $action, $related_post_id ) {
$trigger_type = '';
switch ( $action ) {
case 'llms_rest_student_registered':
case 'lifterlms_created_person':
case 'lifterlms_user_registered':
$trigger_type = 'user_registration';
break;
case 'lifterlms_course_completed':
case 'lifterlms_course_track_completed':
case 'lifterlms_lesson_completed':
case 'lifterlms_section_completed':
case 'lifterlms_quiz_completed':
case 'lifterlms_quiz_passed':
case 'lifterlms_quiz_failed':
$trigger_type = str_replace( 'lifterlms_', '', $action );
break;
case 'llms_user_added_to_membership_level':
case 'llms_user_enrolled_in_course':
$trigger_type = str_replace( 'llms_', '', get_post_type( $related_post_id ) ) . '_enrollment';
break;
case 'lifterlms_access_plan_purchased':
case 'lifterlms_product_purchased':
$trigger_type = str_replace( 'llms_', '', get_post_type( $related_post_id ) ) . '_purchased';
break;
}
return $trigger_type;
}
/**
* Handles all actions that could potentially trigger an engagement
*
* It will fire or schedule the actions after gathering all necessary data.
*
* @since 2.3.0
* @since 3.11.0 Unknown.
* @since 3.39.0 Treat also `llms_rest_student_registered` action.
* @since 6.0.0 Major refactor to reduce code complexity.
*
* @return void
*/
public function maybe_trigger_engagement() {
// Parse incoming hook data.
$hook = $this->parse_hook( current_filter(), func_get_args() );
// We need a user and a trigger to proceed, related_post is optional though.
if ( ! $hook['user_id'] || ! $hook['trigger_type'] ) {
return;
}
// Gather triggerable engagements matching the supplied criteria.
$engagements = $this->get_engagements( $hook['trigger_type'], $hook['related_post_id'] );
// Loop through the retrieved engagements and trigger them.
foreach ( $engagements as $engagement ) {
$handler = $this->parse_engagement( $engagement, $hook );
$this->trigger_engagement( $handler, $engagement->delay );
}
}
/**
* Parse engagement objects from the DB and return data needed to trigger the engagements.
*
* @since 6.0.0
* @since 6.6.0 Fixed an issue where the `lifterlms_external_engagement_handler_arguments` filter
* would not trigger if a 3rd party registered an engagement type.
*
* @param object $engagement The engagement object from the `get_engagements()` query.
* @param array $trigger_data Parsed hook data from `parse_hook()`.
* @return array {
* An associative array of parsed data used to trigger the engagement.
*
* @type string $handler_action Hook name of the action that will handle awarding the sending the engagement.
* @type array $handler_args Arguments passed to the `$handler_action` callback.
* }
*/
private function parse_engagement( $engagement, $trigger_data ) {
$parsed = array(
'handler_action' => null,
'handler_args' => null,
);
/**
* Enable 3rd parties to parse custom engagement types.
*
* @since 2.3.0
*
* @param array $parsed {
* An associative array of parsed data used to trigger the engagement.
*
* @type string $handler_action (Required) Hook name of the action that will handle awarding the sending the engagement.
* @type array $handler_args (Required) Arguments passed to the `$handler_action` callback.
* }
* @param object $engagement The engagement object from the `get_engagements()` query.
* @param int $user_id WP_User ID who will be awarded the engagement.
* @param int $related_post_id WP_Post ID of the related post.
* @param string $event_type The type of engagement event.
*/
$filtered_parsed = apply_filters(
'lifterlms_external_engagement_handler_arguments',
$parsed,
$engagement,
$trigger_data['user_id'],
$trigger_data['related_post_id'],
$engagement->event_type
);
// If valid, return the filtered parsed data.
if ( isset( $filtered_parsed['handler_action'] ) && isset( $filtered_parsed['handler_args'] ) ) {
return $filtered_parsed;
}
// Verify that the engagement event type is supported.
if ( ! array_key_exists( $engagement->event_type, llms_get_engagement_types() ) ) {
return $parsed;
}
$parsed['handler_args'] = array(
$trigger_data['user_id'],
$engagement->engagement_id,
$trigger_data['related_post_id'],
absint( $engagement->trigger_id ),
);
/**
* @todo Fix this
*
* If there's no related post id we have to send one anyway for certs to work.
*
* This would only be for registration events @ version 2.3.0 so we pass the engagement_id twice until we find a better solution.
*/
if ( 'certificate' === $engagement->event_type && empty( $parsed['handler_args'][2] ) ) {
$parsed['handler_args'][2] = $parsed['handler_args'][1];
}
$parsed['handler_action'] = sprintf(
'lifterlms_engagement_%1$s_%2$s',
'email' === $engagement->event_type ? 'send' : 'award',
$engagement->event_type
);
return $parsed;
}
/**
* Triggers or schedules an engagement
*
* @since 6.0.0
*
* @param array $data Handler data from `parse_engagement()`.
* @param int $delay The engagement send delay (in days).
* @return void
*/
private function trigger_engagement( $data, $delay ) {
// Can't proceed without an action and a handler.
if ( empty( $data['handler_action'] ) || empty( $data['handler_args'] ) ) {
return;
}
// If we have a delay, schedule the engagement handler.
$delay = absint( $delay );
if ( $delay ) {
as_schedule_single_action(
time() + ( DAY_IN_SECONDS * $delay ),
$data['handler_action'],
array( $data['handler_args'] ),
! empty( $data['handler_args'][3] ) ? $this->get_delayed_group_id( $data['handler_args'][3] ) : null
);
} else {
/**
* Skip processing checks for immediate engagements.
*
* We know the user exists (because they're currently logged in) and we don't have to run
* publish/existence checks on all the related posts because the `get_engagement()` query takes care
* of that already.
*/
add_filter( 'llms_skip_engagement_processing_checks', '__return_true' );
do_action( $data['handler_action'], $data['handler_args'] );
remove_filter( 'llms_skip_engagement_processing_checks', '__return_true' );
}
}
/**
* Unschedule all scheduled actions for a delayed engagement
*
* This is the callback function for deleted engagement posts.
*
* The `deleted_post` action param `$post` has been added since WordPress 5.5.0.
*
* @since 6.0.0
*
* @param int $post_id WP_Post ID.
* @param WP_Post|null $post Post object of the deleted post.
* @return void
*/
public function unschedule_delayed_engagements( $post_id, $post = null ) {
// @todo Remove compatibility with WP < 5.5 when bumping the minimum WP required version to 5.5+
$post_type = $post ? $post->post_type : get_post_type( $post_id );
if ( 'llms_engagement' === $post_type ) {
as_unschedule_all_actions( '', array(), $this->get_delayed_group_id( $post_id ) );
}
}
/**
* Log debug data to the WordPress debug.log file
*
* @since 2.7.9
* @since 3.12.0 Unknown.
* @deprecated 6.0.0 Engagement debug logging is removed. Use `llms_log()` directly instead.
*
* @param mixed $log Data to write to the log.
* @return void
*/
public function log( $log ) {
_deprecated_function( 'LLMS_Engagements::log()', '6.0.0', 'llms_log()' );
if ( $this->debug ) {
llms_log( $log, 'engagements' );
}
}
}