Alert: This function’s access is marked private. This means it is not intended for use by plugin or theme developers, only in other core functions. It is listed here for completeness.

LLMS_Engagements::parse_engagement( object $engagement, array $trigger_data )

Parse engagement objects from the DB and return data needed to trigger the engagements.


Parameters Parameters

$engagement

(object) (Required) The engagement object from the get_engagements() query.

$trigger_data

(array) (Required) Parsed hook data from parse_hook().


Top ↑

Return Return

(array) An associative array of parsed data used to trigger the engagement.

  • 'handler_action'
    (string) Hook name of the action that will handle awarding the sending the engagement.
  • 'handler_args'
    (array) Arguments passed to the $handler_action callback.


Top ↑

Source Source

File: includes/class.llms.engagements.php

	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;

	}


Top ↑

Changelog Changelog

Changelog
Version Description
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.
6.0.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

You must log in before being able to contribute a note or feedback.